AnQi CMS as an efficient content management system, deeply understands the pursuit of convenience by content creators.Markdown is a lightweight markup language that is favored by content editors for its simplicity, ease of learning, and clear formatting.How can we ensure that the excellent content you write in Markdown is perfectly converted into browser-readable HTML and displayed beautifully on the front-end page in AnQi CMS?

This is not a complex technical problem, Anqi CMS has fully considered this from the beginning of its design, through a series of intelligent processing and flexible configuration, enabling Markdown content to have a 'native' performance on your website.

I. Basic Markdown content auto-rendering: Enable the editor's magic

The AnQi CMS is built-in with a powerful Markdown editor support, its core idea is to make the input and output of content as automated and seamless as possible.After you enable the Markdown editor in the background "Global Settings" -> "Content Settings", the system will intelligently recognize and process your Markdown content.

For the article (archive）、Category（category) and single page (page)'s default 'content' (ContentThe field, when you enter or import content using the Markdown editor in the background, Anqi CMS will parse its syntax and convert it to standard HTML structure. This means that you do not need any additional configuration, just call the corresponding in the template.Contentfield, for example:

{# 在文章详情页中调用文章内容 #}
<div>
  {%- archiveDetail articleContent with name="Content" %}
  {{articleContent|safe}}
</div>

or category details, single page details ofContentField:

{# 在分类详情页中调用分类内容 #}
<div>
  {%- categoryDetail categoryContent with name="Content" %}
  {{categoryContent|safe}}
</div>

{# 在单页面详情页中调用单页面内容 #}
<div>
  {%- pageDetail pageContent with name="Content" %}
  {{pageContent|safe}}
</div>

Here|safeThe filter is crucial, it tells the template engine that this content is safe HTML and does not need to be escaped again.Otherwise, you might see the original HTML tags instead of the rendered effect.

It is worth mentioning thatIf some Markdown content does not want to be automatically rendered, or you want to manually control the rendering process,archiveDetail/categoryDetail/pageDetailsuch as tags,Contentthe field also supportsrender=falsethe parameters. For example,{% archiveDetail archiveContent with name="Content" render=false %}This content will be output as raw Markdown text. Otherwise,render=trueit explicitly indicates rendering, which can provide finer control in some special cases.

Second, flexible rendering of custom field Markdown content:renderThe wonder of filters

Not all Markdown content is displayed through these predefined "Content" fields.Sometimes, you may create custom fields in the content model and want these fields to also support Markdown syntax.产品特点Custom field, and describe it with Markdown.

In this case, Anqi CMS provides powerfulrenderFilter.This filter is specifically used to explicitly convert Markdown text in variables to HTML.|renderand it is done:

{# 假设有一个自定义字段名为 'product_features' #}
{% archiveDetail productFeatures with name="product_features" %}
  <div class="product-features-section">
    {{ productFeatures|render|safe }}
  </div>

By|renderEven custom fields containing Markdown content can be correctly parsed and presented as beautiful HTML on the front end. Similarly,|safeIt is also indispensable to avoid HTML tags from being treated as plain text when escaping output.

3. Advanced Markdown Elements: Displaying Mathematical Formulas and Flowcharts

For content in Markdown that includes mathematical formulas (such as LaTeX syntax) or flowcharts (such as Mermaid syntax), AnQi CMS also provides support, but these usually require the use of some front-end JavaScript libraries to complete client-side dynamic rendering.The Anqi CMS itself is only responsible for passing these special syntaxes as text to the front-end, while the actual rendering work is performed by the third-party libraries loaded by the browser.

Make sure these advanced elements are displayed correctly, you need tothe skeleton template (usuallybase.htmlor the main layout file of your website)of<head>Inside the tag, include the corresponding CSS styles and JavaScript libraries:

  1. Provide default styles for Markdown content (optional but recommended):Although Markdown content is converted to HTML, the default browser styles may be too plain. Introducedgithub-markdown-cssThis CSS library can make your Markdown content have a more professional GitHub style appearance.

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

  2. Render mathematical formulas (MathJax supported):If you use LaTeX-style mathematical formulas in Markdown, the MathJax library is indispensable.It will parse and beautifully present these formulas in the browser.

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

  3. Render flowchart (Mermaid supported):For Mermaid flowcharts, you need to include the Mermaid 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>

Add these code snippets tobase.htmlof<head>After the area, when the page loads Markdown content containing mathematical formulas or Mermaid flowcharts, these JavaScript libraries will automatically intervene to render them into readable graphics or formulas.

Four, Summary and **Practice

Secure CMS through its intelligent Markdown editor, flexible,renderFilter and compatibility with third-party rendering libraries, providing comprehensive Markdown support for content creators.Whether it is the layout of daily articles or the display of complex mathematical formulas and flow charts, they can be presented accurately and beautifully on the front page.

In actual operation, remember the following points:

  • Enable editor:Make sure the Markdown editor is enabled in the background "Global Settings" -> "Content Settings."
  • |safeEssential:Any Markdown rendered to HTML content should be added in the template output|safefilter.
  • Advanced features need to be introduced:Advanced Markdown elements such as mathematical formulas and flow charts, additional CSS and JS libraries need to be introduced to your template.
  • Testing is crucial:After each adjustment, be sure to test on the front-end page to ensure that the content is rendered as expected.

With these features, you can focus on content creation, allowing Anqi CMS to take care of the presentation details for you, thereby providing your website visitors with a better reading experience.

Frequently Asked Questions (FAQ)

Q1: Why does the front-end page display the original Markdown text I wrote in the background instead of the rendered HTML?

A1: |render|safeFilter, for example{{ custom_field_value|render|safe }}Finally, confirm that your template file does not accidentally remove|safeFilter removal, which will cause HTML tags to be escaped instead of rendered.

Q2: My article contains mathematical formulas and Mermaid flowcharts, why are they not rendered?

A2: Math formulas and Mermaid flowcharts require a client-side JavaScript library to be dynamically rendered.The default configuration of AnQi CMS does not include these libraries because not all websites need them.base.html）的<head>Manually add MathJax and Mermaid JavaScript references, as well as optional Markdown style CSS in the tag.Please refer to the description of the "Advanced Markdown Elements" section in this article.

Q3: Using in the template|safeDoes the filter pose a security risk?

A3: |safeThe filter tells the template engine that the content you are outputting is trusted HTML and does not need to be escaped.If your Markdown content source is uncontrolled (for example, allowing users to input directly) and not properly filtered for security, malicious users may harm your website by injecting JavaScript code (XSS attack).