How to implement Markdown format content rendering and display on the AnQiCMS web page correctly?
In the digital age, the efficiency of content creation and publishing is the key to the success of a website.Markdown as a lightweight markup language, with its concise and efficient characteristics, is increasingly favored by content creators.AnQiCMS understands this need, providing users with excellent Markdown support, making content creation more convenient, while ensuring that the web page presents a beautiful and clear structure.
To ensure that Markdown-formatted content is correctly rendered and displayed on your AnQiCMS website, you mainly need to complete the following steps: first, enable the Markdown editor in the background; second, correctly call and render the content in the template; finally, according to your needs, introduce the necessary CSS styles and JavaScript libraries to support richer display effects, such as mathematical formulas and flowcharts.
Enable Markdown editor
The starting point lies in the AnQiCMS backend settings.First, you need to log in to the AnQiCMS backend management interface.In the sidebar navigation, find and click "Global Settings", then select "Content Settings".In this page, you will see an option related to the editor selection.Make sure you have checked or enabled the Markdown editor.After enabling this feature, when you write or edit articles, pages, and other content in the 'Content Management', you can directly create using Markdown syntax.AnQiCMS will automatically perform an initial parsing after receiving content in Markdown format.
Render Markdown content in the template
The content is stored in Markdown format on the backend and needs to be correctly converted to HTML and displayed in the front-end template.The AnQiCMS template system (similar to the Django template engine) automatically parses the content output by the Markdown editor into HTML by default.
When you call the article content field in the template file (such as thedetail.html), for example{% archiveDetail articleContent with name="Content" %}, and output it as{{articleContent|safe}}Here lies the key to using|safefilter.|safeThe filter tells the template engine that this content is safe HTML code and does not require double escaping.This, the HTML tags converted from Markdown, can be correctly recognized and rendered by the browser.
If the content you are using is not from the default Markdown editor (such as Markdown text stored in custom fields), or if you want to have more explicit control over the Markdown rendering process, you can use|renderFilter. For example,{{your_markdown_variable|render|safe}}. This|renderThe filter explicitly indicates that AnQiCMS will convert the specified Markdown text to HTML, then|safeEnsure it is safely output as HTML to the page.
Optimize the display style of Markdown content
Although AnQiCMS automatically converts Markdown to HTML, the default browser styles may not meet your requirements for content aesthetics.To make the Markdown content display better visual effects on the web page, you can introduce a special CSS stylesheet.A common practice is to use an open-source style library like GitHub-Markdown-CSS, which can provide a set of simple and professional default styles for your Markdown content.
You can add in the template file<head>Add the following CSS reference in the tag:
<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" />
It is recommended to add this code to your website templatebase.htmlIn the file. In this way, all pages of your website can inherit this Markdown style, making your Markdown content more unified and professional.
Supports advanced features such as mathematical formulas and flowcharts
For websites in the field of science and technology or data analysis, it may be necessary to display mathematical formulas or complex flow charts.AnQiCMS also considers these advanced requirements and allows implementation through integration with third-party JavaScript libraries.
Render mathematical formulas (MathJax)
If you need to display LaTeX formatted mathematical formulas in Markdown content, you can integrate MathJax. Similarly, inbase.htmlof<head>tags, add the following script:
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
After adding, the mathematical formula (such as$$E=mc^2$$) you write in Markdown can be correctly parsed and rendered by MathJax.
Render flowchart (Mermaid)
If your content includes flowcharts, sequence diagrams, and other charts, Mermaid is a powerful tool.By introducing the Mermaid library, you can directly draw diagrams in Markdown using concise text syntax. Inbase.htmlof<head>Add the following script inside the tag:
<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 this step, you can use Mermaid syntax in Markdown content to create various charts, which will be dynamically rendered as SVG graphics by the Mermaid library.
Summary
By following these steps, you can easily achieve the correct rendering and display of Markdown format content in AnQiCMS. From enabling the backend editor to applying it in the frontend template|safe(or|render|safe) Filter, then introducing CSS styles to beautify the display, up to integrating MathJax and Mermaid to support advanced features, AnQiCMS provides a complete and flexible solution, allowing your content creation and presentation to reach a professional level.This will greatly enhance your content operation efficiency and provide readers with a better reading experience.
Frequently Asked Questions (FAQ)
Q1: I have written the content using Markdown in the background, but the front-end displays the raw Markdown text instead of HTML, why is that?
A1:This usually happens because you did not use|safeFilter. The AnQiCMS template engine, for security reasons, defaults to escaping all output content to prevent XSS attacks.When the HTML content converted from Markdown is escaped, it will be displayed as raw text.Make sure your template code looks like this:{{archiveContent|safe}}of whicharchiveContentin your Markdown content variable.
Q2: I followed the steps to enable Markdown, and also introduced the MathJax or Mermaid script, but the mathematical formulas and flowcharts still do not display normally, how should I troubleshoot?
A2:First, make sure that your JavaScript and CSS references are placed inbase.htmlthe file<head>The tag is correct and the path is correct. Next, check whether the syntax of the mathematical formula or flowchart you write in Markdown is correct, as MathJax and Mermaid have strict syntax requirements.You can try testing your Markdown code in online editors that support these libraries to see if it renders correctly.In addition, check the browser console (F12) for any error messages, as this usually points to the problem.Ensure the network connection is normal, CDN resources can be loaded.
Q3: Can I customize the display style of Markdown content instead of using GitHub-Markdown-CSS?
A3:Of course you can. GitHub-Markdown-CSS is just a convenient choice that provides basic stylish aesthetics.If you have specific requirements for the visual style of the website, you can completely write your own CSS styles to override or replace it.You can create a custom onecustom.cssFile and link it to yourbase.htmlIn which you define<h1>to<h6>/<p>/<ul>/<ol>/<table>The HTML tag style corresponding to the Markdown element.To ensure that your custom styles take effect, you can place the link after GitHub-Markdown-CSS or use more specific CSS selectors to increase the priority.