How to insert Markdown formatted text in website content and render it correctly as HTML?

In AnQiCMS, inserting Markdown-formatted text and rendering it correctly into HTML is an important way for content operators to improve efficiency and produce high-quality pages.AnQiCMS has built-in support for Markdown editing and rendering, allowing you to enjoy the simplicity and efficiency of Markdown while ensuring that the final page output is beautiful and well-structured HTML.

Enable Markdown editor

To start using Markdown in AnQiCMS, first make sure that its editor feature is enabled. This setting is usually located in the core configuration of the system:

You can visitAnQiCMS backendEnterGlobal Settingsand then findContent settingsOption. Here, you will see an option to enable or disable Markdown editor.After checking the option, when you publish or edit articles, single pages, and other content, the content editor will switch to Markdown mode, making it convenient for you to create content using Markdown syntax.

Enable Markdown editor after, you can directly use Markdown syntax for formatting when editing content in the background. For example, using**粗体**to indicate bold,# 标题Indicates a first-level heading,- 列表项Indicates an unordered list, as well as Markdown common elements such as code blocks, links, and images.

Insert Markdown text in the content

AnQiCMS supports inserting Markdown text in various content types, including:

• Article content:When publishing a new article or editing an existing one, you can directly input Markdown text in the 'Document Content' area.
• Single page content:For pages such as “About Us” and “Contact Us”, the content can also be written using the Markdown editor.
• Category description/content:When managing articles or product categories, the "category introduction" or "category content" fields also support Markdown format.
• Tag description/content:If you want to add a more detailed description to a label, you can also use Markdown in the "Label Description" or "Label Content" field.

By writing content in Markdown, you can not only focus on the text itself, but also avoid cumbersome mouse operations, and ensure that the content structure is clear, laying a good foundation for subsequent style rendering.

Ensure Markdown is rendered correctly as HTML

When you enable the Markdown editor in the background and write content using Markdown syntax, AnQiCMS will usually automatically render it into HTML to display correctly on the front-end page.

For article, category and single page main content fields (such asarchiveDetail/categoryDetail/pageDetailin the tags ofContentfield), when the Markdown editor is enabled, the system will automatically convert the Markdown text to HTML.This means that when you call these fields directly in the template, you do not need any additional operations, and Markdown content can be displayed in HTML format.

For example, in the template of the article detail page, if your article content uses Markdown, the following call method is as follows:

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

Here{{articleContent|safe}}The HTML that has been safely converted by the AnQiCMS backend will be output to the page.|safeThe filter is crucial here, it indicates that the template engine should process the content as safe HTML, avoiding double escaping.

However, in certain specific scenarios, you may need to manually control the conversion process from Markdown to HTML. This includes:

1. Markdown editor is not enabled, but a field contains Markdown text:If you disable the Markdown editor in the background but a certain content field still contains Markdown text, the system will not automatically render.
2. Custom fields contain Markdown text:Fields added through the "Content Model Custom Fields" may not be rendered in Markdown by default.
3. Need to explicitly control the rendering time:You want to explicitly Markdown render the content of a certain field.

In this case, you can use the AnQiCMS providedrenderFilter配合safeFilter，to manually convert Markdown text to HTML and safely output. For example，if your custom fieldintroductionContains Markdown text:

{% archiveDetail introduction with name="introduction" %}
{{introduction|render|safe}}

Here|renderThe filter will perform Markdown to HTML conversion,|safeMake sure the converted HTML can be correctly parsed by the browser without being escaped.

Enhance rendering effects: Support mathematical formulas and flowcharts

The new version of AnQiCMS also supports inserting mathematical formulas and flowcharts in Markdown content.These advanced features require the use of third-party libraries on the front-end to render correctly.You need to fill in the website template'sbase.htmlthe file<head>In the tag, introduce the corresponding CDN resources:

1. Markdown default style:To make Markdown content on the page have better visual effects, you can introduce GitHub-style Markdown CSS.

   <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. Math formula rendering:If your content contains LaTeX and other mathematical formulas, you need to introduce the MathJax library for rendering.

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

3. Flowchart rendering:For flowcharts using Mermaid syntax, you need to include the Mermaid library.

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

Add this code to your website template (usuallybase.html）的<head>After the area, the mathematical formulas and flowcharts you write in Markdown can be displayed professionally and beautifully on the front-end page.

Summary

AnQiCMS offers an efficient, convenient, and powerful content creation experience through its built-in Markdown editor and flexible rendering mechanism.Whether it is simple text formatting or complex mathematical formulas and flowcharts, AnQiCMS can help you easily handle them and ensure that the content is presented in a **state to the visitors.Just as long as you enable the editor according to the above steps, write the content correctly, and use it reasonably when necessaryrender|safeThe filter and external resources can fully utilize the potential of Markdown in AnQiCMS.

Frequently Asked Questions (FAQ)

1. Ask: I have enabled the Markdown editor in the background and used Markdown syntax in the article, but why is the article still displayed as raw Markdown text on the front end and not converted to HTML?Answer: This is usually due to incorrect content output method in the template. Please check your template code to ensure that you have used|safeFilter. For example, it should be used{{articleContent|safe}}, rather than just{{articleContent}}. If the content is not passed throughContentThis field will be automatically rendered by default, or you need to add before if the Markdown editor is not enabled|safeadd before|rendera filter such as{{customField|render|safe}}.

2. Ask: I want to add a 'Product Feature' field to the custom content model and allow Markdown text to be entered in this field.How should I ensure it renders correctly on the front end?Answer: For custom fields, even if the Markdown editor is enabled, the system may not automatically convert Markdown to HTML. Therefore, when calling this custom field in your template, it is recommended to always use it explicitly|render|safeFilter. For example, if your custom field name isproduct_features, when calling it in the template, it should be written as{{item.product_features|render|safe}}.

3. Ask: I have added the CDN code for MathJax and Mermaid according to the document, but the mathematical formulas and flowcharts in the Markdown are still not displayed or displayed incorrectly. What is the matter?Answer: Please check if you have placed the CDN code correctly inbase.htmlthe file<head>Within the tags. Secondly, ensure that your Markdown syntax is correct, for example, a Mermaid flowchart needs to be in the format ofgraph TD...This structure begins. Sometimes, the browser's cache may also cause problems, try clearing the browser cache or accessing the page in incognito mode.If the problem still exists, it may be due to a CDN loading failure or a conflict with other JavaScript code on your website. You can check the console for error messages in the browser developer tools.