在 AnQiCMS 页面中集成 MathJax 和 Mermaid.js：轻松显示数学公式与流程图

AnQiCMS 作为一款高效、灵活的内容管理系统，在满足各类内容展示需求方面表现出色。随着技术内容的日益丰富，许多用户会遇到需要在网站中优雅地展示数学公式和流程图的场景。AnQiCMS 通过其内置的 Markdown 编辑器和对模板的灵活支持，使得集成 MathJax 和 Mermaid.js 变得非常简单，能够帮助您将复杂的数学表达式和逻辑图表直观地呈现在网页上。

下面，我们将详细介绍如何在 AnQiCMS 页面中集成这些工具，让您的网站内容更具表现力。

第一步：启用 Markdown 编辑器

要让 MathJax 和 Mermaid.js 正常工作，首先需要确保 AnQiCMS 的内容编辑功能支持 Markdown。AnQiCMS 提供了内置的 Markdown 编辑器，它是显示数学公式和流程图的基础。

请登录 AnQiCMS 后台，导航至 全局设置 -> 内容设置。在这里，您会找到一个选项用于启用或禁用 Markdown 编辑器。请确保该选项处于启用状态。一旦 Markdown 编辑器启用，您在编辑文章或页面内容时就可以使用 Markdown 语法进行创作了。

第二步：修改基础模板文件以引入 MathJax 和 Mermaid.js

MathJax 和 Mermaid.js 的渲染能力依赖于在页面中加载它们各自的 JavaScript 库。在 AnQiCMS 中，所有的页面通常会继承一个基础模板文件，通常是 base.html。我们将修改这个文件，在 <head> 标签内引入必要的 CDN 资源，这样它们就能在所有页面上生效。

AnQiCMS 的模板文件位于服务器的 /template 目录下。您需要找到当前正在使用的模板目录，并在其中定位到 base.html 文件。如果您的模板是默认模板，通常路径会是 /template/default/base.html。

在 base.html 文件的 <head> 标签内部，找到一个合适的位置（通常在所有 CSS 文件之后，但其他 JavaScript 文件之前），添加以下代码片段：

1. 引入 MathJax 渲染数学公式

MathJax 能够将 LaTeX 语法编写的数学公式渲染成高质量的排版。您需要添加以下 script 标签：

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

这段代码会异步加载 MathJax 3 的核心脚本。async 属性意味着脚本将在后台加载，不会阻塞页面的其他内容的解析，从而优化页面加载速度。

2. 引入 Mermaid.js 渲染流程图和图表

Mermaid.js 允许您通过简单的文本语法创建各种图表，如流程图、序列图、甘特图等。为了集成 Mermaid.js，您需要添加以下 script 标签：

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

请注意，Mermaid.js 的脚本使用了 type="module"，这表明它是一个 ES 模块。mermaid.initialize({ startOnLoad: true }); 这行代码会指示 Mermaid 在页面加载完成后自动查找并渲染页面中的 Mermaid 图表。

完成修改后，请保存 base.html 文件。

第三步：在内容中编写数学公式和流程图

现在，Markdown 编辑器已启用，并且 MathJax 和 Mermaid.js 脚本已引入页面。您可以在 AnQiCMS 后台创建或编辑任何文章或页面，并直接在 Markdown 内容区域中使用它们各自的语法。

1. 编写数学公式 (MathJax)

MathJax 支持两种主要的公式编写方式：

  • 行内公式 (Inline Math): 使用单个美元符号 $ 包裹公式。 例如：$ E=mc^2 $ 将渲染为 \( E=mc^2 \)。
  • 块级公式 (Display Math): 使用双美元符号 $$ 包裹公式，公式会独立显示一行并居中。 例如：$$ x = \frac{-b \pm \sqrt{b^2-4ac}}{2a} $$ 将渲染为 $\( x = \frac{-b \pm \sqrt{b^2-4ac}}{2a} \)$

2. 编写流程图和图表 (Mermaid.js)

Mermaid.js 图表需要放置在特殊的 Markdown 代码块中，指定语言为 mermaid。

例如，创建一个简单的流程图：

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

保存您的内容后，访问前台页面，MathJax 和 Mermaid.js 就会自动解析并渲染您编写的公式和图表。

小贴士与注意事项

  • 清除缓存： 在修改模板文件或系统设置后，为了确保更改立即生效，请务必前往 AnQiCMS 后台的 更新缓存 功能，清除所有系统缓存。
  • CDN 优势： 文中使用的都是公共 CDN 链接，它们通常具有更快的加载速度和更高的可用性。如果出于特殊需求需要本地托管脚本，可以从 MathJax 和 Mermaid.js 的官方网站下载文件，并将其放置在 AnQiCMS 的 /public/static/ 目录下，然后相应地修改 base.html 中的路径。
  • 语法检查： 如果您的公式或图表未能正确显示，请仔细检查 MathJax（LaTeX）和 Mermaid 的语法是否正确。它们对语法错误比较敏感。您可以查阅 MathJax 和 Mermaid 的官方文档获取更详细的语法指南。

通过以上步骤，您便能在 AnQiCMS 网站中轻松地集成 MathJax 和 Mermaid.js，为您的技术文章、教程或报告增添专业的数学公式和清晰的图表，从而大大提升内容的质量和用户的阅读体验。

常见问题 (FAQ)

1. 我按照步骤操作了，但是页面上的数学公式或流程图没有显示出来，这是什么原因？ 最常见的原因包括：

  • Markdown 编辑器未启用： 确保在 AnQiCMS 后台的“全局设置 -> 内容设置”中启用了 Markdown 编辑器。
  • 模板文件修改不正确： 检查 base.html 文件中的脚本引入代码是否完整、准确，并位于 <head> 标签内。注意 Mermaid.js 的 type="module" 属性和 mermaid.initialize() 调用。
  • AnQiCMS 缓存未清除： 修改模板或设置后，需要到后台手动清除缓存才能使更改生效。
  • 内容格式不正确： 确保您在 Markdown 编辑器中编写公式和图表的语法符合 MathJax（$...$ 或 $$...$$）和 Mermaid (mermaid ...) 的要求。

2. MathJax 和 Mermaid.js 的脚本可以本地托管吗？ 当然可以。如果您的网站对外部 CDN 访问有特殊限制，或者希望完全掌控资源加载，可以将 MathJax 和 Mermaid.js 的发布文件下载到您的服务器上，然后将它们放置在 AnQiCMS 的静态资源目录（例如 /public/static/js/）中。随后，您只需修改 base.html 中对应的 script 标签的 src 路径，指向本地文件即可。

3. 我的 Mermaid 图表代码很长，或者 MathJax 公式非常复杂，有没有办法调试它们不渲染的原因？ 对于复杂的代码，建议先在 MathJax 或 Mermaid 的在线编辑器或官方文档中进行测试和验证，确保语法无误。例如，Mermaid 官方提供了一个实时编辑器，您可以在其中输入代码并即时查看渲染效果。如果确认语法无误但在 AnQiCMS 页面上仍有问题，可以尝试打开浏览器的开发者工具（通常按 F12 键），查看控制台（Console）是否有报错信息，这通常能帮助您定位是脚本加载失败、语法解析错误还是其他问题。