在使用安企CMS管理网站内容时，单页面（Page）是一个非常实用的功能，它能灵活地创建“关于我们”、“联系方式”等静态内容。很多朋友喜欢用Markdown来撰写这些页面的内容，因为它简单高效，能快速排版。不过，有时我们会发现，即便内容是用Markdown写的，页面前端却依然显示为纯文本，没有经过HTML渲染。这往往是因为模板没有正确指示系统进行渲染。

别担心，安企CMS提供了非常简单且强大的方式来解决这个问题，让你的Markdown内容能够强制渲染为漂亮的HTML。这主要涉及两种方法，它们都能让你灵活地控制内容的显示。

理解安企CMS的Markdown处理机制

在深入操作之前，我们先简单了解一下安企CMS是如何处理Markdown内容的。通常，如果你在后台的“全局设置”->“内容设置”中启用了Markdown编辑器，那么通过这个编辑器创建或编辑的文档内容，在前端默认情况下是会自动渲染为HTML的。

然而，在某些特定场景下，比如你关闭了Markdown编辑器，或者内容是从其他地方导入，希望在模板层面做更精细的控制时，就需要手动强制渲染。安企CMS的模板引擎非常灵活，它允许你在获取内容时，明确地告诉系统：“请把这段Markdown文本渲染成HTML！”

方法一：直接在pageDetail标签中指定render参数

当我们使用pageDetail标签来获取单页面内容时，这个标签本身就提供了一个render参数，可以直接控制Markdown内容的渲染行为。

pageDetail标签是用来获取单个页面的详细信息的，例如页面的标题、描述、内容等。它的基本用法是：

{% pageDetail 变量名称 with name="字段名称" id="1" %}

如果我们需要获取某个单页的Content字段，并且希望它强制渲染为HTML，可以在name="Content"之后，额外添加一个render=true的参数。同时，为了避免模板引擎对已渲染的HTML代码再次进行转义（这会导致HTML标签显示为纯文本），我们还需要配合使用|safe过滤器。

举个例子，假设我们想在模板中显示ID为1的单页面内容，并确保其Markdown被正确渲染：

