安企CMS如何将Markdown格式的文章内容正确渲染为HTML并显示？

📅 👁️ 68

在内容创作日益高效的今天，Markdown因其简洁明了的语法和专注于内容本身的特性，受到了广大内容创作者的青睐。安企CMS深知这一趋势，并提供了强大的功能，让您可以轻松地将Markdown格式的文章内容转化为精美的HTML页面，并支持更丰富的显示效果，如数学公式和流程图。

首先，要让安企CMS识别并处理Markdown内容，您需要在后台进行简单的配置。这就像告诉系统，您希望以Markdown的方式来撰写文章。

一旦启用，当您创建或编辑文章时，文章内容的输入框将会变为Markdown编辑器，方便您使用Markdown语法进行内容创作。

当Markdown编辑器启用后，安企CMS会默认对您用Markdown语法撰写的内容进行处理，将其转换为浏览器可以理解的HTML结构。然而，在某些特定的模板调用场景下，您可能需要更明确地控制这一渲染过程。

在模板文件中，我们通常使用archiveDetail标签来获取文章的详细内容。例如，获取文章内容的Markdown原文：

{# 默认用法，自动获取当前页面文档 #}
<div>文档内容：{% archiveDetail with name="Content" %}</div>

这里的Content字段就是您在后台Markdown编辑器中输入的内容。

为了确保Markdown内容被正确渲染为HTML并安全显示，通常会用到render参数和safe过滤器：

render=true：这个参数明确指示系统对获取到的Markdown内容执行渲染操作，将其转换为HTML。
|safe：这是Django模板引擎的一个过滤器。因为系统出于安全考虑，默认会对HTML标签进行自动转义（例如<会变成<），以防止XSS攻击。当您确定内容是安全且需要显示为HTML时，使用|safe过滤器可以取消这种自动转义，让浏览器正确解析并显示HTML。

因此，在您的模板文件中，获取并显示经过渲染的Markdown内容通常会写成这样：

{# 假设archiveContent变量存储了Content字段的内容 #}
<div>
    {%- archiveDetail articleContent with name="Content" %}
    {{articleContent|render|safe}}
</div>

或者直接在标签中指定渲染：

<div>
    {%- archiveDetail with name="Content" render=true %}{{archiveContent|safe}}
</div>

通过这种方式，您撰写的Markdown内容就能在前端页面上完美地以HTML形式展现出来。

Markdown不仅能提供基本的文本格式化，结合第三方库，还能实现更高级的显示效果，如数学公式和流程图。安企CMS也支持通过在模板中引入相应的CDN资源来增强这些功能。

这些增强功能通常需要在您的base.html（或任何作为公共头部引用的模板文件，如bash.html或partial/header.html）的<head>标签中添加对应的脚本和样式链接。

Markdown默认样式： 为了让渲染后的Markdown内容拥有更美观、可读性强的样式，您可以引入一个通用的GitHub风格Markdown样式表。在您的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" />
```
然后，您可能需要将渲染后的内容包裹在一个具有markdown-body类的div中，以便样式生效：<div class="markdown-body">{{ articleContent|render|safe }}</div>。
网页上数学公式的正确显示 (MathJax)： 如果您需要在文章中嵌入LaTeX格式的数学公式，MathJax是一个非常强大的解决方案。在base.html的<head>部分添加：
```
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
```
此脚本会自动检测页面中的数学公式并进行渲染。
网页上流程图的正确显示 (Mermaid)： Mermaid允许您使用简单的文本语法来创建流程图、序列图等。在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>
```
Mermaid会扫描页面中特定的代码块（通常是graph TD、sequenceDiagram等Mermaid语法块），并将其转换为可交互的图形。

通过上述步骤，您的Markdown文章不仅能被正确渲染为HTML，还能拥有专业的样式、动态的数学公式和清晰的流程图，极大地提升了内容的表现力和用户体验。安企CMS将技术细节封装于后端，让内容创作者能够专注于内容本身，而无需担忧复杂的渲染逻辑。

Q: Markdown编辑器已启用，但文章内容仍显示为纯文本，没有转换为HTML，这是为什么？ A: 这通常是由于在模板文件中没有正确使用render=true参数来指示系统渲染Markdown，或者没有使用|safe过滤器来取消HTML的自动转义。请检查您的archiveDetail标签是否包含了render=true和|safe，例如：{{articleContent|render|safe}}。
Q: 我在文章中插入了数学公式和流程图，但在前端页面上却无法正常显示，这是什么原因？ A: 即使Markdown内容本身被渲染为HTML，MathJax和Mermaid等高级功能也需要额外的JavaScript库来解析和显示。请确保您已按照文档说明，在您网站的base.html或其他公共头部模板的<head>部分，正确引入了MathJax和Mermaid的CDN脚本。
Q: 除了文章详情页，我能否在分类描述或单页面内容中使用Markdown并渲染为HTML？ A: 是的，安企CMS的Markdown渲染能力不限于文章详情。在获取分类描述（categoryDetail）或单页面内容（pageDetail）时，如果这些字段支持Markdown，您同样可以使用render=true参数和|safe过滤器来将其内容渲染为HTML。例如：{{categoryContent|render|safe}}。