As a senior CMS website operator, I know that the presentation of high-quality content is crucial for attracting and retaining users.Markdown is a lightweight markup language that is favored by content creators for its concise and efficient features.AnQi CMS provides support for Markdown content, but it is necessary to make some template configurations to ensure that it is displayed correctly and beautifully on the web.
Below, I will elaborate on how to correctly display Markdown content on the Anqi CMS web page, including the integration methods for default styles, mathematical formulas, and flowcharts.
A detailed guide on correctly displaying Markdown content on Anqi CMS web pages
The Anqi CMS provides a convenient creative experience for content creators through its built-in Markdown editor.However, in order to present these Markdown contents with the expected visual effects on the website front-end and support advanced features such as mathematical formulas and flowcharts, we need to make some necessary configurations in the template file.Here are the detailed configuration steps and operation instructions.
Step 1: Enable Markdown editor
Firstly, ensure that your security CMS system has enabled the Markdown editor feature.This setting is the foundation of content creation, allowing you to write and edit content in Markdown format in the background.
You need to log in to the AnQi CMS backend management interface, navigate toGlobal Settingsand then selectContent settings.On this page, you will find the options to enable Markdown editor.Please check or select to enable this feature and save the settings.Once the editor is enabled, you can choose Markdown as the content input method when creating or editing documents.
Step 2: Integrate Markdown default style
The Markdown content, when parsed into HTML, may appear plain or not in line with the overall website design if there is no corresponding CSS style.To provide a good and consistent reading experience, we can introduce a universal Markdown style library, such as GitHub's Markdown CSS.
You need to edit your website template file. According to AnqiCMS template conventions, the common header code is usually locatedbase.htmlin the file. Please find the<head>part and add the following line<link>Tags to introduce the GitHub-style 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" />
By introducing this external stylesheet, your Markdown content will be automatically applied a set of beautiful, readable default styles after being converted to HTML, including the formatting of elements such as headings, paragraphs, lists, and code blocks, thereby greatly enhancing the user experience.
Step 3: Support rendering of mathematical formulas
For websites that need to include mathematical formulas in their content, such as technical blogs or educational platforms, relying solely on default Markdown parsing is not enough.To display complex mathematical expressions correctly on the web, we need to use professional mathematical typesetting engines such as MathJax.
Similarly, you need tobase.htmlthe file<head>Part, add the following after the CSS link added in the previous step<script>tag to introduce the MathJax library:
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
MathJax can parse LaTeX, MathML, and other formats of mathematical formulas, and render them into high-quality images or text, ensuring that mathematical content is displayed clearly and accurately across various browsers and devices.
Step 4: Implement the visualization of the flowchart
In addition to text and formulas, flowcharts are another important means of conveying information, especially when explaining business logic, code flow, or complex system architecture.AnQi CMS combined with the Mermaid.js library can implement embedding text-based flowcharts in Markdown and automatically render them as SVG graphics.
You need tobase.htmlthe file<head>section, after all other scripts, add the following<script>code block to introduce the Mermaid.js 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>
Mermaid.js allows you to define various charts such as flowcharts, sequence diagrams, Gantt charts, and more using simple text syntax.With the above configuration, when your Markdown content contains Mermaid syntax, it will be automatically recognized and rendered into a visual chart by Mermaid.js when the page loads, greatly enhancing the expressiveness of the content.
flexibility in content creation and template rendering
After the above configuration is completed, content creators can freely create content in the background using the Markdown editor, which includes default styles, mathematical formulas, and flowcharts. When these contents passarchiveDetailorpageDetailWhen the tag is called in the front-end template, the system will automatically convert Markdown to HTML, and cooperate with the introduced styles and scripts to present rich visual effects.
It is worth mentioning that even if you have turned off the Markdown editor in the global content settings of the Anqicms, the template tags still provide flexibility for converting Markdown content. When you usearchiveDetailorpageDetailWhen getting content, you can addrender=trueparameters to force the system to convert Markdown content. For example:
<div>文档内容：{% archiveDetail archiveContent with name="Content" render=true %}{{archiveContent|safe}}</div>
ThisrenderParameters grant content operators finer-grained control, allowing them to decide whether to perform Markdown to HTML conversion for specific content blocks without relying on global settings, thereby maintaining a high degree of flexibility in content presentation.
Operational benefits
By configuring the steps above, your safe CMS website will be able to perfectly support the display of Markdown content, including basic formatting, complex mathematical formulas, and intuitive flowcharts.This has not only improved the efficiency and convenience of content creation, but also greatly enhanced the reading experience of readers.High-quality, structured content is easier for search engines to crawl and understand, which helps improve the SEO performance of the website, thereby attracting more users and improving user retention rates.As a website operator, embracing Markdown and ensuring its perfect presentation on the front end is undoubtedly a key step to enhancing the value of website content and user experience.
Frequently Asked Questions (FAQ)
1. If I have configured CDN resources but the Markdown content is still not rendered correctly on the web page, how should I troubleshoot the problem?
First, please check whether the CDN link you have included in the file is correct and accurate, including the URL address,base.htmland other relevant details.crossoriginandreferrerpolicyProperties.Make sure these links do not have spelling errors and the CDN service is accessible.Next, check your browser's developer tools (F12) network (Network) tab to see if these CDN resources have loaded successfully.If the loading fails, it may be due to a network problem or the CDN service is temporarily unavailable.cdnjs.cloudflare.comandcdn.jsdelivr.netLoad scripts and styles.Finally, please confirm that you have enabled the Markdown editor in the background "Global Settings" -> "Content Settings" and that the content you are editing is indeed in Markdown format.
2. Can I disable Markdown rendering or the loading of formulas/process diagrams on certain pages?
Yes, you can achieve this. For Markdown rendering itself, such as article details or single-page details,archiveDetailandpageDetailTag supportrenderThe parameter. If you do not want the content of a page to be rendered by Markdown, even if the global setting is enabled, you can alsorenderthe parameter tofalse. For external scripts like MathJax and Mermaid.js, although they are usually placed inbase.htmlYou can achieve global loading in Chinese, but you can also use advanced template control according to your needs. For example, you can use conditional judgments (such asbase.htmlto use conditional judgments (such as{% if archive.IsMathContent %}）To decide whether to load these scripts, or to write JavaScript code to dynamically remove or stop the initialization of these libraries after the page has been loaded, but this usually involves more complex template logic and frontend development knowledge.
3. Will introducing MathJax and Mermaid scripts significantly affect the page loading speed of the website?
The inclusion of any external script may affect the page loading speed, but MathJax and Mermaid loaded through CDN are usually optimized. They use asynchronous loading (async) A property, which means they will not block the rendering of other content on the page. MathJax usually starts rendering formulas after the page content is parsed, and Mermaid also providesstartOnLoad: trueThe option comes to automatically initialize after the page is fully loaded.To further optimize performance, you can consider the following strategies: ensure that these scripts are only loaded on pages where these features are actually needed; locally cache CDN resources; or, if your website's user base is widely distributed, choose a CDN node closer to the user.In most cases, the functional improvements brought by these libraries far outweigh their minor impact on performance, especially for professional content websites.