{# 假设当前页面是单页面，或者你知道单页的ID，比如ID为1 #}
<div>
    {# 获取单页面内容，并明确指定render=true来强制渲染Markdown为HTML #}
    {% pageDetail pageContent with name="Content" id="1" render=true %}
    {# 使用|safe过滤器确保HTML代码不会被转义，而是直接输出 #}
    {{ pageContent|safe }}
</div>

这段代码的逻辑很清晰：

  1. {% pageDetail pageContent with name="Content" id="1" render=true %}：这行代码会从数据库中获取ID为1的单页面的Content字段内容。render=true在这里起到了关键作用，它会指示安企CMS的内部处理器，在将Markdown内容传递给pageContent变量之前，先将其转换为HTML。
  2. {{ pageContent|safe }}：由于render=true已经将Markdown转换成了HTML，pageContent变量现在包含的是一段HTML代码。安企CMS的模板引擎出于安全考虑，默认会自动转义HTML标签，防止跨站脚本攻击（XSS）。|safe过滤器就是告诉模板引擎：“这段HTML内容是安全的，请直接输出，不要转义其中的HTML标签。”

通过这种方式，你的Markdown内容就能以HTML的形式呈现在页面上了。

方法二：利用|render过滤器进行二次处理

有时候，你可能已经将Markdown内容获取到了一个变量中，或者这个内容是某个自定义字段，它不直接支持render=true参数。在这种情况下，你可以使用|render过滤器对这个变量进行后期处理。

|render过滤器是一个通用的内容渲染工具，它可以将包含Markdown文本的变量，渲染成HTML。它同样需要与|safe过滤器一起使用。

假设你有一个单页面，其中有一个自定义字段叫做introduction，它里面存放的是Markdown格式的简介。你可以这样来处理：

{# 获取单页面的自定义字段内容，此时pageIntroduction变量中是原始Markdown文本 #}
{% pageDetail pageIntroduction with name="introduction" %}

<div>
    <h3>页面简介 (Markdown渲染为HTML):</h3>
    {# 使用|render过滤器将pageIntroduction变量中的Markdown内容渲染为HTML，再使用|safe过滤器确保HTML被正确显示 #}
    {{ pageIntroduction|render|safe }}
</div>

这里做了两步操作：

  1. {% pageDetail pageIntroduction with name="introduction" %}：首先，我们通过pageDetail标签获取了名为introduction的自定义字段内容，并将其存储在pageIntroduction变量中。此时，pageIntroduction中是原始的Markdown文本。
  2. {{ pageIntroduction|render|safe }}：接着，我们对pageIntroduction变量应用|render过滤器。这个过滤器会把变量中的Markdown文本转换成HTML。然后，和之前一样，|safe过滤器确保这些HTML代码被浏览器正常解析和显示。

何时选择哪种方法？

  • 当你直接从Content字段获取主内容时，推荐使用pageDetail标签的render=true参数。 这种方法更直接，在内容获取阶段就完成了渲染，代码也更简洁。
  • 当内容来自自定义字段、或者你已经将内容赋值给一个变量，需要后续处理时，使用|render过滤器更合适。 这种方法提供了更大的灵活性，可以在获取内容之后，根据需要随时进行渲染。

无论选择哪种方法，关键都在于明确告诉安企CMS：“这是一段Markdown，我希望它显示为HTML。”

注意事项与**实践

  1. |safe过滤器不可或缺： 就像前面提到的，|safe过滤器是为了防止HTML标签被转义而显示为纯文本的关键。如果没有它，即使Markdown被渲染成了HTML，你也可能只会看到<p>Hello World</p>这样的字样，而不是“Hello World”的段落。
  2. 安全性考量： |safe过滤器顾名思义，是告诉系统这段内容是“安全”的。这意味着，如果你渲染的Markdown内容是来自用户输入，并且没有经过严格的安全过滤，那么直接使用|safe可能会存在XSS（跨站脚本攻击）的风险。虽然安企CMS在后台编辑时有其自身的安全机制，但在处理未知来源或高度敏感的用户生成内容时，请务必谨慎。
  3. Markdown样式： 强制渲染为HTML只是解决了内容从Markdown到HTML的转换问题。如果你希望渲染后的Markdown内容拥有像GitHub那样的美观样式，你可能还需要在模板的<head>部分引入GitHub Markdown CSS样式表。例如，可以在你的base.html文件中添加： 
    
<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内容在前端就会有更专业的显示效果。

通过这些简单的方法，你可以轻松地在安企CMS中管理和展示你的Markdown单页面内容，让网站的呈现更加丰富多彩。

常见问题 (FAQ)

Q1：为什么有时候我的Markdown内容显示为纯文本，而不是HTML？ A1：这通常是因为模板在输出内容时，没有明确指示安企CMS将Markdown文本渲染为HTML。如果后台的Markdown编辑器没有启用，或者你直接获取了内容而没有使用render=true参数（对于pageDetail或archiveDetail标签）或|render过滤器，那么Markdown源代码就会原样输出。解决方法是在模板中添加相应的render=true参数或|render过滤器，并配合|safe过滤器使用。

Q2：|safe过滤器有什么作用，它安全吗？ A2：|safe过滤器是告诉安企CMS的模板引擎，其前面的内容是安全的HTML代码，无需进行默认的HTML转义。如果没有|safe，像<p>这样的HTML标签可能会被转义成&lt;p&gt;，导致页面显示为纯文本。 关于安全性，使用|safe意味着你信任这段HTML内容。对于后台管理员手动输入的Markdown内容，通常是安全的。但如果内容是来自前端用户提交或不可信的第三方来源，并且没有经过严格的安全审查，直接使用|safe可能会引入XSS（跨站脚本攻击）的风险。因此，在使用时需要根据内容的来源和敏感性进行判断。

Q3：强制渲染成HTML后，如何让Markdown内容样式更美观？ A3：强制渲染只负责将Markdown语法转换为HTML结构。要让这些HTML拥有更好的视觉效果，你需要引入CSS样式。一个常见的做法是引入第三方的Markdown样式库，比如GitHub的Markdown样式。你可以在你的网站模板（通常是base.html或类似文件）的<head>标签内，添加一个链接引用其CDN资源，例如： `https://cdnjs.cloudflare.com/ajax/libs/github-markdown-css/5.2.