How to display mathematical formulas and flowcharts with Markdown in AnQiCMS?
In content operation, sometimes we need to display complex mathematical formulas or clear flow charts, especially in technical articles, data reports, or educational content.AnQiCMS with its powerful Markdown editor provides us with the convenience to meet this requirement.By simple configuration and introducing the necessary library files, you can perfectly present these professional contents on the website front-end.
Enable AnQiCMS Markdown Editor
Firstly, you need to make AnQiCMS recognize and handle Markdown format content, and you need to make corresponding settings in the background.Please go to the "Global Settings" in the AnQiCMS admin panel, find the "Content Settings" option.Here, you will see an option to "enable Markdown editor", check it and save the changes.After enabling this feature, you can choose Markdown format to write content when creating or editing documents.
Insert mathematical formulas and flowcharts in the content
Enable Markdown editor after, in the document content area, you can directly use Markdown syntax to write mathematical formulas and flowcharts.
Fora mathematical formulaThis is usually done in the following way:
- Inline formula:Using a single
$symbol enclosed, for example$E=mc^2$. - Inline formula:Using double
$$Symbols enclosed, formulas will be displayed on separate lines and centered, for example$$ \sum_{i=1}^n i = \frac{n(n+1)}{2} $$.
ForFlowchartYou can use Mermaid syntax to place it in a special Markdown code block:
```mermaid
graph TD;
A[开始] --> B{决策};
B -- 是 --> C[执行操作];
C --> D[结束];
B -- 否 --> D;
```
These syntaxes will be recognized in the Markdown editor, but to ensure they are displayed correctly on the front-end page, further steps are required.
Add basic styles to Markdown content
To make your Markdown content look tidy and professional on your website, we can introduce a universal Markdown stylesheet.This is like putting on a beautiful dress for text content. You need to place it in the public header file of the website (usuallybase.html, located/templateIn the folder of the template you are using under the directory<head>Area, add the following CDN links:
<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" />
This stylesheet provides a set of default styles for the HTML elements rendered by Markdown, significantly enhancing the visual appeal and readability of the content.
Ensure the correct display of mathematical formulas
The rendering of mathematical formulas requires a dedicated JavaScript library to convert Markdown-formatted formulas into browser-displayable mathematical symbols.MathJax is a very popular choice, it can convert formulas in LaTeX and other formats into high-quality layouts.Likewise, inbase.htmlthe file<head>The area, following the Markdown style sheet, add MathJax CDN reference:
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
This script will asynchronously load the MathJax library and automatically scan and render mathematical formulas on the page after it is loaded.
Implement the dynamic rendering of flowcharts.
The display of flowcharts can be achieved with the Mermaid library.Mermaid allows you to create various types of diagrams using simple text syntax.To enable it, pleasebase.htmlthe file<head>or<body>Add the following code before the end tag:
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
</script>
This code imports the Mermaid library and initializes it to automatically recognize and render the flowchart definitions in Markdown code blocks after the page has loaded.
Template content rendering settings
After completing the reference to all the external libraries, the most critical step is to ensure that your AnQiCMS template can correctly render Markdown content into HTML. In obtaining the template tags for document content (such as those commonly used in document detail pages, for example, in the document detail page),archiveDetailIn the tag），you need to handle it specially.
AnQiCMS template system provides convenience for rendering Markdown content. You are usingarchiveDetailLabel can be added when fetching contentrender=trueThe parameter tells the system to automatically convert Markdown formatted text to HTML. Moreover, to avoid the HTML code being doubly escaped by the browser and causing display exceptions, it is necessary to use it in conjunction with|safefilter.
Therefore, the fragment of the document body that you retrieve and display in your template may look like this:
{% archiveDetail articleContent with name="Content" render=true %}
{{ articleContent|safe }}
With such settings, you can use the Markdown editor in AnQiCMS backend to write content containing mathematical formulas and flowcharts, which can be correctly parsed, rendered, and beautifully presented on the front-end page.
Frequently Asked Questions (FAQ)
Q: Why did the mathematical formulas and flowcharts still not display after I added the CDN and template code according to the steps?
- A:When encountering this situation, please check the following key points first:
- Is the Markdown syntax correct?Confirm the mathematical formula you entered in the background (for example
$$...$$) and the flowchart (for examplemermaid ...The syntax complies with Markdown and MathJax/Mermaid standards. Any minor grammar error can lead to rendering failure. - Are the template rendering parameters and filters applied correctly?Ensure that your template uses it to get content when
{% archiveDetail ... render=true %}and adds it when outputting{{ variable|safe }}. If missingrender=true, Markdown will not be converted to HTML by AnQiCMS; if missing|safeThe converted HTML may be escaped again by the browser, causing MathJax and Mermaid to fail to recognize and process. - Is the CDN link valid and accessible?Use the browser developer tools' Network tab to check if the CDN files of MathJax and Mermaid are loaded successfully, without any 404 or other network errors.
- Is there a JavaScript error in the browser console?In the browser developer tool's Console tab, check if there are any JavaScript error reports related to MathJax or Mermaid, which will help locate the problem.
- Is the Markdown syntax correct?Confirm the mathematical formula you entered in the background (for example
- A:When encountering this situation, please check the following key points first:
Q: Can I download the MathJax and Mermaid library files to the local server instead of using CDN?
- A:Absolutely. If you have special considerations for the loading speed, stability, or reliance on CDN of the website, you can download these JavaScript library files to your server.Then, will
base.htmlReplace the CDN link with the relative paths of these local files. For example, you can store the files in/public/static/js/directory, thensrcThe property to/static/js/mathjax.jsor/static/js/mermaid.esm.min.mjsThe specific path depends on the actual storage location of your file.
- A:Absolutely. If you have special considerations for the loading speed, stability, or reliance on CDN of the website, you can download these JavaScript library files to your server.Then, will
Q: Does AnQiCMS support other mathematical formula or flowchart rendering libraries besides MathJax and Mermaid?
- A:AnQiCMS itself provides a powerful Markdown editor and the core capability to render Markdown content to HTML.This means theoretically, as long as any third-party library that can be rendered on the front-end through JavaScript, you can try to integrate it into your AnQiCMS website.You just need to find the CDN link or local file of the corresponding library, add it to your template according to its official documentation, and ensure that the content is output in the correct HTML structure so that these libraries can recognize and process it further.