In AnQi CMS, the Markdown editor brings us great convenience, especially when inserting mathematical formulas or drawing flowcharts.Through concise syntax, we can easily express complex concepts.However, after using these advanced features, they may not be displayed as expected, but instead show display anomalies, such as only displaying the original Markdown text, or some content cannot be parsed.

Do not worry when encountering such problems.This is usually not a problem with the CMS itself, but rather some issue occurred during the configuration, content writing, or frontend loading process.We can start from several key points and conduct a systematic investigation.

Step 1: Check basic settings and template import

The first thing to confirm is whether our website is ready for the correct display of Markdown, mathematical formulas, and flowcharts.

  1. Enable Markdown Editor:This is the most basic premise.Please log in to the Anqi CMS backend and go to the "Content Settings" page under "Global SettingsHere, make sure that the 'Enable Markdown Editor' option has been checked.If this option is not enabled, the system will not parse Markdown syntax no matter how you write it in the document.

  2. Confirm that the template file has been correctly introduced with related scripts:The CMS supports Markdown mathematical formulas and flowcharts, which are implemented by integrating third-party JavaScript libraries.This means that your website template needs to include the CDN resources of these libraries.base.htmlThe file (or similar main template file):<head>At the bottom of the<body>At the beginning of the

    • MathJax for mathematical formulas:Ensure that your template includes the following script (or a similar version of MathJax 3):
      
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
      This script is responsible for rendering LaTeX mathematical formulas in Markdown into readable mathematical expressions.
    • Mermaid is used for flowcharts:Ensure that your template includes the following script (or a similar version of Mermaid):
      
<script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
    mermaid.initialize({ startOnLoad: true });
</script>
      This code imports the Mermaid library and initializes it, so that it can parse and render the flowchart syntax in Markdown.
    • Markdown style (optional but recommended):To make Markdown content look more aesthetically pleasing, you can optionally introduce a Markdown stylesheet, for example:
      
<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" />
      Please check that the CDN link is spelled correctly and is placed in a reasonable position.You can access the template editing interface by going to the "Template Design" menu in the background.

Step 2: Troubleshoot the content itself and its rendering method

Even if the front-end script is correctly introduced, the content writing and rendering method may still cause display errors.

  1. Is the Markdown syntax correct:?Even experienced users may encounter parsing failure due to a tiny grammar error.

    • Math formula (MathJax):
      • Inline formula: use a single dollar sign$For example, encapsulate.$E=mc^2$.
      • Block formula (on a separate line and centered): use double dollar signs$$For example, encapsulate.$$E=mc^2$$.
      • Make sure the LaTeX syntax of the formula itself is correct.
    • Flowchart (Mermaid):
      • Mermaid charts are usually wrapped inmermaid `和`code blocks. For example:
        graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
      • Check if the Mermaid chart syntax is correct, for example,graph TD(from top to bottom) is correct, arrow connector-->Is it correct to use.A small error can cause the entire chart to fail to render. Recommend testing your formula and flowchart syntax in a reliable Markdown previewer to ensure its correctness.

  2. Content is rendered correctly as HTML and marked as safe:In the AnQi CMS template system, you will usually usearchiveDetailUsing tags to obtain document content.Markdown content needs to be processed by the backend, converted to HTML before it can be recognized by the frontend MathJax and Mermaid libraries.

    • Backend Markdown to HTML:in the document contentContentField calling, you may need to ensure that the content has been converted to HTML by the Markdown processor. For example, when usingarchiveDetailtags to getContentyou can try addingrender=trueParameters, explicitly tell the system to perform Markdown to HTML conversion: 
      
{% archiveDetail articleContent with name="Content" render=true %}
{{ articleContent|safe }}
    • |safeFilter:Even if the content has been correctly converted to HTML by the backend, the Django template engine of Anqi CMS may escape the output HTML tags for security reasons (for example, converting<Converted to&lt;）。If this happens, MathJax and Mermaid will not be able to recognize these escaped HTML and will not be able to render correctly.|safeFilter. This filter tells the template engine that this content is safe and does not need to be escaped.
      
{# 假设article.Content已经被后端转换为HTML，并且我们信任它的内容是安全的 #}
<div>{{ article.Content|safe }}</div>
      or combinedrenderParameters:
      
{% archiveDetail articleContent with name="Content" render=true %}
<div>{{ articleContent|safe }}</div>
      Please note,|safeThe filter should be used with caution, only when you fully trust the content source, to prevent potential XSS attacks.

Step 3: Check the browser and network environment

The display of front-end content is closely related to the browser environment and network status.

  1. Browser Developer Tools:This is a powerful tool for front-end troubleshooting.
    • Console (Console):Open the browser developer tools (usually press F12), switch to the “Console” panel.Check for any JavaScript error messages.MathJax or Mermaid loading failure, initialization error, or issues encountered during rendering may leave clues here.
    • 网络 (Network)：EnglishSwitch to the “Network” panel, refresh the page. Check the CDN script files for MathJax and Mermaid (for exampletex-mml-chtml.jsandmermaid.esm.min.mjs）Whether it was successfully loaded, was the status code 200.If a 404 (File Not Found), 500 (Server Error) or other exception status occurs, it indicates that the CDN resource could not be successfully retrieved.
    • **Element (Elements)