How to correctly render Markdown content as HTML and display mathematical formulas or flowcharts in Anqi CMS?
In Anqi CMS, using Markdown format to write content not only improves editing efficiency, but also maintains the structured and readable nature of the content.When the content involves complex mathematical formulas or requires a clear flowchart, the power of Markdown can be demonstrated.The Anqi CMS provides good support for this, let's take a look at how to correctly render and display these advanced contents on the website.
Step 1: Enable Markdown editor
First, make sure that your security CMS system has enabled the Markdown editing feature. This setting is usually in the background ofGlobal SettingsFind it.
Enter the Anqi CMS backend, find the left menu bar ofBackend settingsand click to enterContent settings. On this page, you will see an option, usually 'Enable Markdown Editor' or similar descriptions.Make sure this option is checked or enabled and save your changes.This is the foundation for the system to recognize and process Markdown content.
Second step: write Markdown content in the document
When the Markdown editor is enabled, you can write content using Markdown syntax when creating or editing documents.Markdown is concise and intuitive, allowing us to focus on the content itself.
For mathematical formulas, Markdown usually combines LaTeX syntax to write:
- Inline formula: Use a single dollar sign
$Wrap, for example:$\sum_{i=1}^n i = \frac{n(n+1)}{2}$It will be rendered as:(The sum of the first n natural numbers is n(n+1)/2). - Block formula(Displayed on a separate line): Use double dollar signs
$$Wrap, for example:
It will be rendered as: $( E=mc^2 )$$$ E=mc^2 $$
For flowcharts, Anqi CMS supports generating through Mermaid syntax.Mermaid allows you to describe diagrams using text and then automatically render them into graphics.Mermaid's syntax is very intuitive, withmermaidThe keyword is followed by the chart type and definition, and enclosed in three backticks ` . For example, a simple flowchart can be like this:
graph TD;
A[Start] --> B{Decision};
B --> |Yes| C[Perform action];
B --> |No| D[End];
C --> D;
You can directly paste or write these Markdown codes in the document content editor of AnQi CMS.
Step 3: Adjust the website template to support rendering
Markdown content, especially mathematical formulas and flowcharts, need to rely on front-end JavaScript libraries to be correctly rendered in the browser.The Anqi CMS template system is very flexible, allowing us to easily integrate these libraries.You need to modify the template file, usually the "skeleton file" of the website——base.htmlto include the necessary CSS and JavaScript.
base.htmlThe file is usually located in the root directory of your theme folder, for example./template/default/base.htmlIn the file.<head>Within the tag, we need to add the following code:
Provide basic styling for Markdown content:To make the rendered content of Markdown more visually appealing and conform to standards, 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" />Supports display of mathematical formulas:MathJax is a powerful JavaScript rendering engine that can render LaTeX-formatted mathematical formulas into high-quality layouts.
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>Support flowchart display:The Mermaid library can parse Mermaid syntax and convert it into SVG graphics.It should be noted that Mermaid usually needs to be imported and initialized as an ES module.
<script type="module"> import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs'; mermaid.initialize({ startOnLoad: true }); </script>Make sure these scripts are placed in
<head>tags so that the page can be processed in time during loading. Among them, the initialization code of Mermaidmermaid.initialize({ startOnLoad: true });Tell Mermaid to automatically find and render all Mermaid charts after the page is loaded.
Step 4: Make sure the content is displayed correctly on the document details page.
In Anqi CMS, document content (for examplearchive.Content）usually gets automatically rendered as HTML. However, if you are storing Markdown content in custom fields or want to explicitly control the rendering behavior, you can do so in the template byarchiveDetailLabel collaborationrenderParameter to achieve.
For example, in your article detail template (usually{模型table}/detail.html), the display of document content snippets may be as follows:
{%- archiveDetail articleContent with name="Content" render=true %}
{{articleContent|safe}}
here,render=trueIt ensured that Markdown content would be processed into HTML. And|safeThe filter is crucial, it tells the template engine that this content is safe HTML, which does not need to be escaped again, otherwise you might see the original HTML tags instead of the rendered effect.
If your Markdown content is stored in a custom field (for example, you have created a field namedintroductionThe custom field to store Markdown introduction), then you may need to use it similarlyrenderFilter:
{% archiveDetail introduction with name="introduction" %}
{{introduction|render|safe}}
After completing these steps, you can publish a document containing Markdown, mathematical formulas, and flowcharts, and then visit the front-end page for testing.Remember to clear your browser cache before viewing the effect to ensure that the latest template files and scripts are loaded.
With the above configuration, your Anqi CMS website can not only publish standard text content, but also present complex mathematical formulas and dynamic flowcharts in a professional and intuitive manner, greatly enriching the expressiveness of the website content.
Frequently Asked Questions (FAQ)
1. Why is my mathematical formula or flowchart not displayed, but only the original code?This is usually because the front-end JavaScript rendering library has not been loaded or initialized correctly. Please check the following points:
- Is the Markdown editor enabled?Please confirm that the Markdown editor has been enabled in the "Content Settings" of the Anqi CMS backend.
- Is the template file modification correct?Please check carefully.
base.htmlIn the file, whether the CDN links of MathJax and Mermaid are complete, the paths are correct, and they are all placed in<head>the tags. Especially Mermaid'sscript type="module"andmermaid.initialize()Have all been added? - Whether used when outputting content?
|safeFilterIn{% archiveDetail %}Make sure to use tags when outputting content,|safeFilter, for example{{articleContent|safe}}otherwise the HTML code will be escaped and cannot be rendered. - Network connection issue: Confirm that your server and visitors can connect to the CDN service (
cdnjs.cloudflare.comandcdn.jsdelivr.net), if the network is restricted, these scripts may not load.
2. I only want to use Markdown text formatting, not mathematical formulas and flowcharts, can I?Of course you can. If you only need Markdown text formatting and styling (such as headings, lists, code blocks, etc.), and do not need support for mathematical formulas and flowcharts, then you just need tobase.htmlAdd the GitHub Markdown CSS link.You can omit the JavaScript inclusion of MathJax and Mermaid, which can reduce the resources loaded on the page.
3. Will these third-party CDN resources affect the loading speed or stability of the website?Using CDN (Content Delivery Network) usually speeds up the loading of resources because CDN distributes resources to servers around the world, and users can obtain resources from the nearest node.cdnjs.cloudflare.comandcdn.jsdelivr.netSuch mainstream CDN services have very high stability and speed.However, any external dependency carries potential risks, such as temporary interruptions in CDN services or network congestion.For most small and medium-sized enterprise websites, this impact is usually negligible and the benefits outweigh the drawbacks.If you have high requirements for performance and stability and possess relevant technical capabilities, you can also consider downloading these JS/CSS files to host them on a local server, but this will increase maintenance costs.