How to correctly render Markdown formatted article content in AnQi CMS and display it?
Today, with the increasingly efficient content creation, Markdown is favored by a large number of content creators for its concise syntax and focus on the content itself.AnQi CMS is aware of this trend and provides powerful features, allowing you to easily convert Markdown formatted article content into exquisite HTML pages, and supports richer display effects such as mathematical formulas and flowcharts.
Enable Markdown Editor: The First Step of Content Creation
Firstly, to make AnQi CMS recognize and process Markdown content, you need to make simple configurations in the background.This is like telling the system that you want to write the article in Markdown.
- Log in to the AnQi CMS background.
- Navigate toGlobal Settingsand then selectContent settings.
- Here, you will find an option toEnable Markdown editor. Check this option and save the settings.
Once enabled, when you create or edit an article, the input box for the article content will become a Markdown editor, making it convenient for you to create content using Markdown syntax.
The magic of Markdown to HTML: automatic and manual rendering
When the Markdown editor is enabled, Anqie CMS will default to processing the content you write in Markdown syntax, converting it into an HTML structure that browsers can understand.However, in certain specific template invocation scenarios, you may need to control this rendering process more explicitly.
We usually use in template filesarchiveDetailTag to get the detailed content of the article. For example, to get the Markdown original text of the article content:
{# 默认用法，自动获取当前页面文档 #}
<div>文档内容：{% archiveDetail with name="Content" %}</div>
HereContentField is the content you input in the background Markdown editor.
To ensure that Markdown content is rendered correctly as HTML and displayed safely, it is usually used torenderParameters andsafeFilter:
render=trueThis parameter explicitly indicates that the system should render the Markdown content obtained and convert it to HTML.|safeThis is a filter of the Django template engine. Because of security considerations, the system will default to automatically escaping HTML tags (such as<Will become<），to prevent XSS attacks. When you are sure the content is safe and needs to be displayed as HTML, use|safeThe filter can cancel this automatic escaping so that the browser can correctly parse and display HTML.
Therefore, in your template file, to retrieve and display rendered Markdown content is usually written like this:
{# 假设archiveContent变量存储了Content字段的内容 #}
<div>
{%- archiveDetail articleContent with name="Content" %}
{{articleContent|render|safe}}
</div>
Or specify rendering directly in the tag:
<div>
{%- archiveDetail with name="Content" render=true %}{{archiveContent|safe}}
</div>
In this way, the Markdown content you write can be perfectly displayed in HTML on the front-end page.
Enhance display effects: introduce external styles and features
Markdown not only provides basic text formatting, but also, when combined with third-party libraries, can achieve more advanced display effects, such as mathematical formulas and flowcharts.The AnQi CMS also supports enhancing these features by introducing the corresponding CDN resources in the template.
These enhanced features usually need to be added to yourbase.html(or any template file referenced as a public header, such asbash.htmlorpartial/header.html）的<head>the tag by adding the corresponding script and style link.
Markdown default style:To make the rendered Markdown content more aesthetically pleasing and readable, you can introduce a generic GitHub style Markdown stylesheet. In your
base.htmlof<head>Partly added:<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" />Then, you may need to wrap the rendered content in a container with
markdown-bodyclassdivto make the styles take effect:<div class="markdown-body">{{ articleContent|render|safe }}</div>.Proper display of mathematical formulas on the web (MathJax):If you need to embed LaTeX-formatted mathematical formulas in an article, MathJax is a very powerful solution. In
base.htmlof<head>Partly added:<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>This script will automatically detect mathematical formulas in the page and render them.
Correct display of flowcharts on the web (Mermaid):Mermaid allows you to create diagrams, sequence diagrams, and more using simple text syntax. In
base.htmlof<head>Partly added:<script type="module"> import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs'; mermaid.initialize({ startOnLoad: true }); </script>Mermaid scans specific code blocks on the page (usually
graph TD/sequenceDiagramTranslate Mermaid syntax block and convert it into an interactive graphic.
By following these steps, your Markdown article can not only be rendered correctly as HTML, but also have professional styles, dynamic mathematical formulas, and clear flowcharts, greatly enhancing the expressiveness and user experience of the content.AnQi CMS encapsulates technical details in the backend, allowing content creators to focus on the content itself and not worry about complex rendering logic.
Frequently Asked Questions (FAQ)
Q: The Markdown editor is enabled, but the article content is still displayed as plain text without being converted to HTML. Why is that?A: This is usually due to not using the parameters correctly in the template file
render=trueto indicate that the system should render Markdown, or not using them|safeA filter to remove the automatic escaping of HTML. Please check yourarchiveDetailtags whether they includerender=trueand|safeFor example:{{articleContent|render|safe}}.Q: Why are mathematical formulas and flowcharts inserted in the article not displayed normally on the front-end page?A: Even though Markdown content itself is rendered as HTML, advanced features like MathJax and Mermaid require additional JavaScript libraries to parse and display. Make sure you have followed the instructions in the documentation on your website,
base.htmlOr other public header template's<head>Part, correctly introduced CDN scripts for MathJax and Mermaid.Q: Can I use Markdown and render it as HTML in category descriptions or single page content, besides the article detail page?A: Yes, the Anqi CMS Markdown rendering capability is not limited to article details. When getting the category description (
categoryDetail) or single page content (pageDetailWhen these fields support Markdown, you can also use the filter to render its content as HTML. For example:render=trueParameters and|safeFilter to render the content as HTML. For example:{{categoryContent|render|safe}}.