如何将Markdown内容中自定义字段`introduction`渲染成HTML？

📅 👁️ 71

在 AnQiCMS 中，自定义字段为我们提供了极大的灵活性，能够根据实际业务需求扩展内容结构。比如，您可能为文章或产品设置了一个名为 introduction 的自定义字段，并希望在这个字段中撰写 Markdown 格式的简介。那么，如何在网站前端将这些 Markdown 内容正确地渲染成 HTML，使其在页面上呈现出丰富的格式呢？这篇文章将详细介绍如何轻松实现这一目标。

理解 AnQiCMS 中的自定义字段与 Markdown

AnQiCMS 的核心优势之一就是其灵活的内容模型。您可以在后台为不同的内容模型（如文章、产品）自定义各种字段。当您创建一个 多行文本 类型的自定义字段，并且在编辑内容时选择启用 Markdown 编辑器，您就可以在这个字段中享受 Markdown 带来的便捷排版体验。例如，我们创建了一个名为 introduction 的字段，并在其中输入了包含标题、列表或链接的 Markdown 文本。

默认情况下，如果您直接在模板中输出这个自定义字段的内容，它会以纯文本形式显示原始的 Markdown 语法，而不是我们期望的排版效果。要让它在前端显示为漂亮的 HTML 格式，我们需要对它进行额外的处理。

获取 Markdown 自定义字段内容

在 AnQiCMS 的模板中，获取自定义字段内容的方式通常有两种：通过 archiveDetail 标签直接获取，或者通过 archiveParams 标签循环获取。

如果您知道自定义字段的名称（例如 introduction），可以直接使用 archiveDetail 标签来获取它的值：

{% archiveDetail introductionContent with name="introduction" %}
<div>
    {{ introductionContent }}
</div>

在这里，introductionContent 变量将包含您的 introduction 字段的原始 Markdown 文本。如果您的内容模型定义了多个自定义字段，并且您希望遍历它们，可以使用 archiveParams 标签：

{% archiveParams params %}
<div>
    {% for item in params %}
        {% if item.FieldName == "introduction" %}
            <div>
                {{ item.Value }}
            </div>
        {% endif %}
    {% endfor %}
</div>

无论哪种方式，此时输出的都还是原始的 Markdown 文本。

核心：将 Markdown 内容渲染为 HTML

要将这些原始的 Markdown 文本转换为浏览器可识别的 HTML，AnQiCMS 提供了一个非常实用的过滤器：render。这个过滤器能够将 Markdown 语法解析并转换为对应的 HTML 结构。

然而，仅仅使用 render 过滤器还不够。为了安全起见，AnQiCMS 模板引擎默认会对所有输出内容进行 HTML 实体转义。这意味着，即使 render 过滤器将 Markdown 转换成了 HTML（例如 <h1>标题</h1>），这些 HTML 标签也会被再次转义成 <h1>标题</h1>，最终在页面上仍然显示为源代码，而不是实际的渲染效果。

为了解决这个问题，我们需要使用另一个重要的过滤器：safe。safe 过滤器告诉模板引擎，这段内容是安全的，不需要进行 HTML 实体转义，可以直接作为 HTML 输出到页面上。

因此，将 Markdown 自定义字段渲染为 HTML 的关键在于同时使用 render 和 safe 两个过滤器。它们的使用顺序是先 render，后 safe：

{{ 您的Markdown变量 | render | safe }}

一个完整的示例

让我们以上面的 introduction 自定义字段为例，看看如何在模板中完整地渲染它：

方式一：直接获取 introduction 字段并渲染

