在安企CMS中，利用Markdown格式撰写文章是一种高效且优雅的内容创作方式，它让我们的内容结构更加清晰，排版更加灵活。特别是对于需要包含代码、数学公式甚至流程图的技术性文章而言，Markdown编辑器更是不可或缺的利器。那么，如何确保这些精心编写的Markdown文本能在网站前端正确地解析并完美呈现呢？让我们一步步来探索。
启用Markdown编辑器
首先，要享受到Markdown带来的便利，我们需要在安企CMS后台开启这项功能。操作非常简单：
- 登录您的安企CMS后台。
- 在左侧导航栏找到并点击 全局设置。
- 进入 内容设置 选项卡。
- 在这里，您会看到一个用于启用Markdown编辑器的选项。勾选它，并保存您的设置。
一旦启用，当您创建或编辑文章时，文档内容的编辑器将切换到Markdown模式，您就可以开始使用Markdown语法来编写内容了。
在文章中撰写Markdown文本
在Markdown编辑器中，您可以按照标准的Markdown语法进行创作，例如：
- 使用
#来创建标题（# 一级标题,## 二级标题）。 - 使用
*或_来斜体或加粗文本（*斜体*,**加粗**）。 - 使用
-或*创建无序列表，使用1.创建有序列表。 - 使用反引号 创建行内代码，或使用三反引号
```python“` 括起代码块。 - 插入图片 “。
安企CMS的Markdown编辑器还特别支持更高级的内容，比如数学公式和流程图，这对于许多专业领域的文章来说非常实用。您可以直接在编辑器中嵌入LaTeX语法的数学公式或Mermaid语法的流程图，系统会将其作为原始Markdown文本保存。
确保Markdown内容正确显示在网页上
文章内容以Markdown格式保存后，安企CMS会在将内容输出到网页前端时，自动将其转换为HTML。然而，要让转换后的HTML内容不仅结构正确，还能拥有美观的样式，并正确渲染数学公式和流程图，还需要在网站模板中进行一些额外的配置。
通常，这些配置需要在您网站模板的 base.html 文件中进行修改，它通常位于 /template/{您的模板目录}/ 下。请在文件的 <head> 标签内添加以下内容：
为Markdown内容应用默认样式： 为了让Markdown转换成的HTML元素（如标题、列表、代码块）有良好的默认视觉效果，可以引入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" />正确显示数学公式（MathJax）： 如果您在文章中使用了LaTeX语法的数学公式，需要引入MathJax库来解析和渲染它们。
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>正确显示流程图（Mermaid）： 对于使用Mermaid语法绘制的流程图，则需要引入Mermaid库并进行初始化。
<script type="module"> import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs'; mermaid.initialize({ startOnLoad: true }); </script>
将这些代码片段添加到 base.html 文件的 <head> 区域，可以确保这些渲染库在页面加载时被正确引用，从而使得Markdown内容，包括复杂的数学公式和流程图，都能在您的网站上完美呈现。
模板中的内容渲染逻辑
在安企CMS的模板中，无论是文章（archive）还是单页面（page）的内容字段，通常都会在后台自动将Markdown转换为HTML。当您在模板中调用这些内容时，比如使用 archiveDetail 标签获取 Content 字段，并将其输出时，务必使用 |safe 过滤器。
例如，在您的文章详情模板中，您可能会这样显示文章内容：
{% archiveDetail articleContent with name="Content" %}
{{ articleContent|safe }}
这里的 |safe 过滤器非常重要，它告诉模板引擎，articleContent 变量中的内容是安全的HTML，不需要再次进行转义。如果缺少 |safe，浏览器可能会将HTML标签作为纯文本显示，导致文章排版混乱，甚至出现乱码。
此外，archiveDetail 标签还提供了 render 参数，允许您手动控制Markdown到HTML的转换。当您在内容设置中关闭了Markdown编辑器，但文章内容仍是Markdown格式时，可以使用 render=true 参数强制进行转换：
<div>文档内容：{% archiveDetail archiveContent with name="Content" render=true %}{{archiveContent|safe}}</div>
反之，如果您想获取原始的Markdown文本而不进行任何转换（例如，您想在前端使用JavaScript库进行自定义渲染），可以使用 render=false：
<div>原始Markdown内容：{% archiveDetail archiveContent with name="Content" render=false %}{{archiveContent|safe}}</div>
通过以上步骤，您不仅可以轻松地在安企CMS中使用Markdown来创作内容，还能确保这些内容在网站前端得到专业、准确且美观的呈现。这无疑将大大提升您的内容创作效率和网站的用户体验。
常见问题 (FAQ)
Q1: 我已经开启了Markdown编辑器并撰写了内容，但文章在网站前台显示为原始Markdown文本，没有被解析成HTML，这是为什么？
A1: 这很可能是因为您在模板中输出文章内容时，没有使用 |safe 过滤器。当安企CMS将Markdown内容转换为HTML后，为了安全起见，模板引擎默认会对所有输出内容进行HTML转义。|safe 过滤器会告知模板引擎，您输出的内容是预期的HTML，无需再次转义，这样浏览器才能正确渲染HTML标签。请检查您的文章详情模板，确保在输出 Content 字段时使用了 {{ archiveContent|safe }}。
Q2: 我在文章中插入了数学公式或流程图，但它们只显示为原始代码或文本，并没有被渲染成图表或公式，该如何解决？
A2: 数学公式（如LaTeX）和流程图（如Mermaid）的渲染需要特定的JavaScript库在浏览器端进行处理。虽然安企CMS后台会将这些Markdown内容转换为标准的HTML，但如果没有在前端引入相应的JS库，浏览器就无法识别并渲染它们。请确保您已按照文章中的指导，在您模板的 base.html 文件的 <head> 标签中，正确引入了MathJax（用于数学公式）和Mermaid（用于流程图）的CDN链接及初始化代码。
Q3: archiveDetail 标签的 render 参数有什么作用？在什么情况下我需要使用它？
A3: render 参数允许您手动控制Markdown内容是否在后台被转换为HTML。默认情况下，如果您的后台开启了Markdown编辑器，archiveDetail 会自动将Markdown转换为HTML。但如果您在后台关闭了Markdown编辑器，但文章内容本身是Markdown格式，您可以使用 render=true 强制进行转换。反之，如果您希望获取原始的Markdown文本（例如，您打算在前端使用自定义的JavaScript库来处理Markdown），则可以使用 render=false 来阻止后台的自动转换。在大多数情况下，如果您在后台启用了Markdown编辑器，通常不需要显式设置 render=true，但了解它的作用可以帮助您在特定场景下更灵活地控制内容显示。