安企CMS为内容创作者提供了灵活的内容编辑方式，其中Markdown格式的支持极大地提升了内容创作的效率和表现力。理解如何在文档内容中正确使用Markdown并确保其在网站前端完美渲染为HTML，是发挥这一功能优势的关键。

启用与使用Markdown编辑器

要开始在AnQiCMS中使用Markdown，首先需要在后台进行简单的配置。这通常在全局设置 -> 内容设置中完成。启用Markdown编辑器后，您在文档、单页或分类内容编辑时，内容输入框将从传统的富文本编辑器切换为支持Markdown语法的纯文本编辑器。

一旦启用，您就可以在内容编辑区使用Markdown语法了。例如，您可以使用#表示标题，**粗体**表示加粗文字，[链接](URL)创建超链接，`插入图片，以及-或*`创建列表等。这些基础语法会被AnQiCMS的模板引擎自动解析并转换为对应的HTML结构。

对于更高级的Markdown应用，例如数学公式和流程图，AnQiCMS也提供了支持。为了让这些高级元素能被浏览器正确解析并显示，您需要引入一些第三方JavaScript库和样式文件。这些代码片段通常放置在您网站模板的公共头部文件（如 base.html 或 header.html）的 <head> 标签内或 </body> 结束标签之前。

例如，如果您希望在网站上正确显示Markdown样式、数学公式和流程图：

  • Markdown基本样式：为了让渲染后的Markdown内容具有清晰的排版和样式，您可以引入类似GitHub风格的Markdown CSS。

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

  • 数学公式显示：对于使用LaTeX或MathML编写的数学公式，可以引入MathJax库来解析并美观地显示。

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

  • 流程图与图表：Mermaid是一个流行的JavaScript库，可以将Markdown风格的文本描述转换为流程图、序列图等图表。

    <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）来创建图表。

确保内容正确渲染为HTML

在AnQiCMS中，内容的最终显示效果由模板标签和过滤器共同决定。了解如何正确使用它们，是确保Markdown内容正确渲染的关键环节。

当您在后台启用了Markdown编辑器后，通过archiveDetail、categoryDetail、pageDetail等标签获取的Content字段内容，AnQiCMS的模板引擎通常会自动将其从Markdown转换为HTML。这意味着您在模板中直接输出{{ archive.Content }}，大部分情况下就能看到渲染后的HTML。

然而，在某些特定场景下，您可能希望手动控制Markdown内容的渲染过程，或者确保内容不被模板引擎的默认转义机制干扰。AnQiCMS为此提供了render参数和|safe过滤器。

  • render 参数：在archiveDetail、categoryDetail、pageDetail等标签获取Content字段时，可以添加render参数来明确指定是否进行Markdown到HTML的转换。render=true会强制执行转换，而render=false则会阻止转换，直接输出原始Markdown文本。 例如：

    {# 强制将Markdown内容渲染为HTML #}
<div>文档内容：{% archiveDetail archiveContent with name="Content" render=true %}{{archiveContent|safe}}</div>
{# 不进行Markdown渲染，显示原始Markdown文本 #}
<div>原始Markdown：{% archiveDetail archiveContent with name="Content" render=false %}{{archiveContent}}</div>

    这个参数在您需要对同一份Markdown内容进行不同处理时非常有用。

  • |safe 过滤器：在AnQiCMS的模板系统中，为了防止潜在的跨站脚本（XSS）攻击，所有通过变量输出到页面的内容默认都会进行HTML实体转义。这意味着，像<这样的HTML特殊字符会被转换为&lt;，以确保浏览器将其显示为文本而不是解析为HTML标签。

    因此，对于经过Markdown渲染或您希望以HTML形式输出的内容（如通过render=true处理后的内容），您必须使用 |safe 过滤器来明确告知模板引擎，该内容是安全的HTML代码，不需要进行二次转义。如果缺少|safe过滤器，您可能会看到原始HTML代码（例如<p>我的段落</p>）而非浏览器解析后的效果（一个实际的段落）。

    正确的做法是：

    {# 确保渲染后的HTML内容被浏览器正确解析 #}
<div>文档内容：{% archiveDetail archiveContent with name="Content" render=true %}{{archiveContent|safe}}</div>

    |safe过滤器是确保Markdown内容最终能够被浏览器正确解析并显示为HTML的关键步骤。

通过以上步骤，即在后台启用Markdown、在模板中引入必要的第三方库、并在输出内容时根据需要使用render参数和|safe过滤器，您就可以充分利用AnQiCMS的Markdown功能，高效创作并展示高质量的文档内容。

常见问题 (FAQ)

  1. 为什么我启用了Markdown编辑器，但内容在前端显示的是原始Markdown语法，而不是渲染后的HTML？ 这通常是因为在模板中输出内容时，缺少了|safe过滤器。AnQiCMS为了安全默认会转义HTML特殊字符。Markdown内容被转换为HTML后，如果直接输出而没有|safe过滤器，这些HTML标签也会被转义，导致在页面上显示为原始代码。请确保在输出Markdown转换后的内容（如{{ archiveContent }}）时，加上|safe，例如{{ archiveContent|safe }}。

  2. 我的数学公式或流程图显示不出来，或者显示为代码块而不是图形怎么办？ Markdown编辑器本身只负责解析数学公式和流程图的文本语法，但浏览器并不原生支持它们的渲染。您需要在网站的模板文件（通常是base.html或公共头部文件）中引入相应的第三方JavaScript库。对于数学公式，需要引入MathJax；对于流程图，需要引入Mermaid。请参照文章中提供的代码片段，确保这些库被正确引入到您的网站。

  3. AnQiCMS的Markdown编辑器和富文本编辑器可以同时使用吗？我可以在某些内容类型中使用Markdown，而在另一些内容类型中使用富文本吗？ 目前，AnQiCMS中的Markdown编辑器和富文本编辑器是全局切换的，即您在“全局设置 -> 内容设置”中选择启用Markdown编辑器后，所有支持内容编辑的模块（如文档、单页、分类描述等）都会统一使用Markdown编辑器。您不能直接在后台对不同内容类型进行独立的编辑器切换。不过，即使您全局启用了Markdown编辑器，在模板中通过render=false参数也可以选择性