内容是网站的灵魂，而如何高效、美观地呈现这些内容，是每一位运营者关心的话题。在安企CMS中，利用Markdown来撰写内容，不仅能大幅提升写作效率，还能轻松实现复杂的排版需求，例如插入数学公式和绘制流程图，这对于技术博客、教育站点或需要展示复杂业务流程的企业官网来说，无疑是如虎添翼的功能。

接下来，我们将一起探索如何在安企CMS的模板中，将Markdown内容正确地渲染为HTML，并优雅地展示您的数学公式和流程图。

首先，启用Markdown编辑器

在安企CMS中，开启Markdown功能是实现这些炫酷效果的第一步。您只需登录后台，前往“全局设置”下的“内容设置”页面，在这里找到并启用Markdown编辑器。完成这一设置后，您在发布或编辑文章、页面等内容时，就可以直接使用Markdown语法进行创作了。

为模板准备渲染环境

Markdown内容，尤其是涉及到数学公式和流程图，需要在前端页面通过额外的JavaScript库来解析和渲染。安企CMS的模板系统基于Django模板引擎语法，文件通常以.html为后缀，并统一存放在/template目录下。您可能有一个名为base.html的公共模板文件，它包含了网站的通用头部（<head>）和底部区域。我们将在页面的<head>标签内引入必要的外部资源，以确保所有页面都能正确渲染这些特殊内容。

  1. 为Markdown内容添加样式

    为了让Markdown渲染出的HTML内容拥有良好的可读性和美观度，我们可以引入一个通用的Markdown样式库，比如github-markdown-css。这个样式库能够让您的Markdown内容在网页上呈现出类似GitHub的风格。

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

  2. 让数学公式跃然纸上

    如果您需要在内容中展示复杂的数学公式，MathJax是一个非常强大的解决方案，它能将LaTeX、MathML等格式的数学表达式渲染为高质量的排版效果。

    同样，在base.html的<head>标签内，添加MathJax的CDN引用：

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

    现在，您可以在Markdown内容中使用LaTeX语法来编写公式，例如行内公式$\alpha + \beta = \gamma$或独立公式块$$\sum_{i=1}^{n} i = \frac{n(n+1)}{2}$$，它们都将被MathJax正确渲染。

  3. 绘制清晰的流程图

    流程图是展示业务逻辑、算法步骤的绝佳方式。Mermaid是一个基于Markdown的流程图和图表工具，它允许您用简单的文本语法创建各种图表。

    在base.html的<head>标签内，紧随MathJax之后，添加Mermaid的CDN引用及其初始化脚本：

        <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` ... `）即可绘制流程图。

在模板中正确显示Markdown内容

现在，当您的后台和前端模板都准备就绪，我们来关注如何在具体的页面（如文章详情页、单页等）中，将Markdown内容转换为可供浏览器渲染的HTML。

安企CMS的模板标签，如archiveDetail、categoryDetail或pageDetail，用于获取不同类型内容的详细信息。其中，Content字段通常承载着Markdown格式的文本。

默认情况下，如果您在后台启用了Markdown编辑器，系统在获取Content字段时，会尝试自动将Markdown转换为HTML。但为了更精准的控制，或者当您需要在其他自定义字段中渲染Markdown时，安企CMS提供了两种灵活的方式：

  1. 使用render=true参数（推荐用于主要内容字段） 当您调用Content字段时，可以为其添加render=true参数，明确指示系统进行Markdown到HTML的转换。 例如：

    {% archiveDetail articleContent with name="Content" render=true %}
{{ articleContent|safe }}

    这里的articleContent变量将包含由Markdown转换而来的HTML。

  2. 使用|render过滤器（适用于任何包含Markdown的变量） 如果您的Markdown内容存放在自定义字段中，或者您希望在全局关闭Markdown编辑器的情况下，仅对特定内容进行渲染，那么|render过滤器会是您的好帮手。它能将任何包含Markdown语法的变量，转换为HTML。 例如，假设您有一个名为introduction的自定义字段包含Markdown：

    {% archiveDetail introduction with name="introduction" %}
{{ introduction|render|safe }}

一个重要的提醒： 无论是使用render=true参数还是|render过滤器，转换后的内容都是HTML格式。为了防止模板引擎再次对HTML特殊字符进行转义（例如将<转为&lt;），导致HTML代码无法正确显示，您需要在输出时加上|safe过滤器。这样，浏览器才能将其识别为正常的HTML结构并进行渲染。

实践案例：将Markdown内容呈现在页面上

假设您正在编辑一个名为article_detail.html的文章详情页模板。结合前面提到的步骤，您的模板可能会是这个样子：

{# 假设这是您的文章详情页模板：/template/default/article_detail.html #}

{# 继承基础模板，基础模板中已引入必要的CDN资源 #}
{% extends 'base.html' %}

{% block title %}
    <title>{% tdk with name="Title" siteName=true %}</title>
{% endblock %}

{% block head_extra %}
    {# 如果您的CDN资源是直接在base.html中引入，这里可以省略。
       如果是在block中引入，确保其在<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" />
    <script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
    <script type="module">
        import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
        mermaid.initialize({ startOnLoad: true });
    </script>
{% endblock %}

{% block content %}
<article class="markdown-body"> {# 添加 markdown-body 类以应用 GitHub Markdown 样式 #}
    <h1>{% archiveDetail with name="Title" %}</h1>
    <div class="article-meta">
        <span>分类: <a href="{% categoryDetail with name='Link' %}">{% categoryDetail with name='Title' %}</a></span>
        <span>发布日期: {% archiveDetail with name="CreatedTime" format="2006-01-02" %}</span>
        <span>浏览量: {% archiveDetail with name="Views" %}°</span>
    </div>

    <div class="article-content">
        {# 获取文章内容并确保渲染Markdown为HTML且安全输出 #}
        {% archiveDetail articleContent with name="Content" render=true %}
        {{ articleContent|safe }}
    </div>

    {# 如果您有自定义Markdown字段，例如一个叫 'supplementary_info' 的字段 #}
    {% archiveDetail supplementaryInfo with name="supplementary_info" %}
    {% if supplementaryInfo %}
    <div class="supplementary-section">
        <h2>补充信息</h2>
        {{ supplementaryInfo|render|safe }}
    </div>
    {% endif %}

</article>
{% endblock %}

在这段代码中，{% archiveDetail articleContent with name="Content" render=true %} 语句从当前文章中获取Markdown格式的内容，render=true参数确保其被转换为HTML，然后{{ articleContent|safe }}安全地将其输出到页面上。而外部引入的CSS和JavaScript库则会负责为这些HTML内容赋予样式、渲染数学公式和流程图。

一些实用建议

  • CDN资源的稳定性： 上述示例中使用的CDN链接（cdnjs.cloudflare.com和cdn.jsdelivr.net）通常是稳定可靠的，但在极少数情况下，网络问题可能影响资源的加载。如果您的网站对加载速度和稳定性有非常高的要求，可以考虑将这些JavaScript和CSS文件下载到本地服务器，并通过安企CMS的静态资源管理功能进行分发。
  • 内容编写与测试： 在Markdown中编写数学公式和流程图时，建议您先在一些在线Markdown编辑器中进行预览和