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

Enable Markdown Editor

To start using Markdown in AnQiCMS, you first need to ensure that the editor feature is enabled. This setting is usually located in the system's core configuration:

You can access by visitingAnQiCMS backend, and enterGlobal Settings, and then findContent SettingsOption.Here, you will see an option to enable or disable the Markdown editor.Selecting this option will enable the Markdown editor when you publish or edit articles, single pages, and other content, making it convenient for you to create content using Markdown syntax.

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

Insert Markdown text in the content.

AnQiCMS supports inserting Markdown text into 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 single-page pages such as 'About Us' and 'Contact Us', the content can also be written using the Markdown editor.
  • Category description/content:When managing article or product categories, the "category introduction" or "category content" fields also support Markdown format.
  • Tag description/content:If you wish to add a more detailed description to a tag, you can also use Markdown in the 'Tag Description' or 'Tag Content' field.

Writing content with Markdown allows you to focus on the text itself, avoid cumbersome mouse operations, and ensure that the content structure is clear, laying a good foundation for subsequent style rendering.

Ensure Markdown renders correctly to HTML

When you enable the Markdown editor in the background and write content using Markdown syntax, AnQiCMS usually automatically renders it into HTML for correct display on the front-end page.

For the main content fields such as articles, categories, and single pages (for examplearchiveDetail/categoryDetail/pageDetailin the tags of theContentField), when the Markdown editor is enabled, the system will automatically convert Markdown text to HTML during template rendering.This means that when you directly call these fields in the template, no additional operations are needed, 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 are the{{articleContent|safe}}The HTML converted by AnQiCMS backend will be safely output to the page.|safeThe filter here is crucial, indicating to the template engine that the content should be treated as safe HTML to avoid 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 content field still contains Markdown text, the system will not automatically render it.
  2. Custom field includes Markdown text:The system may not render Markdown by default for fields added through "Content Model Custom Fields".
  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 are the|renderThe filter will perform Markdown to HTML conversion,|safeEnsure that the converted HTML is correctly parsed by the browser and not 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 front-end libraries to render correctly.base.htmlthe file<head>In the tag, introduce the corresponding CDN resources:

  1. Markdown default style:In order to have better visual effects for Markdown content on the page, 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 includes mathematical formulas such as LaTeX, 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 Mermaid syntax flowcharts, 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 (usually thebase.html) of<head>After the region, the mathematical formulas and flowcharts you write in Markdown can be displayed professionally and beautifully on the front-end page.

Summary

AnQiCMS provides an efficient, convenient, and powerful content creation experience for users through its built-in Markdown editor and flexible rendering mechanism.Whether it's simple text formatting or complex mathematical formulas and flowcharts, AnQiCMS can help you easily handle them and ensure that the content is presented to visitors in a **state**.render|safeFilters and external resources can fully tap the potential of Markdown in AnQiCMS.

Common Questions (FAQ)

  1. Question: I have enabled the Markdown editor in the background and used Markdown syntax in the article, but why does the article still display as raw Markdown text on the frontend and not converted to HTML?Answer: This is usually caused by incorrect content output method in the template. Please check your template code to ensure that you have used|safefilter. For example, it should use{{articleContent|safe}}，instead of just{{articleContent}}. If the content is not throughContentsuch default fields that are automatically rendered, or if the Markdown editor is not enabled, you also need to add in front of|safebefore|renderFilter, such as{{customField|render|safe}}.

  2. Question: 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 frontend?Answer: Even if the Markdown editor is enabled, the system may not automatically convert Markdown to HTML for custom fields. 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. Question: I have added the CDN code for MathJax and Mermaid according to the document, but the mathematical formulas and flowcharts in Markdown still do not display or display incorrectly. What is the matter?Answer: Please carefully check whether you have placed the CDN code correctly inbase.htmlthe file<head>Tags inside. Next, make sure your Markdown syntax is correct, for example, Mermaid flowcharts should be in the format ofgraph TD...Such a structure begins.Sometimes, browser cache may also cause problems, try clearing the browser cache or accessing the page in incognito mode.If the issue still persists, it may be due to a CDN loading failure or a conflict with other JavaScript code on your website. You can check the console in the browser developer tools for any error messages.