<article>
    <h1>{{ archive.Title }}</h1>
    <div class="article-meta">
        <!-- 其他文章元数据 -->
    </div>
    <div class="article-introduction">
        <h2>文章简介</h2>
        {% archiveDetail introductionContent with name="introduction" %}
        {{ introductionContent | render | safe }}
    </div>
    <div class="article-content">
        <h2>文章详情</h2>
        {% archiveDetail articleContent with name="Content" %}
        {{ articleContent | safe }} {# 主内容字段通常已自动渲染，这里仅用safe确保输出 #}
    </div>
</article>

方式二：循环获取自定义字段并渲染

如果您的自定义字段较多，或者不确定其具体名称，可以采用循环的方式，并判断字段名：

<article>
    <h1>{{ archive.Title }}</h1>
    <div class="article-meta">
        <!-- 其他文章元数据 -->
    </div>
    {% archiveParams customFields %}
    {% for field in customFields %}
        {% if field.FieldName == "introduction" %}
            <div class="article-introduction">
                <h2>文章简介</h2>
                {{ field.Value | render | safe }}
            </div>
        {% endif %}
        {# 如果有其他Markdown自定义字段，也可以在这里添加渲染逻辑 #}
        {% if field.FieldName == "additional_notes" %}
            <div class="additional-notes">
                <h3>补充说明</h3>
                {{ field.Value | render | safe }}
            </div>
        {% endif %}
    {% endfor %}
    <div class="article-content">
        <h2>文章详情</h2>
        {% archiveDetail articleContent with name="Content" %}
        {{ articleContent | safe }}
    </div>
</article>

在这些示例中，introductionContent 或 field.Value 变量里存储的 Markdown 文本，经过 | render 转换为 HTML 结构，再通过 | safe 确保这些 HTML 能够被浏览器正常解析和显示。

配置 Markdown 编辑器（可选）

为了更好地使用 Markdown 功能，您可能还需要在 AnQiCMS 后台进行一些设置：

启用 Markdown 编辑器： 在 后台->全局设置->内容设置 中，确保已启用 Markdown 编辑器。这样，在编辑内容时，您的自定义字段就能支持 Markdown 输入了。
支持数学公式与流程图： 如果您的 Markdown 内容包含 MathJax 数学公式或 Mermaid 流程图，您还需要在模板的 base.html 文件的 <head> 部分引入相应的第三方 JavaScript 库和 CSS 样式，具体方法可以参考 AnQiCMS 的相关文档说明。

通过上述步骤，您就可以灵活地在 AnQiCMS 中使用 Markdown 自定义字段，并将它们完美地渲染成结构丰富的 HTML 内容，极大地提升网站内容展示的质量和多样性。

常见问题 (FAQ)

Q1: 为什么在模板中直接输出自定义字段内容时，显示的是原始 Markdown 文本而不是渲染后的 HTML？

这是因为 AnQiCMS 模板引擎的默认行为。当您直接输出一个变量时，它会将其视为纯文本并进行 HTML 实体转义，以防止潜在的安全问题（如 XSS 攻击）。即使字段内容本身是 Markdown，也需要显式地通过 |render 过滤器将其转换为 HTML，并使用 |safe 过滤器告诉模板引擎这段内容是安全的 HTML，不需要再次转义，才能在前端正确渲染。

Q2: 除了 introduction 字段，我能否将其他包含 Markdown 的自定义字段也渲染为 HTML？

当然可以。|render 过滤器是一个通用的内容渲染工具，只要您的自定义字段中存储的是 Markdown 格式的文本，无论是 product_description、activity_notes 还是其他任何自定义字段，您都可以使用 {{ 您的字段变量 | render | safe }} 的方式将其渲染为 HTML。关键在于确保字段内容是有效的 Markdown 文本，并且在模板中正确地应用了 |render|safe 过滤器链。

Q3: 如果我的 Markdown 自定义字段内容中包含 MathJax 数学公式或 Mermaid 流程图，它们能被正确渲染吗？

是的，AnQiCMS 的 Markdown 编辑器支持这些高级功能。要使 MathJax 和 Mermaid 在前端页面上正确显示，您需要在模板文件的 <head> 部分引入相应的 JavaScript 库。AnQiCMS 提供了详细的文档 (help-markdown.md) 指导您如何在 base.html 中添加这些 CDN 资源。一旦配置正确，您的 Markdown 自定义字段中包含的数学公式和流程图就能在页面上被完美地渲染出来。

如何将Markdown内容中自定义字段`introduction`渲染成HTML？

理解 AnQiCMS 中的自定义字段与 Markdown

获取 Markdown 自定义字段内容

核心：将 Markdown 内容渲染为 HTML

一个完整的示例

配置 Markdown 编辑器（可选）

常见问题 (FAQ)

相关文章

`escapejs`过滤器在处理Markdown内容中JavaScript代码片段时有何用途？

Markdown内容渲染为HTML后，如何防止恶意脚本（XSS）注入？

如何截短Markdown内容中的URL链接显示文字，同时保持可点击？

`urlize`过滤器如何自动识别并美化Markdown内容中的URL链接？

AnQiCMS的Markdown编辑器支持哪些Markdown语法标准和扩展？

AnQiCMS模板中，如何将同一字符串重复输出指定次数？

如何在AnQiCMS中实现文本的批量重复显示功能？

使用AnQiCMS `repeat` 过滤器重复输出字符串的**实践是什么？