安企CMS为用户提供了强大且灵活的内容管理能力，其中对Markdown格式的支持，极大地提升了内容创作者的效率。无论是撰写技术文章需要展示复杂的数学公式，还是产品文档中需要清晰的流程图，安企CMS都能帮助您在前端页面上美观地呈现这些内容。

要实现这一目标，我们需要分几个步骤进行，从后台设置到前端模板调整，确保内容能够被正确解析和渲染。

第一步：在后台启用Markdown编辑器

首先，您需要在安企CMS的后台管理界面启用Markdown编辑器。这是您创作包含数学公式和流程图内容的基石。

  1. 登录安企CMS后台。
  2. 前往“全局设置”菜单，然后点击“内容设置”。
  3. 在内容设置页面中，找到“是否启用Markdown编辑器”选项，并将其开启。
  4. 保存您的设置。

启用后，当您在编辑文章、单页、分类描述等内容时，就可以选择使用Markdown编辑器进行创作了。

第二步：在内容中创作数学公式和流程图

启用Markdown编辑器后，您就可以在文本内容中使用Markdown语法来编写数学公式和流程图了。

  • 数学公式： 通常，Markdown中的数学公式可以使用LaTeX语法，并用特定的符号包裹。
    • 行内公式：使用单个美元符号包裹，例如 $E=mc^2$。
    • 块级公式（独立一行居中显示）：使用双美元符号包裹，例如 $$ \int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2} $$。
  • 流程图： 流程图通常借助Mermaid语法在Markdown代码块中实现。
    • 在Markdown编辑器中，创建一个代码块，并指定语言为mermaid，例如： 
      graph TD;
    A[开始] --> B{决策};
    B -- 是 --> C[执行操作];
    C --> D[结束];
    B -- 否 --> E[等待];
    E --> A;
      这些内容在您保存后，会以原始的Markdown文本形式存储在数据库中，等待前端的解析和渲染。

第三步：确保前端页面能正确渲染Markdown内容

安企CMS的Markdown编辑器本身已经将Markdown内容转换为HTML，但数学公式和流程图的复杂渲染需要额外的JavaScript库来处理。这就像浏览器能够解析HTML，但要显示精美的图表或交互式组件，就需要引入相应的脚本一样。您需要在前端模板文件中引入必要的CDN资源。

找到您当前使用的模板目录（通常在/template下，例如default），然后打开该模板下的base.html文件。这个文件通常包含了网站的通用头部（<head>）和底部区域，是引入全局脚本和样式表的理想位置。

请将以下代码片段添加到base.html文件的<head>标签内：

  1. 应用Markdown默认样式： 为了让Markdown渲染出的HTML内容拥有良好的排版和样式，我们可以引入一个通用的Markdown样式表。

    <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是一个强大的JavaScript显示引擎，用于在Web浏览器中显示数学公式。

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

  3. 实现流程图的正确显示： Mermaid是一个JavaScript库，可以从类似Markdown的文本定义创建图表和可视化。

    <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文件。这样，当浏览器加载您的页面时，这些脚本和样式就会被引入，从而具备解析和渲染数学公式及流程图的能力。

第四步：在模板中控制内容字段的渲染方式

即使您在后台使用了Markdown编辑器，最终内容如何呈现在前端，还需要在模板文件中进行调用和控制。安企CMS提供了灵活的模板标签，允许您决定是否对内容字段进行Markdown到HTML的转换。

以文档详情页为例，您通常会使用archiveDetail标签来显示文章内容。该标签的Content字段支持一个render参数，用于控制Markdown转换行为。

  • 默认情况下，如果后台启用了Markdown编辑器，Content字段在调用时会自动将Markdown转换为HTML。您通常会这样调用：

    {% archiveDetail archiveContent with name="Content" %}
{{ archiveContent|safe }}

    这里的|safe过滤器至关重要，它告诉模板引擎，archiveContent中的HTML内容是安全的，不需要进行二次转义，可以直接输出。

  • 如果您希望明确控制是否进行Markdown渲染，可以使用render参数：

    • render=true：强制对Markdown内容进行渲染。
    • render=false：不进行Markdown渲染，直接输出原始的Markdown文本。
    {# 强制进行Markdown转换，并安全输出HTML #}
{% archiveDetail archiveContent with name="Content" render=true %}
{{ archiveContent|safe }}


{# 不进行Markdown转换，输出原始Markdown文本 #}
{% archiveDetail rawContent with name="Content" render=false %}
{{ rawContent }}

    这个render参数在处理一些特殊情况时非常有用，例如您可能希望在页面上展示Markdown语法本身而不是渲染后的效果，或者您的内容中包含了部分由其他系统生成的HTML，不希望被Markdown解析器再次处理。

通过以上四个步骤，您的安企CMS网站就能够完美地在前端展示Markdown格式编辑的内容，包括复杂的数学公式和清晰的流程图了。

常见问题 (FAQ)

Q1: 我已经按照步骤启用了Markdown编辑器，并在内容中编写了数学公式和流程图，但前端页面上这些内容仍然只显示为原始文本，没有被渲染，这是为什么？

A1: 出现这种情况，最常见的原因是没有在前端模板文件（base.html或其他包含您网站<head>部分的模板文件）中正确引入用于渲染数学公式（MathJax）和流程图（Mermaid）的CDN资源，或者引入的位置不正确。请仔细检查第三步中提供的三个CDN链接是否都已添加到base.html的<head>标签内，并且没有语法错误。另外，确保您在模板中调用Content字段时使用了|safe过滤器，例如{{ archiveContent|safe }}，以防止HTML内容被转义。

Q2: 我发现页面上的Markdown内容样式有些混乱，或者公式、流程图虽然能显示但样式不佳，如何统一这些内容的显示效果？

A2: 确保Markdown内容的默认样式是美观的，这取决于您在base.html中引入的第一个CDN资源：github-markdown-css。这个CSS文件提供了一套简洁、通用的Markdown渲染样式。如果样式仍然不满意，您可以选择：1. 查找其他更符合您网站风格的Markdown CSS库进行替换；2. 在您自定义的CSS文件中，针对markdown-body类或其内部元素编写额外的CSS规则，覆盖或增强默认样式。对于公式和流程图，MathJax和Mermaid通常自带了不错的默认样式，但如果您有特定需求，可以查阅它们各自的官方文档，了解如何进行自定义配置。

Q3: 如果我的一篇文章里，既有Markdown编写的内容，又有一些直接粘贴的HTML代码，我应该如何设置才能让它们都正确显示，而不出现错误？

A3: 在这种混合内容的情况下，建议在后台启用Markdown编辑器，并确保在模板中调用Content字段时使用render=true参数，并始终附加|safe过滤器，例如{{ archiveContent|safe }}。安企CMS的Markdown编辑器通常能够识别并保留Markdown内容中的HTML标签，render=true会尝试将Markdown部分转换为HTML，而|safe则保证了无论是编辑器转换的HTML还是您直接粘贴的HTML，都能作为原始HTML被浏览器解析。如果发现HTML部分仍然被转义，请再次确认|safe过滤器是否已正确使用。