Today, with the increasing efficiency of content creation, Markdown has gained favor among content creators due to its concise and clear syntax and its focus on the content itself.A-Ke CMS fully understands this trend and provides powerful features, allowing you to easily convert Markdown-formatted article content into exquisite HTML pages and supports more rich display effects, such as mathematical formulas and flowcharts.

Enable Markdown Editor: The First Step in Content Creation

Firstly, to make the Anqi CMS recognize and process Markdown content, you need to make simple configurations in the background.This is like telling the system that you want to write articles in Markdown format.

  1. Log in to the Anqi CMS backend.
  2. Navigate toGlobal Settingsthen selectContent Settings.
  3. Here, you will find an option toEnable Markdown Editor. Check this option and save the settings.

Once enabled, when you create or edit an article, the article content input box will become a Markdown editor, making it convenient for you to create content using Markdown syntax.

The Magic of Markdown to HTML: Automatic and Manual Rendering

When the Markdown editor is enabled, AnQi CMS will default to processing the content you write in Markdown syntax, converting it into an HTML structure that browsers can understand.However, in certain specific template call scenarios, you may need to control this rendering process more explicitly.

In template files, we usually usearchiveDetailTags can be used to obtain the detailed content of articles. For example, to obtain the Markdown original of the article content:

{# 默认用法，自动获取当前页面文档 #}
<div>文档内容：{% archiveDetail with name="Content" %}</div>

Here are theContentField is the content you input in the Markdown editor on the backend.

To ensure that Markdown content is rendered correctly as HTML and displayed safely, it is usually usedrenderparameters withsafeFilter:

  • render=trueThis parameter explicitly indicates that the system should render the Markdown content obtained, converting it to HTML.
  • |safeThis is a filter of Django template engine. Because the system considers security, it will automatically escape HTML tags by default (for example<Will become&lt;To prevent XSS attacks. When you are sure the content is safe and needs to be displayed as HTML, use|safeThe filter can cancel this automatic escaping, allowing the browser to correctly parse and display HTML.

Therefore, in your template file, to retrieve and display the rendered Markdown content is usually written like this:

{# 假设archiveContent变量存储了Content字段的内容 #}
<div>
    {%- archiveDetail articleContent with name="Content" %}
    {{articleContent|render|safe}}
</div>

Or you can specify the rendering directly in the tag:

<div>
    {%- archiveDetail with name="Content" render=true %}{{archiveContent|safe}}
</div>

In this way, the Markdown content you write can be perfectly displayed on the front-end page in HTML form.

Enhance display effects: Introduce external styles and features

Markdown not only provides basic text formatting, but also, with the help of third-party libraries, can achieve more advanced display effects, such as mathematical formulas and flowcharts.The AnQi CMS also supports enhancing these features by introducing the corresponding CDN resources in the template.

These enhanced features usually need to be added in yourbase.html(or any template file referenced as a public header, such as)bash.htmlorpartial/header.html) of<head>add the corresponding script and style link in the tag.

  1. Markdown default style:To make the rendered Markdown content more aesthetically pleasing and readable, you can introduce a universal GitHub style Markdown stylesheet in yourbase.htmlof<head>Partially added:

    <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" />

    Then, you may need to wrap the rendered content in a div withmarkdown-bodyclass:divso that the styles take effect:<div class="markdown-body">{{ articleContent|render|safe }}</div>.

  2. Correct display of mathematical formulas on the web (MathJax):If you need to embed LaTeX formatted mathematical formulas in an article, MathJax is a very powerful solution.base.htmlof<head>Partially added:

    <script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>

    This script will automatically detect mathematical formulas in the page and render them.

  3. Correct display of flow charts on the web (Mermaid):Mermaid allows you to create diagrams, sequence diagrams, etc. using simple text syntax. Inbase.htmlof<head>Partially added:

    <script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
    mermaid.initialize({ startOnLoad: true });
</script>

    Mermaid scans specific code blocks on the page (usuallygraph TD/sequenceDiagramConvert the Mermaid syntax block into an interactive graphic.

By following these steps, your Markdown article will not only be correctly rendered as HTML but also feature professional styles, dynamic mathematical formulas, and clear flowcharts, greatly enhancing the expressiveness of the content and the user experience.The Anqi CMS encapsulates technical details in the backend, allowing content creators to focus on the content itself without worrying about complex rendering logic.

Common Questions (FAQ)

  1. Q: The Markdown editor is enabled, but the article content is still displayed as plain text without being converted to HTML. Why is that?A: This is usually due to not using the parameters correctly in the template filerender=trueor not using them to indicate that the system should render Markdown|safeFilter to remove automatic escaping of HTML. Check your archiveDetailtag to include render=trueand|safe, for example:{{articleContent|render|safe}}.

  2. Q: I inserted mathematical formulas and flowcharts into the article, but they do not display normally on the frontend page. What could be the reason?A: Even if Markdown content is rendered as HTML, advanced features like MathJax and Mermaid require additional JavaScript libraries to parse and display. Make sure you have followed the instructions in the documentation for your website.base.html[or other public header templates]<head>[part, correctly introducing CDN scripts for MathJax and Mermaid]

  3. Q: Can I use Markdown and render it as HTML in category descriptions or single-page content, in addition to the article detail page?A: Yes, the Markdown rendering capability of AnQi CMS is not limited to article details. It includes getting category descriptions (categoryDetail) or single-page content (pageDetailWhen, if these fields support Markdown, you can also userender=trueparameters with|safea filter to render its content as HTML. For example:{{categoryContent|render|safe}}.