在 AnQiCMS 中，Markdown 是一种高效且广受欢迎的内容创作方式。它以简洁的标记语法，让创作者能够专注于内容本身，而无需被复杂的排版工具所困扰。然而，将这些简洁的 Markdown 文本呈现在用户面前的浏览器中，需要经过 AnQiCMS 后台和前端模板的协同处理。理解这个过程，能帮助您更好地利用 AnQiCMS 的内容管理能力，确保您的内容以**状态展示。

启用 Markdown 编辑器：内容创作的第一步

首先，在 AnQiCMS 后台启用 Markdown 编辑器是使用 Markdown 撰写内容的基础。通常，您可以在“全局设置”下的“内容设置”中找到相应的选项来开启它。这一步非常关键，它告诉系统您将使用 Markdown 语法来编写文章、页面或分类的详细内容。一旦启用，您在文档内容、页面内容或分类内容等主要编辑区域输入 Markdown 文本后，系统便会识别并为后续的渲染做准备。

例如，您在文章内容中输入：

# 欢迎来到 AnQiCMS
这是一个 **强大** 的内容管理系统。

- 部署简单
- 功能丰富
- 扩展性强

在前端页面上，我们期望看到的是标题、加粗文本和列表，而不是原始的 Markdown 符号。

内容撰写与自动解析：Markdown 到 HTML 的初步转换

当您在 AnQiCMS 的编辑器中输入 Markdown 内容并保存后，系统在后台会对这些内容进行初步解析和转换。对于文档、页面和分类等主内容字段（如 archive.Content、page.Content、category.Content），AnQiCMS 默认在启用 Markdown 编辑器后，会自动将 Markdown 文本转换为标准的 HTML 结构。这意味着，您无需手动执行转换操作，系统会智能地完成这一任务。

例如，您在模板中直接调用文章内容：

<div>
    {{ archive.Content }}
</div>

此时，archive.Content 变量已经包含了由 Markdown 转换而来的 HTML 代码。

模板层的渲染控制：确保 HTML 正确显示

尽管 AnQiCMS 会自动进行 Markdown 到 HTML 的转换，但在前端模板层面，仍需要一些额外的处理来确保内容能够正确、安全地显示。

1. 使用 |safe 过滤器防止二次转义

Markdown 转换后的内容本质上是包含 HTML 标签的字符串。如果在模板中直接输出这些字符串而没有做特殊处理，模板引擎可能会为了安全起见，将其中的 <、> 等字符转义为 &lt;、&gt;。这将导致页面显示的是原始的 HTML 代码，而不是经过渲染的视觉效果。

因此，在 AnQiCMS 模板中，任何包含 HTML 内容的变量（包括由 Markdown 转换而来的 HTML），都需要使用 |safe 过滤器。这个过滤器告诉模板引擎，该变量中的内容是安全的 HTML，可以直接输出，无需进行额外的转义。

正确的使用方式是：

<div>
    {{ archive.Content|safe }}
</div>

2. 灵活运用 |render 过滤器进行手动控制

在大多数情况下，AnQiCMS 会在后台自动处理 Markdown 渲染。但如果您的 Markdown 内容存储在自定义字段中，或者您需要更精确地控制渲染时机，|render 过滤器就派上用场了。

例如，如果您自定义了一个名为 introduction 的字段，用于存储 Markdown 格式的简介：

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

这里的 |render 过滤器会强制将 introduction 变量中的 Markdown 文本渲染为 HTML。它还接受 render=true 或 render=false 参数，可以更明确地指定是否进行渲染：

  • render=true：强制对内容进行 Markdown 到 HTML 的转换。
  • render=false：不进行 Markdown 转换，直接返回原始内容。

例如，手动指定渲染：

<div>文档内容：{% archiveDetail archiveContent with name="Content" render=true %}{{archiveContent|safe}}</div>

3. 引入外部资源：数学公式与流程图的完整呈现

基础的 Markdown 语法转换为 HTML 即可正常显示，但对于更高级的功能，如数学公式（LaTeX）和流程图（Mermaid），仅仅转换为 HTML 是不够的。它们需要借助额外的 JavaScript 库在浏览器端进行解析和渲染。

AnQiCMS 的文档中明确提到了如何集成这些功能，您需要在模板的 <head> 部分引入相应的 CDN 资源：

  • 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" />
  • 数学公式 (MathJax): 如果您的内容包含 LaTeX 格式的数学公式，需要引入 MathJax 库。 
    
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
  • 流程图 (Mermaid): 如果您的内容包含 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> 标签内，以确保它们在页面加载时被执行。

总结

在 AnQiCMS 中，Markdown 内容从编辑器输入到前端页面正确渲染为 HTML，是一个由后台处理和前端模板协同完成的流畅过程。通过在后台启用 Markdown 编辑器，利用系统自动的 Markdown 到 HTML 转换，并在前端模板中合理使用 |safe 和 |render 过滤器，以及按需引入外部渲染库（如 MathJax 和 Mermaid），您将能够确保所有 Markdown 内容，无论是普通文本、代码块，还是复杂的数学公式和流程图，都能以清晰、美观且功能完整的方式呈现在访问者面前。

常见问题 (FAQ)

1. 为什么我发布的 Markdown 内容在前端显示的是原始的 Markdown 语法，而不是渲染后的 HTML？

这通常是因为您在模板中调用内容时，忘记使用 |safe 过滤器。Markdown 文本在转换为 HTML 后，如果不对其进行 |safe 处理，模板引擎会为了安全将其中的 HTML 标签再次转义，导致显示为原始代码。确保您的内容变量后紧跟 |safe，例如 {{ archive.Content|safe }}。

2. 我的文章中包含数学公式或流程图，但在前端只显示了原始的 LaTeX 或 Mermaid 代码，没有图形化呈现，这是为什么？

AnQiCMS 仅负责将这些特殊 Markdown 语法转换为基本的 HTML 结构，但它们的图形化渲染需要依赖浏览器端的 JavaScript 库。您需要在网站模板的 <head> 区域引入相应的 CDN 资源，例如 MathJax（用于数学公式）和 Mermaid（用于流程图）库，并确保它们被正确初始化。具体引入代码可参考 AnQiCMS 的相关文档。

**3. 我在自定义的模型字段中输入了 Markdown 内容，但它并没有像文档内容那样自动渲染成