在内容管理日益精细化的今天，网站不仅承载着文字和图片，更需要以专业且易懂的方式呈现复杂信息，例如数学公式和流程图。AnQiCMS 致力于提供高效、灵活的内容管理解决方案，当我们在网站上处理技术文章、学术内容或业务流程图时，如何确保这些特殊元素能够正确、美观地显示出来，就成为了一个值得探讨的问题。

AnQiCMS 本身对 Markdown 编辑器提供了良好支持，这意味着我们可以用简洁的 Markdown 语法来编写公式和流程图。然而，要让浏览器正确解析并渲染这些特殊的 Markdown 语法，还需要借助一些成熟的前端库。本文将详细介绍如何在 AnQiCMS 模板中引入这些库，并确保数学公式和流程图能够完美呈现。

前提准备：启用 Markdown 编辑器

首先，我们需要在 AnQiCMS 后台启用 Markdown 编辑器，以便在编辑内容时能够使用相关的语法。

请登录您的 AnQiCMS 后台，导航到 全局设置 -> 内容设置。在这个页面中，您会找到一个名为“是否启用Markdown编辑器”的选项。请务必将其设置为“是”。启用后，在您发布或编辑文档内容时，即可在内容编辑区域使用 Markdown 语法。

核心步骤：引入前端支持库到模板

AnQiCMS 采用了类似 Django 的模板引擎语法，这意味着网站模板通常会有一个 base.html 文件，它作为所有页面的骨架，承载着公共的页头、页脚等内容。为了让数学公式和流程图能在全站范围内正常显示，我们需要将所需的前端库引入到这个 base.html 文件的 <head> 区域。

您的模板文件存放在 /template 目录下，每个模板包都有自己的目录。找到您当前正在使用的模板包中的 base.html 文件（或者类似的公共头部文件），然后按照以下步骤添加代码。

1. Markdown 内容样式美化（可选，但强烈推荐）

虽然这不是公式和流程图显示所必需的，但引入一套美观的 Markdown 样式，可以让您的内容更具阅读性。这里我们推荐使用 GitHub 风格的 Markdown CSS。

在 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" />

2. 实现数学公式的正确显示

数学公式的渲染通常依赖于 MathJax 这样的库，它能够将 LaTeX、AsciiMath 或 MathML 语法编写的公式转换为清晰、美观的数学符号。

继续在 base.html 文件的 <head> 标签内，添加 MathJax 的 CDN 脚本：

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

3. 实现流程图的正确显示

流程图的渲染则可以借助 Mermaid 库，它允许您通过简单的文本描述来生成各种图表，包括流程图、序列图、甘特图等。

同样在 base.html 文件的 <head> 标签内，添加 Mermaid 的 CDN 脚本和初始化代码：

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

在内容模板中渲染 Markdown 字段

完成了后台设置和前端库的引入，还有最后一步非常关键：确保您的内容模板能够正确解析并渲染 Markdown 格式的文档内容。

在 AnQiCMS 中，当我们使用 archiveDetail 或 pageDetail 标签来调用文档或页面的 Content 字段时，需要明确告诉系统对这段内容进行 Markdown 到 HTML 的转换。这通过在标签中添加 render=true 参数来实现。同时，由于渲染后的 HTML 代码可能包含标签，我们需要使用 |safe 过滤器来防止 HTML 实体转义。

以文档详情页为例，假设您在 article/detail.html 或类似的文档模板中显示文章内容，您的代码可能会是这样：

<article class="markdown-body"> {# 配合上一步的github-markdown-css样式 #}
    <h1>{% archiveDetail with name="Title" %}</h1>
    <div class="article-content">
        {%- archiveDetail articleContent with name="Content" render=true %}
        {{ articleContent|safe }}
    </div>
</article>

在这里：

  • {%- archiveDetail articleContent with name="Content" render=true %}：这行代码告诉 AnQiCMS 获取当前文档的 Content 内容，并将其作为 Markdown 格式进行渲染。articleContent 是我们为渲染结果定义的临时变量。
  • {{ articleContent|safe }}：将渲染后的 HTML 内容安全地输出到页面上，防止浏览器将其作为纯文本显示。

如果您是在单页面中显示内容，调用方式也类似：

<div class="page-content markdown-body">
    {%- pageDetail pageContent with name="Content" render=true %}
    {{ pageContent|safe }}
</div>

测试与验证

完成以上所有步骤后，您就可以进行测试了：

  1. 在 AnQiCMS 后台新建或编辑一篇文档/页面。
  2. 在内容编辑器中，尝试插入数学公式和流程图的 Markdown 语法。
    • 数学公式示例（LaTeX 语法）： 
      
行内公式：$E=mc^2$
块级公式：
$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$
    • 流程图示例（Mermaid 语法）： 
      graph TD;
    A[开始] --> B{决策};
    B -- 是 --> C[执行操作1];
    B -- 否 --> D[执行操作2];
    C --> E[结束];
    D --> E;
  3. 保存并发布该文档/页面。
  4. 访问网站前台，查看该文档/页面。如果一切配置正确，您应该能看到渲染美观的数学公式和清晰的流程图了。

如果显示不正常，请检查浏览器控制台是否有 JavaScript 错误，并仔细核对 base.html 中引入 CDN 的代码以及内容模板中 render=true 和 |safe 过滤器的使用是否正确。

通过这些简单的配置，您的 AnQiCMS 网站就能完美地呈现复杂的数学公式和清晰的流程图，极大地提升了内容的专业性和可读性，为您的访客带来更优质的阅读体验。

常见问题（FAQ）

Q1：我启用了 Markdown 编辑器，也配置了 CDN，但数学公式和流程图还是不显示，或者显示为原始 Markdown 文本，这是为什么？ A1： 这很可能是因为您在内容模板（例如 article/detail.html 或 page/detail.html）中调用文章或页面内容时，没有正确地告诉 AnQiCMS 去渲染 Markdown。请确保您在 archiveDetail 或 pageDetail 标签中添加了 render=true 参数，并且对输出的内容使用了 |safe 过滤器。例如：{% archiveDetail articleContent with name="Content" render=true %}{{ articleContent|safe }}。

Q2：我能自定义 MathJax 或 Mermaid 渲染出来的公式和流程图的样式吗？ A2： 当然可以。MathJax 和 Mermaid 都提供了丰富的配置选项，允许您自定义字体、颜色、布局等。您可以通过修改 mermaid.initialize() 中的配置参数，或在 MathJax 脚本加载之前定义 MathJax = { ... } 对象来自定义它们的行为和样式。此外，