How to display Markdown formatted content on a front-end page (including mathematical formulas and flowcharts)?
The Anqi CMS provides powerful and flexible content management capabilities for users, among which the support for Markdown format greatly enhances the efficiency of content creators.Whether it is to write technical articles that require the display of complex mathematical formulas or product documents that need clear flowcharts, AnQi CMS can help you beautifully present these contents on the front-end page.
To achieve this goal, we need to proceed in several steps, from backend settings to frontend template adjustments, to ensure that the content is correctly parsed and rendered.
Step 1: Enable Markdown editor in the background
First, you need to enable the Markdown editor in the Anqi CMS backend management interface. This is the foundation for creating content that includes mathematical formulas and flowcharts.
- Log in to the AnQi CMS background.
- Go to the “Global Settings” menu and click on “Content Settings”.
- On the Content Settings page, find the “Enable Markdown Editor” option and turn it on.
- Save your settings.
After enabling, when you are editing articles, single pages, category descriptions, and other content, you can choose to use the Markdown editor to create.
Step 2: Create mathematical formulas and flowcharts in the content
Enable Markdown editor after, you can use Markdown syntax in the text content to write mathematical formulas and flowcharts.
- Mathematical formula:The mathematical formula in Markdown can usually be written in LaTeX syntax and enclosed with special symbols.
- Inline formula: Enclosed by a single dollar sign, for example
$E=mc^2$. - Block formula (displayed independently in a centered line): Enclosed with double dollar signs, for example
$$ \int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2} $$.
- Inline formula: Enclosed by a single dollar sign, for example
- Flowchart:Flowcharts are usually implemented in Markdown code blocks using Mermaid syntax.
- In the Markdown editor, create a code block and specify the language as
mermaidFor example:graph TD; A[Start] --> B{Decision}; B -- Yes --> C[Perform action]; C --> D[End]; B -- No --> E[Wait]; E --> A;This content will be stored in the database in its original Markdown text format after you save it, waiting to be parsed and rendered by the front-end.
- In the Markdown editor, create a code block and specify the language as
Step 3: Ensure the front-end page can correctly render Markdown content
The AnqiCMS Markdown editor itself has already converted Markdown content to HTML, but the complex rendering of mathematical formulas and flowcharts requires additional JavaScript libraries to handle.This is like a browser being able to parse HTML, but to display beautiful charts or interactive components, you need to introduce the corresponding scripts.You need to include the necessary CDN resources in the frontend template file.
Find the directory of the template you are currently using (usually in/template, for exampledefault), then open the template under it.base.htmlFile. This file usually contains the common header of the website (<head>) and footer area, which is an ideal place to introduce global scripts and stylesheets.
Please add the following code snippet tobase.htmlthe file<head>Inside the tag:
Apply the default Markdown style:To make the HTML content rendered by Markdown have good formatting and style, we can introduce a universal Markdown stylesheet.
<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" />Implement the correct display of mathematical formulas:MathJax is a powerful JavaScript rendering engine used to display mathematical formulas in web browsers.
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>Implement the correct display of flowcharts:Mermaid is a JavaScript library that can create charts and visualizations from text definitions similar to Markdown.
<script type="module"> import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs'; mermaid.initialize({ startOnLoad: true }); </script>After completing these additions, save
base.htmlFile. So, when the browser loads your page, these scripts and styles will be included, thus enabling parsing and rendering of mathematical formulas and flowcharts.
Step 4: Control the rendering method of content fields in the template
Even if you use a Markdown editor in the background, how the final content is displayed on the front end still needs to be called and controlled in the template file.AnQi CMS provides flexible template tags, allowing you to decide whether to convert content fields from Markdown to HTML.
Taking the document detail page as an example, you usually usearchiveDetailtags to display article content. TheContentfield supports onerenderParameters used to control Markdown conversion behavior.
By defaultIf the Markdown editor is enabled on the backend,
ContentThe field will automatically convert Markdown to HTML when called. You would typically call it like this:{% archiveDetail archiveContent with name="Content" %} {{ archiveContent|safe }}Here
|safeFilters are crucial, they tell the template engine,archiveContentThe HTML content is safe, no need for double escaping, and can be output directly.If you want to explicitly control whether Markdown rendering is performedyou can use
renderparameters:render=trueForce Markdown content to be rendered.render=falseDo not render Markdown, output the original Markdown text directly.
{# 强制进行Markdown转换，并安全输出HTML #} {% archiveDetail archiveContent with name="Content" render=true %} {{ archiveContent|safe }} {# 不进行Markdown转换，输出原始Markdown文本 #} {% archiveDetail rawContent with name="Content" render=false %} {{ rawContent }}This
renderParameters are very useful in handling some special cases, such as when you may want to display the Markdown syntax itself on the page instead of the rendered effect, or when your content includes some HTML generated by other systems and you do not want it to be parsed again by the Markdown parser.
By following these four steps, your secure CMS website can perfectly display Markdown formatted content on the front end, including complex mathematical formulas and clear flowcharts.
Frequently Asked Questions (FAQ)
Q1: I have enabled Markdown editor according to the steps and written mathematical formulas and flowcharts in the content, but these contents still only display as raw text on the front-end page without being rendered. Why is that?
A1:This usually happens because the frontend template file is missing (base.htmlor other files containing your website<head>The template file) correctly introduces the CDN resources used to render mathematical formulas (MathJax) and flowcharts (Mermaid), or the position of introduction is incorrect. Please carefully check whether the three CDN links provided in the third step have been added tobase.htmlof<head>Within the tags, and make sure there are no syntax errors. Also, ensure that you call it in the templateContentfields were used|safeFilter, for example{{ archiveContent|safe }}to prevent HTML content from being escaped.
Q2: I found that the Markdown content style on the page is a bit chaotic, or the formulas and flowcharts can be displayed but the style is not good, how to unify the display effect of these contents?
A2:Ensure that the default style of Markdown content is beautiful, depending on what you introduce inbase.htmlthe first CDN resource introduced ingithub-markdown-css. This CSS file provides a set of concise and universal Markdown rendering styles.If the style is still not satisfactory, you can choose: 1. Find another Markdown CSS library that better suits your website style and replace it;2. In your custom CSS file, formarkdown-bodyWrite additional CSS rules for the class or its internal elements, overriding or enhancing the default styles.For formulas and flowcharts, MathJax and Mermaid usually come with good default styles, but if you have specific needs, you can refer to their respective official documents to learn how to customize the configuration.
Q3: How should I set up an article that contains both Markdown-written content and some directly pasted HTML code so that they both display correctly without any errors?
A3:In such a mixed content situation, it is recommended to enable Markdown editor in the background and ensure it is called in the templateContentUse field whenrender=trueparameter and always append|safeFilter, for example{{ archiveContent|safe }}. Anqi CMS's Markdown editor usually recognizes and retains HTML tags within Markdown content,render=trueAttempts to convert Markdown sections to HTML, and|safeIt ensures that whether it is the HTML converted by the editor or the HTML pasted directly, it can be parsed as original HTML by the browser. If the HTML part is still escaped, please confirm again|safeIs the filter being used correctly.