How to render Markdown content into HTML in AnQiCMS?
In a content management system, Markdown is a lightweight markup language that allows content creators to write in plain text format and use simple symbols for formatting, which can be easily converted into structured HTML.For AnQiCMS users, using Markdown to write content can not only improve efficiency, but also ensure consistency and maintainability of the content format.
How do we render Markdown content into beautiful HTML pages in AnQiCMS?This involves several key steps and some practical skills.
Step 1: Enable Markdown editor support in the background
Firstly, to let AnQiCMS recognize and process Markdown content, we need to make corresponding settings in the background.Please go to the administration interface of AnQiCMS, find the 'Content Settings' option under 'Global Settings'.Here, you will see an option named 'Enable Markdown Editor'.Check and save this setting, the content editing interface of AnQiCMS will support Markdown syntax, which means you can directly use Markdown to write in the editor for articles, products, pages, and other content.
When you enter Markdown text in content fields (such as article details, category descriptions, single-page content, Tag content, etc.), AnQiCMS will automatically convert it to HTML format when rendering the front-end page by default.This means that in most cases, you do not need to perform any additional operations, the system will intelligently convert your Markdown markup into HTML tags that the browser can recognize.|safeFilter. For example,{{archive.Content|safe}}The article content will be safely rendered as HTML.
Step 2: Enhance Markdown Rendering (optional but recommended)
Although AnQiCMS defaults to converting Markdown to HTML, in order to provide a richer visual experience, especially when the content includes code, mathematical formulas, or flowcharts, we may need to use some front-end libraries to further beautify or enable rendering of specific features.These enhanced features are usually implemented by introducing external CSS and JavaScript libraries in the template file.
1. Optimize Markdown Style: GitHub Markdown CSS
If you want your Markdown content to have a concise and professional style on the web like GitHub, you can introducegithub-markdown-cssThis will make your Markdown converted HTML page look more beautiful and easy to read.
You can find the public template files of the website (usuallybase.html）的<head>Add the following CSS reference inside the tag:
<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" />
After adding, you may also need to add a class name to the parent element containing the Markdown content:markdown-bodyto apply these styles.
2. Display mathematical formula: MathJax
For content that needs to display complex mathematical formulas, AnQiCMS combined with the MathJax library can perfectly solve it.Just include the MathJax JavaScript script in the template, and your LaTeX or AsciiMath formatted formulas can be rendered as clear mathematical expressions.
Similarly, inbase.htmlthe file<head>Add the following script inside the tag:
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
After that, use the MathJax syntax supported in your Markdown content (such as$$...$$or$....$）to do so.
3. Draw a flowchart: Mermaid
If you want to create flowcharts, sequence diagrams, or other charts directly in Markdown content, Mermaid is an excellent choice.AnQiCMS integrates the Mermaid library, allowing you to directly generate these charts through text descriptions.
Inbase.htmlat the bottom of the file (</body>Before the label, or in<head>asdeferAdd the following Mermaid script:
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
</script>
Ensuremermaid.initialize({ startOnLoad: true });Called to automatically render the chart when the page is loaded. In Markdown content, you can use Mermaid syntax to create charts, for example:
```mermaid
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
### 第三步：使用 `|render` 过滤器进行精细控制
AnQiCMS 模板引擎提供了一个名为 `|render` 的过滤器，它赋予我们更细致地控制 Markdown 到 HTML 转换的能力。虽然对于文章、页面等的 `Content` 字段，开启 Markdown 编辑器后会默认自动渲染，但对于一些自定义字段或其他并非默认 Markdown 类型的文本，`|render` 过滤器就显得尤为重要。
例如，如果您创建了一个名为 `introduction` 的自定义字段，并在其中填写了 Markdown 格式的简介。为了确保它也能被渲染成 HTML，您可以在模板中这样调用：
```twig
{% archiveDetail introduction_text with name="introduction" %}
{{ introduction_text|render|safe }}
Here|renderThe filter will explicitly tell the AnQiCMS template engine tointroduction_textconvert Markdown text in variables to HTML.
In addition,archiveDetail/categoryDetail/pageDetail/tagDetailtags, when you retrieveContentWhen a fieldrendercan also be specified manually to indicate whether Markdown rendering should be performed. For example:
<div>文档内容：{% archiveDetail archiveContent with name="Content" render=true %}{{archiveContent|safe}}</div>:强制进行 Markdown 渲染。<div>文档内容：{% archiveDetail archiveContent with name="Content" render=false %}{{archiveContent|safe}}</div>：Force no Markdown rendering, even if the global Markdown editor is enabled, the content will be output as raw Markdown text.
This flexibility allows you to decide, based on your actual needs, which text blocks need to be rendered in Markdown and which do not, thus achieving precise control over the content of the page.
Summary
AnQiCMS provides a concise and powerful Markdown rendering mechanism. From enabling globally in the backend, to the automatic rendering of content fields in front-end templates, to implementing style beautification, mathematical formulas, and flow chart display through the introduction of third-party libraries, as well as|renderThe fine control provided by the filter greatly enhances the efficiency and presentation of content operations.Master these methods and you will be able to fully utilize the advantages of AnQiCMS in content creation, presenting high-quality and structured content to users.
Frequently Asked Questions (FAQ)
1.I have enabled the Markdown editor in the background, but why is the Markdown syntax not rendered on the front-end page, instead of showing the original text symbols?
This is usually because your template file does not use|safefilters. For example, if your article contentarchive.ContentContains Markdown, you should use it in the template{{archive.Content|safe}}instead of{{archive.Content}}.|safeThe filter tells the template engine that this content is safe HTML, which can be parsed and displayed directly without escaping processing.
2. Why is my mathematical formula or Mermaid flowchart not displayed correctly and only the original text code is shown?
The enablement of the Markdown editor only affects the input of content, while advanced rendering features such as MathJax and Mermaid require the manual introduction of the corresponding JavaScript libraries in the front-end template. Please check yourbase.htmlOr has the script for MathJax and Mermaid been correctly introduced according to the instructions in the article.In addition, make sure that the formula and chart syntax you use in the Markdown content is the correct syntax supported by these libraries.mermaid...code block.
3. I have also used Markdown syntax in the custom model field, but it is not automatically rendered as HTML. What should I do?
For custom fields other than articles, pages, and other core content fields, AnQiCMS does not automatically perform Markdown rendering. You need to manually use it in the template.|renderA filter is used to explicitly tell the template engine to perform a transformation. For example, if your custom field name iscustom_description, you should write it in the template as{{archive.custom_description|render|safe}}This ensures that the Markdown content is correctly rendered inside it.