AnQiCMS如何将Markdown格式的内容（含公式、流程图）正确渲染为HTML显示？
AnQiCMS 在内容展示上一直致力于提供高效且灵活的解决方案，对于现代内容创作中越来越受欢迎的 Markdown 格式，特别是包含了数学公式和流程图的复杂内容，AnQiCMS 也提供了完善的支持机制，确保这些内容能够被正确解析并美观地呈现在网页上。
要实现 Markdown 格式（含公式、流程图）内容的正确渲染，主要涉及到两个层面：首先是 AnQiCMS 系统内部对 Markdown 文本的 HTML 转换，其次是客户端浏览器通过引入特定的 JavaScript 库来进一步解析和渲染这些特殊元素（如数学公式和流程图）。
第一步：确保 Markdown 编辑器已启用
首先，我们需要确保 AnQiCMS 后台的 Markdown 编辑器功能是开启状态。这是内容运营的基础。您可以登录 AnQiCMS 后台，在“全局设置”中找到“内容设置”选项。在这里，通常会有一个“启用 Markdown 编辑器”的选项，请确保它处于勾选状态。开启后，您在创建或编辑文档（文章、产品、单页面等）时，即可使用 Markdown 语法进行内容创作。
第二步：AnQiCMS 内部的 Markdown 到 HTML 转换
当您在 AnQiCMS 的后台使用 Markdown 编辑器输入内容并保存后，系统在内容发布时会负责将这些 Markdown 文本转换为标准的 HTML 结构。这意味着，像标题（#）、列表（-）、链接（[]()）、图片（”）等基本 Markdown 语法，AnQiCMS 都会自动处理并输出为相应的 HTML 标签。
对于文档内容字段，例如 archive.Content、category.Content 或 page.Content，AnQiCMS 的模板引擎提供了 |render 过滤器，专门用于确保内容在输出时被正确地解析为 HTML。虽然在启用了 Markdown 编辑器后，系统通常会自动处理大部分 Markdown 转换，但在某些自定义字段或特定场景下，明确使用 |render|safe 过滤器可以确保内容被正确解析并安全输出。|safe 过滤器在这里的作用是告知模板引擎，输出的 HTML 内容是安全的，无需再次进行 HTML 实体转义。
例如，在您的模板文件（如 detail.html）中，您可能会这样调用文档内容：
<div>
{{ archive.Content|render|safe }}
</div>
或者对于自定义字段：
<div>
{{ params.introduction.Value|render|safe }}
</div>
第三步：客户端脚本对特殊元素的渲染支持
虽然 AnQiCMS 已经将 Markdown 转换为了 HTML，但数学公式（如 LaTeX 语法）和流程图（如 Mermaid 语法）这些特殊的标记，在转换为 HTML 后，仍然需要借助前端的 JavaScript 库来进一步解析和渲染，才能在浏览器中正常显示为我们所期望的视觉效果。这些库通常需要您手动引入到网站的模板文件中。
AnQiCMS 的模板文件基于 Django 模板引擎语法，通常会有一个 base.html 或类似的公共模板文件，它承载着网站的通用头部、底部以及需要全局引入的资源。我们将在这里添加所需的 JavaScript 和 CSS 引用。
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" />数学公式的正确显示（通过 MathJax）： 数学公式通常使用 LaTeX 或 AsciiMath 等语法编写，例如
$$ E=mc^2 $$。MathJax 是一个强大的 JavaScript 显示引擎，用于在 Web 浏览器中显示数学。 在您的base.html文件的<head>区域内，加入以下脚本：<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>配置完成后，您在 Markdown 内容中编写的数学公式，例如
$$ \int_a^b f(x) dx $$或行内公式$\alpha + \beta = \gamma$，都将在浏览器中被 MathJax 渲染为精美的数学符号。流程图的正确显示（通过 Mermaid）： 流程图通常使用 Mermaid 这样的简单文本语法来描述，例如：
graph TD A[开始] --> B{操作}; B -- 是 --> C[结果1]; B -- 否 --> D[结果2]; C --> E[结束]; D --> E;Mermaid 是一个基于 JavaScript 的库，可以从文本生成图表和流程图。 在您的
base.html文件的<head>区域内，加入以下脚本：<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标记的流程图代码块时，Mermaid 库将识别并将其渲染为交互式的流程图。
内容创作时的 Markdown 语法示例
在 AnQiCMS 后台的 Markdown 编辑器中，您可以通过以下方式编写包含公式和流程图的内容：
- 行内公式： 使用单个美元符号包裹，例如
这是行内公式 $E=mc^2$ 。 - 块级公式： 使用双美元符号包裹，独占一行显示，例如：
$$ \sum_{i=1}^n i = \frac{n(n+1)}{2} $$ - 流程图： 使用
mermaid` 代码块包裹 Mermaid 语法，例如：graph LR A[提交文档] --> B{审核通过?}; B -- 是 --> C[发布]; B -- 否 --> D[退回修改]; C --> E[更新网站]; D --> A;“”
通过上述步骤，AnQiCMS 结合客户端脚本的力量，能够完美地将您的 Markdown 内容（包括复杂的数学公式和流程图）呈现在网页上，为读者提供更丰富的视觉体验和更清晰的信息传达。
常见问题 (FAQ)
1. 为什么 AnQiCMS 已经支持 Markdown 了，我还需要手动引入外部的 CDN 脚本来显示公式和流程图？
AnQiCMS 内部负责将 Markdown 文本（包括 $$...$$ 或 “`mermaid 这样的特殊标记）转换为基本的 HTML 结构。然而，这些特殊的标记本身并不是标准的 HTML 标签，浏览器无法直接理解并渲染成复杂的公式图形或流程图。因此，我们需要引入 MathJax 和 Mermaid 这些客户端 JavaScript 库。这些库会在浏览器加载页面后，扫描页面中特定的 HTML 结构（AnQiCMS 转换生成的），然后将其动态地解析并渲染成最终的视觉效果。AnQiCMS 负责内容管理和初步转换，而这些外部库则负责高级的客户端渲染。
2. 我已经按照步骤引入了脚本并启用了 Markdown 编辑器，但公式或流程图仍然显示为纯文本，或者页面出现报错，应该如何排查？
首先，请检查您的 base.html 文件中引入的 CDN 链接是否完整且正确，确保没有打字错误。其次，确认脚本是否被放置在 <head> 标签内，并且 mermaid 脚本的 type="module" 属性以及 mermaid.initialize({ startOnLoad: true }); 代码是完整的。
在内容编辑方面，请再次核对您使用的公式（如 $$...$$）或流程图（如 mermaid ...）语法是否符合 MathJax 或 Mermaid 的规范。错误的语法会导致它们无法被正确识别。最后，检查浏览器开发者工具（F12）的控制台（Console）是否有报错信息，这通常能帮助您定位是脚本加载失败、语法错误还是其他问题。另外，确保您在模板中输出内容时使用了 |render|safe 过滤器，以确保 AnQiCMS 转换后的 HTML 内容能够被浏览器正确处理，并且允许脚本执行。
3. 我能否使用本地部署的 MathJax 和 Mermaid 库，而不是通过 CDN 链接引入？
完全可以。CDN 链接提供了一种便捷、高效的引入方式，但如果出于对网站加载速度、安全性或离线访问等方面的考虑，您也可以选择将 MathJax 和 Mermaid 库下载到您的服务器上，然后修改 base.html 中的 <script> 和 <link> 标签，将其 src 或 href 属性指向您本地部署的路径。例如，如果将库文件放在 /public/static/js/ 目录下，您可以这样修改：
<script id="MathJax-script" async src="/static/js/mathjax/tex-mml-chtml.js"></script>
<script type="module">
import mermaid from '/static/js/mermaid/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
</script>
请注意，本地部署需要您自行管理这些库文件的更新和维护。