在AnQiCMS中，将Markdown格式的文本插入内容并正确渲染为HTML，是内容运营者提高效率和产出高质量页面的重要方式。AnQiCMS内置了对Markdown编辑和渲染的支持，让您在撰写内容时既能享受Markdown的简洁高效，又能确保最终页面输出美观且结构化的HTML。

启用Markdown编辑器

要开始在AnQiCMS中使用Markdown，首先需要确保其编辑器功能已启用。这个设置通常位于系统的核心配置中：

您可以通过访问 AnQiCMS后台，进入 全局设置，然后找到 内容设置 选项。在这里，您会看到一个用于启用或禁用Markdown编辑器的选项。勾选启用后，在您发布或编辑文章、单页面等内容时，内容编辑器就会切换到Markdown模式，方便您以Markdown语法进行内容创作。

启用Markdown编辑器后，您在后台编辑内容时，就可以直接使用Markdown语法进行排版。例如，使用**粗体**表示加粗，# 标题表示一级标题，- 列表项表示无序列表，以及代码块、链接、图片等Markdown常见元素。

在内容中插入Markdown文本

AnQiCMS支持在多种内容类型中插入Markdown文本，包括：

  • 文章内容： 在发布新文章或编辑现有文章时，可以在“文档内容”区域直接输入Markdown文本。
  • 单页面内容： 对于“关于我们”、“联系我们”等单页面，其内容也可以通过Markdown编辑器进行撰写。
  • 分类描述/内容： 在管理文章或产品分类时，其“分类简介”或“分类内容”字段同样支持Markdown格式。
  • 标签描述/内容： 如果您希望给某个标签添加更详细的描述，也可以在“标签描述”或“标签内容”字段中使用Markdown。

通过Markdown编写内容，不仅能够让您专注于文本本身，避免繁琐的鼠标操作，还能保证内容结构清晰，为后续的样式渲染打下良好基础。

确保Markdown正确渲染为HTML

当您在后台启用了Markdown编辑器并使用Markdown语法撰写内容后，AnQiCMS通常会自动将其渲染为HTML，以便在前端页面上正确显示。

对于文章、分类和单页面等主要内容字段（例如archiveDetail、categoryDetail、pageDetail等标签中的Content字段），当Markdown编辑器处于启用状态时，系统会在模板渲染时自动将Markdown文本转换为HTML。这意味着您在模板中直接调用这些字段时，无需额外操作，Markdown内容就能以HTML形式展现。

例如，在文章详情页的模板中，如果您的文章内容使用了Markdown，以下调用方式：

<div>
    {%- archiveDetail articleContent with name="Content" %}
    {{articleContent|safe}}
</div>

这里的{{articleContent|safe}}就会将已由AnQiCMS后端转换好的HTML安全地输出到页面上。|safe过滤器在这里是关键，它指示模板引擎将内容作为安全的HTML处理，避免被二次转义。

然而，在某些特定场景下，您可能需要手动控制Markdown到HTML的转换过程。这包括：

  1. Markdown编辑器未启用，但某个字段包含Markdown文本： 如果您在后台禁用了Markdown编辑器，但某个内容字段仍旧包含Markdown文本，系统将不会自动渲染。
  2. 自定义字段包含Markdown文本： 对于通过“内容模型自定义字段”添加的字段，系统可能不会默认进行Markdown渲染。
  3. 需要明确控制渲染时机： 您希望对某个字段的内容进行显式地Markdown渲染。

在这种情况下，您可以使用AnQiCMS提供的render过滤器配合safe过滤器，来手动将Markdown文本转换为HTML并安全输出。例如，如果您的自定义字段introduction中包含Markdown文本：

{% archiveDetail introduction with name="introduction" %}
{{introduction|render|safe}}

这里的|render过滤器会执行Markdown到HTML的转换，而|safe则确保转换后的HTML能够被浏览器正确解析而不会被转义。

增强渲染效果：支持数学公式与流程图

新版本的AnQiCMS还支持在Markdown内容中插入数学公式和流程图。这些高级功能需要借助前端第三方库来正确渲染。您需要在网站模板的base.html文件的<head>标签内，引入相应的CDN资源：

  1. Markdown默认样式： 为了让Markdown内容在页面上有更好的视觉效果，可以引入GitHub风格的Markdown CSS。

    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/github-markdown-css/5.2.0/github-markdown.min.css" crossorigin="anonymous" referrerpolicy="no-referrer" />

  2. 数学公式渲染： 如果您的内容包含LaTeX等数学公式，需要引入MathJax库进行渲染。

    <script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>

  3. 流程图渲染： 对于Mermaid语法的流程图，则需要引入Mermaid库。

    <script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
    mermaid.initialize({ startOnLoad: true });
</script>

将这些代码添加到您网站模板（通常是base.html）的<head>区域后，您在Markdown中撰写的数学公式和流程图就能在前端页面上得到专业且美观的展示。

总结

AnQiCMS通过内置的Markdown编辑器和灵活的渲染机制，为用户提供了高效、便捷且功能强大的内容创作体验。无论是简单的文本排版，还是复杂的数学公式和流程图，AnQiCMS都能帮助您轻松驾驭，并确保内容以**状态呈现在访问者面前。只要您按照上述步骤启用编辑器、正确撰写内容，并在必要时合理运用render|safe过滤器及外部资源，就能充分发挥Markdown在AnQiCMS中的潜力。

常见问题 (FAQ)

  1. 问：我已经在后台启用了Markdown编辑器，并在文章中使用了Markdown语法，但为什么文章在前端仍然显示为原始Markdown文本，没有被转换为HTML？ 答：这通常是由于模板中内容输出方式不正确导致的。请检查您的模板代码，确保在输出Markdown内容字段时，使用了|safe过滤器。例如，应使用{{articleContent|safe}}，而不是仅仅{{articleContent}}。如果内容不是通过Content这类默认会自动渲染的字段输出，或者Markdown编辑器未启用，您还需要在|safe之前添加|render过滤器，如{{customField|render|safe}}。

  2. 问：我想在自定义内容模型中添加一个“产品特色”字段，并允许在这个字段中输入Markdown文本。我应该如何确保它在前端正确渲染？ 答：对于自定义字段，即使Markdown编辑器已启用，系统可能也不会自动进行Markdown到HTML的转换。因此，在您的模板中调用这个自定义字段时，建议始终显式使用|render|safe过滤器。例如，如果您的自定义字段名为product_features，在模板中调用时，应写成{{item.product_features|render|safe}}。

  3. 问：我按照文档添加了MathJax和Mermaid的CDN代码，但Markdown中的数学公式和流程图仍然没有显示或显示不正确，这是怎么回事？ 答：请仔细检查您是否将CDN代码正确放置在base.html文件的<head>标签内。其次，确保您的Markdown语法是正确的，例如Mermaid流程图需要以graph TD...这样的结构开始。有时候，浏览器的缓存也可能导致问题，尝试清除浏览器缓存或使用无痕模式访问页面。如果问题依然存在，可能是CDN加载失败或与您网站的其他JavaScript代码存在冲突，您可以查看浏览器开发者工具的控制台是否有报错信息。