AnQiCMS 如何在模板中实现数学公式和流程图的正确显示？
在内容管理日益精细化的今天，网站不仅承载着文字和图片，更需要以专业且易懂的方式呈现复杂信息，例如数学公式和流程图。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>
测试与验证
完成以上所有步骤后，您就可以进行测试了：
- 在 AnQiCMS 后台新建或编辑一篇文档/页面。
- 在内容编辑器中，尝试插入数学公式和流程图的 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;
- 数学公式示例（LaTeX 语法）：
- 保存并发布该文档/页面。
- 访问网站前台，查看该文档/页面。如果一切配置正确，您应该能看到渲染美观的数学公式和清晰的流程图了。
如果显示不正常，请检查浏览器控制台是否有 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 = { ... } 对象来自定义它们的行为和样式。此外，