How to correctly parse and display Markdown formatted text in article content?
In Anqi CMS, writing articles in Markdown format is an efficient and elegant way of content creation, which makes our content structure clearer and layout more flexible.Especially for technical articles that need to include code, mathematical formulas, and even flowcharts, Markdown editors are an indispensable tool.How can you ensure that these meticulously written Markdown texts are correctly parsed and perfectly presented on the front end of the website?Let's explore step by step.
Enable Markdown editor
Firstly, to enjoy the convenience of Markdown, we need to enable this feature on the AnQi CMS backend. The operation is very simple:
- Log in to your Anqi CMS backend.
- Find and click onGlobal Settings.
- EnterContent settingsTab.
- Here, you will see an option to enable Markdown editor. Check it and save your settings.
Once enabled, when you create or edit an article, the document editor will switch to Markdown mode, and you can start writing content using Markdown syntax.
Write Markdown text in the article
In the Markdown editor, you can create content according to standard Markdown syntax, for example:
- Use
#Create a title (# 一级标题,## 二级标题) - Use
*or_Italic or bold text (*斜体*,**加粗**) - Use
-or*Create an unordered list, using1.Create an ordered list. - Use backticks to create inline code, or use triple backticks.
```pythonEnclose the code block. - Insert an image.
The AnQi CMS Markdown editor also supports more advanced content, such as mathematical formulas and flowcharts, which is very practical for articles in many professional fields.You can directly embed LaTeX mathematical formulas or Mermaid flowcharts in the editor, and the system will save them as original Markdown text.
Ensure that the Markdown content is displayed correctly on the web page.
The article content is saved in Markdown format, and Anqi CMS will automatically convert it to HTML when outputting the content to the front-end of the web page.However, to ensure that the converted HTML content is not only structurally correct but also aesthetically pleasing and correctly renders mathematical formulas and flowcharts, some additional configuration is required in the website template.
These settings usually need to be in your website template.base.htmlModify in the file, it is usually located/template/{您的模板目录}/below. Please add the following content to the file:<head>within the tag:
Apply default styles to Markdown content:To make the HTML elements converted from Markdown (such as headings, lists, code blocks) have a good default visual effect, you can introduce GitHub-style Markdown CSS.
<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" />Correctly display mathematical formulas (MathJax):If you use mathematical formulas in LaTeX syntax in an article, you need to include the MathJax library to parse and render them.
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>Correctly display the flowchart (Mermaid):For flowcharts drawn using Mermaid syntax, it is necessary to introduce the Mermaid library and initialize it.
<script type="module"> import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs'; mermaid.initialize({ startOnLoad: true }); </script>
Add these code snippets tobase.htmlthe file<head>The area can ensure that these rendering libraries are correctly referenced when the page is loaded, thereby allowing Markdown content, including complex mathematical formulas and flowcharts, to be perfectly presented on your website.
Logic for rendering content in the template
In Anqi CMS templates, whether it is an article(archive) or a single page(pageThe content field, which is usually automatically converted to HTML in the background. When you call these contents in the template, for example usingarchiveDetailtag to obtainContentField and make sure to use it when outputting|safefilter.
For example, you might display the article content like this in your article detail template:
{% archiveDetail articleContent with name="Content" %}
{{ articleContent|safe }}
Here|safeThe filter is very important as it tells the template engine,articleContentThe content in the variable is safe HTML and does not need to be escaped again. If it is missing|safe, The browser may display HTML tags as plain text, causing the article layout to be disordered and even出现乱码.
Furthermore,archiveDetailthe tags also providerenderParameters, allow you to manually control the conversion from Markdown to HTML. When you turn off the Markdown editor in the content settings, but the article content is still in Markdown format, you can userender=trueThe parameter is forced to be converted:
<div>文档内容：{% archiveDetail archiveContent with name="Content" render=true %}{{archiveContent|safe}}</div>
On the contrary, if you want to obtain the original Markdown text without any conversion (for example, if you want to use a JavaScript library for custom rendering on the front end), you can userender=false:
<div>原始Markdown内容：{% archiveDetail archiveContent with name="Content" render=false %}{{archiveContent|safe}}</div>
By following these steps, you can not only easily create content using Markdown in Anqi CMS, but also ensure that these contents are presented professionally, accurately, and beautifully on the website front-end.This will undoubtedly greatly enhance your content creation efficiency and website user experience.
Frequently Asked Questions (FAQ)
Q1: Why is the article displayed as raw Markdown text on the website front end instead of being parsed into HTML, even though I have enabled the Markdown editor and written content?
A1: This is likely because you did not use|safeFilter. After the Safe CMS converts Markdown content to HTML, for security reasons, the template engine defaults to escaping all output content.|safeThe filter informs the template engine that the content you output is expected HTML, no need to escape it again, so the browser can render HTML tags correctly. Please check your article detail template to ensure that the outputContentfields were used{{ archiveContent|safe }}.
Q2: I inserted mathematical formulas or flowcharts into the article, but they only display as raw code or text and are not rendered as charts or formulas. How can I solve this?
A2: Rendering of mathematical formulas (such as LaTeX) and flowcharts (such as Mermaid) requires specific JavaScript libraries to be processed on the browser side.Although the Anqi CMS backend will convert this Markdown content to standard HTML, the browser will not be able to recognize and render it if the corresponding JS library is not introduced on the front end.Make sure you have followed the instructions in the article, in your template'sbase.htmlthe file<head>In the tag, the CDN link and initialization code for MathJax (used for mathematical formulas) and Mermaid (used for flowcharts) were correctly introduced.
Q3:archiveDetaillabel'srenderWhat is the role of the parameter? In what circumstances do I need to use it?
A3:renderThe parameter allows you to manually control whether the Markdown content is converted to HTML in the background. By default, if the Markdown editor is enabled in your background,archiveDetailIt will automatically convert Markdown to HTML. But if you have turned off the Markdown editor in the background, and the content of the article itself is in Markdown format, you can userender=trueForce the conversion. Otherwise, if you wish to obtain the original Markdown text (for example, if you plan to use a custom JavaScript library to handle Markdown on the front end), you can userender=falsePrevent automatic conversion in the background. In most cases, it is usually not necessary to explicitly set if you have enabled the Markdown editor in the backgroundrender=trueBut understanding its function can help you control the display of content more flexibly in specific scenarios.