Navigate Markdown in Anqi CMS: Ensure content is elegantly rendered as HTML on the front end

Markdown as a lightweight markup language is increasingly favored by content creators for its simplicity, efficiency, and ease of use.It allows us to focus on the content itself without being distracted by complex formatting tools.When using Markdown to write articles, pages, or category descriptions in AnQi CMS, what we care most about is how to see it displayed in perfect HTML on the front end of the website.The AnQi CMS provides a very smooth and flexible solution, making everything simple.

Enable Markdown Editor: Step 1

To make AnQi CMS recognize and handle Markdown formatted content, we first need to enable the corresponding editor in the background. This process is very intuitive:

Log in to your AnQi CMS backend and findGlobal Settingsand then clickContent settings. On this page, you will see an option named "Enable Markdown Editor". Just check it and save the changes.

After completing this step, when you publish documents, edit categories, or pages, the content input box will support Markdown syntax.The system will default to treating these Markdown contents as marked text that needs to be converted.

Core rendering mechanism: automatic conversion and manual control

Once the Markdown editor is enabled in the background, the content rendering mechanism of Anqi CMS will automatically intervene to ensure that the Markdown text you enter in standard content fields such as article content, category description, single-page content, and Tag description can be correctly parsed as HTML on the front-end page.This means, you just need to focus on Markdown writing without any extra operations.

For example, in the article detail page usagearchiveDetailTag callContentWhen a field is, if the Markdown editor is enabled, the content will be automatically converted to HTML.

{# 假设archiveContent变量包含Markdown文本 #}
{%- archiveDetail archiveContent with name="Content" %}
{{articleContent|safe}}

Here we see{{articleContent|safe}}usage,|safeThe filter is crucial.The AnQi CMS defaults to escaping output content to prevent potential XSS attacks.After we convert Markdown content to HTML, the HTML tags should be parsed by the browser instead of being displayed as plain text.|safeThe filter tells the system that this HTML is safe, no need to escape it again, and can be output directly to the page.

However, if you have special requirements, such as wanting some Markdown content not to be converted to HTML, or in the case that the Markdown editor is not enabled, to manually specify a field for Markdown to HTML conversion, AnQi CMS also provides a flexible control method. You canarchiveDetail/categoryDetail/pageDetailortagDetailTag call contentnameIncrease one when the parameterrenderControl manually with the parameter:

  • render=true：Force the conversion of content from Markdown to HTML, regardless of whether the backend editor is enabled.
  • render=false：Force no Markdown to HTML conversion even if the backend editor is enabled.

This allows you to have finer control over the rendering of content.

Advanced Application: Presentation of Mathematical Formulas and Flowcharts

The Anqi CMS not only supports basic Markdown syntax, but also allows us to insert more complex elements into articles, such as mathematical formulas and flowcharts, greatly enriching the expressiveness of the content.To implement these advanced features, we need to rely on some mature third-party libraries to assist in rendering and integrate them into your website template.

Firstly, in order to make the HTML content converted from Markdown more unified and beautiful, we can introduce a set of universal Markdown styles. This is usually done by adding a template's<head>Add an external CSS file to the area to achieve this. For example, using GitHub-styled Markdown styles: 

<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 line of code is usually placed in your website template file (such asbase.html）的<head>Tag inside.

If it isa mathematical formulaWe need MathJax support.MathJax is a powerful JavaScript rendering engine that can render mathematical expressions in LaTeX, MathML, or AsciiMath formats into high-quality typeset formulas.base.htmlthe file<head>part, add the following code:

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

And forFlowchartOr sequence diagrams, Mermaid is a very good choice, it allows you to describe diagrams using a concise text syntax. To enable Mermaid's rendering feature, you need tobase.htmlthe file<head>Partially add a script like this:

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

Please note that this has been usedtype="module"and throughmermaid.initialize({ startOnLoad: true });to ensure that Mermaid automatically searches and renders charts when the page loads.

Through these simple integrations, your AnQiCMS website can perfectly display mathematical formulas and flowcharts written in Markdown on the front end.

Content of custom field in Markdown

In AnQi CMS, in addition to the standard article content, category descriptions, and other fields, we can also add various custom fields to the content model.If you choose to store Markdown formatted text in these custom fields and also want it to be rendered as HTML on the front end, simply enabling the Markdown editor may not be enough.

At this time, you need to use the Anqie CMS providedrenderFilter.This filter is specifically designed to manually convert any variable content that contains Markdown syntax to HTML.This provides strong support for the flexibility of the custom content model.

For example, you may have added a namedintroductionThe custom field is used to store the Markdown summary of the article. When calling and rendering it in the template, it can be used like this:

{# 假设introduction变量包含了Markdown文本，并且是自定义字段 #}
{% archiveDetail introduction with name="introduction" %}
{{introduction|render|safe}}

Similarly,|safeThe filter is still essential here, it ensures that the converted HTML can be correctly parsed by the browser without being escaped again. By|render|safeThe combination, you can ensure that all the carefully written Markdown content in the custom fields can be displayed in the expected HTML format in front of the user.

Some practical tips

  • Maintain consistency:It is recommended that you enter content through the background editor in all scenarios where you need to use Markdown.This ensures that the system consistently processes and renders Markdown, reducing display issues caused by different sources.
  • Template adaptation and style:Even if the Markdown content is correctly converted to HTML, the final visual effect still highly depends on the CSS style applied by your website template. If you find that the rendered Markdown elements (such as headings, lists, code blocks, etc.) do not look ideal, you may need to check or adjust the CSS file of the frontend template, especially if you have usedgithub-markdown-cssEnsure that its style can integrate well.
  • Consideration of security: |safeThe filter is powerful but needs to be used with caution.It tells the system that the output content is safe HTML and does not need to be escaped.When processing Markdown content from user input or untrusted sources, although the AnQiCMS Markdown converter will try to filter out malicious code, we should still remain vigilant to ensure the safety of the content and avoid potential XSS risks.

Through these functions and flexible configurations provided by Anqi CMS, we can easily master Markdown, presenting the content in an unprecedentedly clear and beautiful manner to the readers.

Frequently Asked Questions (FAQ)

1.I have enabled the Markdown editor and used Markdown syntax in the content, but the front-end page did not render it as HTML, but instead displayed the original Markdown text. What's the matter?

This usually has several reasons:

  • missing|safeFilter:This is the most common reason. Even if Markdown content is converted to HTML, if the template does not use|safefor example, a filter (such as{{archiveContent|safe}}), the browser will also display HTML tags as text. Make sure you use your template correctly|safe.
  • render=falseThe parameter was set unexpectedly:Check the content tags you are calling (such asarchiveDetailDid you incorrectly translaterenderThe parameter is set tofalse