在内容运营中，有时我们需要展示复杂的数学公式或清晰的流程图，尤其是在技术文章、数据报告或教育内容中。AnQiCMS 凭借其强大的 Markdown 编辑器，为我们提供了实现这一需求的便利。通过简单的配置和引入必要的库文件，您就能让这些专业内容在网站前端完美呈现。

启用 AnQiCMS 的 Markdown 编辑器

首先，要让 AnQiCMS 识别并处理 Markdown 格式的内容，您需要在后台进行相应的设置。请前往 AnQiCMS 后台的“全局设置”，找到“内容设置”选项。在这里，您会看到一个“启用 Markdown 编辑器”的选项，勾选它并保存更改。开启此功能后，您在创建或编辑文档时，就可以选择 Markdown 格式来编写内容了。

在内容中插入数学公式和流程图

启用 Markdown 编辑器后，在文档内容区域，您可以直接使用 Markdown 语法来编写数学公式和流程图。

对于数学公式，通常使用以下方式：

  • 行内公式： 使用单个 $ 符号包裹，例如 $E=mc^2$。
  • 行间公式： 使用双 $$ 符号包裹，公式会独立成行并居中显示，例如 $$ \sum_{i=1}^n i = \frac{n(n+1)}{2} $$。

对于流程图，可以使用 Mermaid 语法，将其置于一个特殊的 Markdown 代码块中：

```mermaid
graph TD;
    A[开始] --> B{决策};
    B -- 是 --> C[执行操作];
    C --> D[结束];
    B -- 否 --> D;
```

这些语法会在 Markdown 编辑器中被识别，但要确保它们在前端页面上正确显示，还需要后续的步骤。

为 Markdown 内容添加基础样式

为了让您的 Markdown 内容在网站上看起来更加整洁和专业，我们可以引入一个通用的 Markdown 样式表。这就像给文本内容穿上了一件漂亮的衣服。您需要在网站的公共头部文件（通常是 base.html，位于 /template 目录下您所使用的模板文件夹内）的 <head> 区域，添加以下 CDN 链接：

<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 渲染出的 HTML 元素提供一套类似于 GitHub 的默认样式，显著提升内容的视觉效果和可读性。

确保数学公式的正确显示

数学公式的渲染需要一个专门的 JavaScript 库来将 Markdown 格式的公式转换成浏览器可显示的数学符号。MathJax 是一个非常流行的选择，它能将 LaTeX 等格式的公式转换为高质量的排版。同样，在 base.html 文件的 <head> 区域，紧随 Markdown 样式表之后，加入 MathJax 的 CDN 引用：

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

这段脚本会异步加载 MathJax 库，并在页面加载完成后自动扫描并渲染页面上的数学公式。

实现流程图的动态渲染

流程图的显示则可以借助 Mermaid 库来实现。Mermaid 允许您通过简单的文本语法创建各种类型的图表。要启用它，请在 base.html 文件的 <head> 或 <body> 结束标签之前添加以下代码：

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

这段代码会导入 Mermaid 库并对其进行初始化，使其能够在页面加载完成后自动识别并渲染 Markdown 代码块中的流程图定义。

模板中的内容渲染设置

完成了上述所有外部库的引用后，最关键的一步是确保您的 AnQiCMS 模板能够正确地将 Markdown 内容渲染为 HTML。在获取文档内容的模板标签（例如在文档详情页中常用的 archiveDetail 标签）中，您需要特别处理。

AnQiCMS 的模板系统为 Markdown 内容的渲染提供了便利。您在使用 archiveDetail 标签获取内容时，可以加入 render=true 参数，它会告诉系统将 Markdown 格式的文本自动转换为 HTML。此外，为了避免转换后的 HTML 代码被浏览器二次转义而导致显示异常，还需要配合使用 |safe 过滤器。

因此，您的模板中获取并显示文档主体内容的片段可能看起来像这样：

{% archiveDetail articleContent with name="Content" render=true %}
{{ articleContent|safe }}

通过这样的设置，您在 AnQiCMS 后台使用 Markdown 编辑器编写的包含数学公式和流程图的内容，就能在前端页面上被正确地解析、渲染并美观地呈现出来。

常见问题解答 (FAQ)

  1. Q: 为什么我按照步骤添加了 CDN 和模板代码，但数学公式和流程图还是无法显示？

    • A: 遇到这种情况，请首先检查几个关键点：
      • Markdown 语法是否正确？ 确认您在后台输入的数学公式（例如 $$...$$）和流程图（例如 mermaid ...）语法符合 Markdown 以及 MathJax/Mermaid 的规范。任何细微的语法错误都可能导致渲染失败。
      • 模板渲染参数和过滤器是否正确应用？ 确保您的模板在获取内容时使用了 {% archiveDetail ... render=true %}，并且输出时加上了 {{ variable|safe }}。如果缺少 render=true，Markdown 就不会被 AnQiCMS 转换为 HTML；如果缺少 |safe，转换后的 HTML 可能会被浏览器再次转义，导致 MathJax 和 Mermaid 无法识别和处理。
      • CDN 链接是否有效且可访问？ 使用浏览器开发者工具的网络 (Network) 选项卡，检查 MathJax 和 Mermaid 的 CDN 文件是否成功加载，没有出现 404 或其他网络错误。
      • 浏览器控制台是否有 JavaScript 错误？ 在浏览器开发者工具的控制台 (Console) 选项卡中，查看是否有与 MathJax 或 Mermaid 相关的 JavaScript 错误报告，这有助于定位问题。

  2. Q: 我是否可以将 MathJax 和 Mermaid 的库文件下载到本地服务器，而不是使用 CDN？

    • A: 完全可以。如果您对网站的加载速度、稳定性或对 CDN 的依赖性有特殊考虑，可以将这些 JavaScript 库文件下载到您的服务器上。然后，将 base.html 中的 CDN 链接替换为这些本地文件的相对路径。例如，您可以将文件存放在 /public/static/js/ 目录下，然后将 src 属性改为 /static/js/mathjax.js 或 /static/js/mermaid.esm.min.mjs 等，具体路径取决于您文件的实际存放位置。

  3. Q: 除了 MathJax 和 Mermaid，AnQiCMS 是否还支持其他的数学公式或流程图渲染库？

    • A: AnQiCMS 本身提供了强大的 Markdown 编辑器和将 Markdown 内容渲染为 HTML 的核心能力。这意味着理论上，只要是可以通过 JavaScript 在前端进行渲染的第三方库，您都可以尝试将其集成到您的 AnQiCMS 网站中。您只需找到相应库的 CDN 链接或本地文件，并按照其官方文档的要求添加到您的模板中，确保内容以正确的 HTML 结构输出，以便这些库能够识别并进行后续处理。