在 AnQiCMS 中启用 Markdown、渲染数学公式与流程图的完整指南

AnQiCMS 作为一款高效、灵活的内容管理系统，一直在努力为内容创作者提供更便捷、更强大的内容编辑和展示能力。对于经常需要撰写技术文档、学术论文或包含复杂逻辑流程的说明，原有的富文本编辑器有时会显得力不从心。幸运的是，新版的 AnQiCMS 已经集成了对 Markdown 编辑器的支持，并且可以很好地渲染数学公式和流程图，极大地提升了内容创作的效率和表现力。

接下来，我们将一起看看如何在 AnQiCMS 中启用这些强大的功能，让您的网站内容焕发新的生机。

启用 Markdown 编辑器

要开始使用 Markdown 来创作您的内容，首先需要在 AnQiCMS 的后台进行一项简单的设置。

您只需登录后台，找到左侧菜单中的“全局设置”，然后点击进入“内容设置”页面。在这个页面里，您会看到一个选项，通常是关于内容编辑器的类型选择。找到并勾选启用 Markdown 编辑器，然后保存您的更改。完成这一步后，当您再次创建或编辑文档时，富文本编辑器就会自动切换为 Markdown 编辑器了。

Markdown 内容的正确渲染

启用了 Markdown 编辑器后，您在后台撰写的内容会以 Markdown 语法存储。然而，仅仅在后台使用 Markdown 语法还不足以让它们在前台页面完美呈现。为了让 Markdown 文本在您的网站上拥有清晰、一致的视觉风格，我们需要引入一个样式文件。

我们推荐使用 github-markdown-css，它能为您的 Markdown 内容提供类似 GitHub 的优雅样式。您可以在网站模板的 base.html 文件（通常是所有页面共用的头部文件）的 <head> 标签内，添加如下这行代码：

<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 编辑器结合 MathJax 库可以轻松实现专业级别的公式渲染。MathJax 能够将 LaTeX、AsciiMath 等格式的数学表达式转化为高质量的排版效果，无论是内联公式还是独立块级公式，都能完美呈现。

要启用数学公式渲染，您同样需要在网站模板的 base.html 文件中的 <head> 标签内，添加 MathJax 的 CDN 脚本。

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

添加之后，您就可以在 Markdown 内容中使用 LaTeX 语法来书写公式了。例如：

内联公式：$E=mc^2$ 会被渲染为 \(E=mc^2\)。

块级公式：

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

会被渲染为： $\( \int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi} \)$

流程图的绘制与渲染

Markdown 不仅能处理文本和公式，还能通过集成 Mermaid.js 库来绘制各种流程图、序列图等。Mermaid.js 允许您通过简洁的文本语法描述图表结构，然后自动渲染出美观的图形。这对于解释复杂流程或系统架构非常有帮助。

为了让您的网站支持流程图渲染，请在 base.html 文件的 <head> 标签内，添加 Mermaid.js 的 CDN 脚本。请注意，这是一个 type="module" 类型的脚本。

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

一旦引入成功，您就可以在 Markdown 内容中使用 Mermaid 语法来创建流程图了。例如：

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

会被渲染为：

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

内容发布与进阶渲染

当您在后台的 Markdown 编辑器中添加了上述的数学公式或流程图内容后，保存并发布文档，它们就会在前台页面上按照预期的方式渲染出来。

需要注意的是，AnQiCMS 在文档详情页面使用 archiveDetail 标签获取内容时，其 Content 字段默认会检测并渲染 Markdown 语法为 HTML。如果您是将 Markdown 内容放置在自定义字段中，或者出于某种特殊需求希望手动控制渲染过程，您可以使用 render 过滤器。例如，如果您有一个名为 custom_markdown_field 的自定义字段包含 Markdown 内容，您可以在模板中这样调用来确保它被正确渲染：

{{ archiveDetail customMarkdownField with name="custom_markdown_field" | render | safe }}

这里的 |render 确保 Markdown 转换为 HTML，|safe 则告知模板引擎这是一个安全的 HTML 内容，不需要再次转义。

通过以上这些设置，您就可以在 AnQiCMS 网站上充分利用 Markdown 的强大功能，创作出更具表现力、更易于阅读的专业内容。

常见问题 (FAQ)

1. 为什么我启用了 Markdown 编辑器，但在前台内容仍然没有样式，只是显示为普通的文本？

这通常是因为您没有在网站的 base.html 文件中引入 github-markdown-css 样式表。虽然后台编辑器让您能够使用 Markdown 语法，但浏览器本身并不知道如何美化这些 Markdown 元素。引入这个 CSS 文件后，您的 Markdown 标题、列表、代码块等内容就会拥有统一且美观的默认样式了。

2. 我已经按照步骤引入了 MathJax 和 Mermaid.js 的 CDN 脚本，但在文章中输入公式或流程图代码后，它们还是显示为原始代码，没有被渲染出来，这是为什么？

首先，请仔细检查您在 base.html 中引入的脚本是否完整、位置是否正确（通常在 <head> 标签内）。对于 Mermaid.js，还需要确保 mermaid.initialize({ startOnLoad: true }); 这行代码被正确执行，它负责启动 Mermaid 渲染。此外，公式和流程图的 Markdown 语法非常严格，任何细小的拼写错误或格式不当都可能导致渲染失败。建议您对照 MathJax 和 Mermaid.js 的官方文档，检查您的代码块是否符合标准格式（例如，MathJax 的行内公式用 $..$ 或 \(..\)，块级公式用 $$..$$ 或 \[..\]；Mermaid.js 的图表内容必须包裹在 mermaid` 和 ` 代码块中）。

3. 如果我的文章内容是纯 HTML 格式，不是 Markdown，启用了 Markdown 编辑器后会受影响吗？

AnQiCMS 的 Markdown 编辑器通常会有一个切换模式，或者在您粘贴纯 HTML 内容时自动识别。如果您直接在 Markdown 编辑器中粘贴或写入纯 HTML 代码，并且内容字段最终被 |safe 或 render|safe 过滤器处理（或者 AnQiCMS 内部的默认渲染逻辑允许），那么这些 HTML 代码通常会被浏览器正常解析和显示，不会被当作普通文本。不过，为了避免潜在的样式冲突或不必要的解析问题，如果您确定内容是纯 HTML，最好使用传统的富文本编辑器来编辑，或者确保您的 Markdown 渲染配置不会对纯 HTML 造成负面影响。