在内容管理系统中，Markdown 是一种轻量级的标记语言，它让内容创作者能够以纯文本形式写作，并通过简单的符号来排版，最终可以轻松转换成结构化的 HTML。对于 AnQiCMS 用户而言，利用 Markdown 来撰写内容不仅能提升效率，还能保证内容格式的一致性与可维护性。

那么，在 AnQiCMS 中，我们究竟该如何将 Markdown 内容渲染成精美的 HTML 页面呢？这涉及到几个关键步骤和一些实用的技巧。

第一步：在后台开启 Markdown 编辑器支持

首先，要让 AnQiCMS 识别并处理 Markdown 内容，我们需要在后台进行相应的设置。请前往 AnQiCMS 后台的管理界面，找到“全局设置”下的“内容设置”选项。在这里，您会看到一个名为“启用 Markdown 编辑器”的选项。勾选并保存此设置，AnQiCMS 的内容编辑界面就会支持 Markdown 语法，这意味着您可以在文章、产品、页面等内容的编辑器中直接使用 Markdown 进行写作了。

当您在内容字段（如文章详情、分类描述、单页内容、Tag 内容等）中输入 Markdown 文本后，AnQiCMS 在渲染前端页面时，默认会将其自动转换为 HTML 格式。这意味着大部分情况下，您无需额外的操作，系统会智能地将您的 Markdown 标记转化为浏览器可识别的 HTML 标签。为了确保这些转换后的 HTML 内容能被浏览器正确解析并显示，而不是作为纯文本输出，通常在模板中调用这些内容时，我们会使用 |safe 过滤器。例如，{{archive.Content|safe}} 会将文章内容安全地作为 HTML 渲染出来。

第二步：增强 Markdown 渲染效果（可选但推荐）

虽然 AnQiCMS 默认会将 Markdown 转换为 HTML，但为了提供更丰富的视觉体验，特别是当内容包含代码、数学公式或流程图时，我们可能需要借助一些前端库来进一步美化或启用特定功能的渲染。这些增强功能通常通过在模板文件中引入外部 CSS 和 JavaScript 库来实现。

1. 优化 Markdown 样式：GitHub Markdown CSS

如果您希望您的 Markdown 内容在网页上拥有类似于 GitHub 的简洁、专业的样式，可以引入 github-markdown-css。这能让您的 Markdown 转换后的 HTML 页面看起来更加美观和易读。

您可以在网站的公共模板文件（通常是 base.html）的 <head> 标签内添加以下 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" />

引入后，您可能还需要在包含 Markdown 内容的父元素上添加 markdown-body 类名，以应用这些样式。

2. 显示数学公式：MathJax

对于需要展示复杂数学公式的内容，AnQiCMS 结合 MathJax 库可以完美解决。只需在模板中引入 MathJax 的 JavaScript 脚本，您的 LaTeX 或 AsciiMath 格式的公式就能被渲染成清晰的数学表达式。

同样在 base.html 文件的 <head> 标签内，加入以下脚本：

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

之后，在您的 Markdown 内容中使用 MathJax 支持的语法（如 $$...$$ 或 $....$）即可。

3. 绘制流程图：Mermaid

如果您想在 Markdown 内容中直接创建流程图、序列图或其他图表，Mermaid 是一个非常好的选择。AnQiCMS 通过集成 Mermaid 库，让您能够直接通过文本描述来生成这些图表。

在 base.html 文件的底部（</body> 标签之前，或者在 <head> 中作为 defer 脚本），添加以下 Mermaid 脚本：

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

确保 mermaid.initialize({ startOnLoad: true }); 被调用，以便页面加载时自动渲染图表。在 Markdown 内容中，您就可以使用 Mermaid 的语法来创建图表了，例如：

```mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;


### 第三步：使用 `|render` 过滤器进行精细控制

AnQiCMS 模板引擎提供了一个名为 `|render` 的过滤器，它赋予我们更细致地控制 Markdown 到 HTML 转换的能力。虽然对于文章、页面等的 `Content` 字段，开启 Markdown 编辑器后会默认自动渲染，但对于一些自定义字段或其他并非默认 Markdown 类型的文本，`|render` 过滤器就显得尤为重要。

例如，如果您创建了一个名为 `introduction` 的自定义字段，并在其中填写了 Markdown 格式的简介。为了确保它也能被渲染成 HTML，您可以在模板中这样调用：

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

这里的 |render 过滤器会明确地告诉 AnQiCMS 模板引擎，将 introduction_text 变量中的 Markdown 文本转换为 HTML。

此外，在 archiveDetail、categoryDetail、pageDetail、tagDetail 等标签中，当您获取 Content 字段时，也可以通过 render 参数来手动指定是否进行 Markdown 渲染。例如：

  • <div>文档内容：{% archiveDetail archiveContent with name="Content" render=true %}{{archiveContent|safe}}</div>：强制进行 Markdown 渲染。
  • <div>文档内容：{% archiveDetail archiveContent with name="Content" render=false %}{{archiveContent|safe}}</div>：强制不进行 Markdown 渲染，即使全局开启了 Markdown 编辑器，内容也会以原始 Markdown 文本输出。

这种灵活性让您可以根据实际需求，决定哪些文本块需要进行 Markdown 渲染，哪些不需要，从而实现对页面内容的精确控制。

总结

AnQiCMS 提供了简洁而强大的 Markdown 渲染机制。从后台的全局开启，到前端模板中内容字段的自动渲染，再到通过引入第三方库实现样式美化、数学公式和流程图的展示，以及 |render 过滤器提供的精细控制，都极大地提升了内容运营的效率和内容的表现力。掌握这些方法，您就能充分发挥 AnQiCMS 在内容创作方面的优势，为用户呈现高质量、结构化的内容。

常见问题 (FAQ)

1. 我已经在后台开启了 Markdown 编辑器，为什么在前端页面上 Markdown 语法没有被渲染，而是显示了原始的文本符号？

这通常是因为您的模板文件在输出 Markdown 内容的字段时，没有使用 |safe 过滤器。例如，如果您的文章内容 archive.Content 包含 Markdown，您在模板中应该使用 {{archive.Content|safe}} 而不是 {{archive.Content}}。|safe 过滤器告诉模板引擎这段内容是安全的 HTML，可以直接解析显示，而不是进行转义处理。

2. 我的数学公式或 Mermaid 流程图没有正确显示，只显示了原始的文本代码，是什么原因？

Markdown 编辑器的启用只影响内容的输入，而 MathJax 和 Mermaid 等高级渲染功能需要在前端模板中手动引入相应的 JavaScript 库。请检查您的 base.html 或其他公共模板文件中是否已经按照文章中的指引，正确引入了 MathJax 和 Mermaid 的脚本。此外，确保您在 Markdown 内容中使用的公式和图表语法是这些库所支持的正确语法。例如，Mermaid 图表需要包裹在 mermaid... 代码块中。

3. 我在自定义的模型字段中也使用了 Markdown 语法，但它没有自动渲染成 HTML，我需要怎么做？

对于除了文章、页面等核心内容字段之外的自定义字段，AnQiCMS 默认不会自动进行 Markdown 渲染。您需要手动在模板中使用 |render 过滤器来显式地告诉模板引擎进行转换。例如，如果您的自定义字段名为 custom_description，您应该在模板中写成 {{archive.custom_description|render|safe}}，这样才能确保其中的 Markdown 内容被正确渲染。