In AnQi CMS, the Markdown editor brings us great convenience, especially when we need to insert mathematical formulas or draw flowcharts.By using concise syntax, we can easily express complex concepts.However, sometimes after using these advanced features, they may not display as expected, but instead display exceptions, such as only displaying the original Markdown text, or some content cannot be parsed.

Do not be nervous when encountering such problems. This is usually not a problem with the security CMS itself, but rather a problem with some link in the configuration, content writing, or front-end loading process.We can start from several key points and conduct a systematic investigation.

First step: Check basic settings and template introduction

Firstly, it is important to confirm whether our website is already prepared for the correct display of Markdown, mathematical formulas, and flowcharts.

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

  2. Confirm that the template file has been correctly introduced with the relevant scripts:The AnQi 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.Generally, these introduction codes are placed in your theme'sbase.htmlof the file (or a similar main template file)<head>at the bottom of the<body>at the beginning of the

    • MathJax is used 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 as 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 to parse and render Markdown syntax for flowcharts.
    • Markdown style (optional but recommended):To make the Markdown content look more beautiful, you can additionally 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 enter the template editing interface by going to the "Template Design" menu in the background to verify.

Second step: Check the content itself and its rendering method

Even if the front-end script is correctly introduced, the way the content is written and rendered may cause display errors.

  1. Is the Markdown syntax correct:Even experienced users may fail to parse due to a tiny syntax error.

    • Math formula (MathJax):
      • Inline formula: use a single dollar sign.$Enclosed, for example$E=mc^2$.
      • Block-level formula (on a separate line and centered): Use double dollar signs$$Enclosed, for example$$E=mc^2$$.
      • Make sure that the LaTeX syntax of the formula itself is correct.
    • Flowchart (Mermaid):
      • Mermaid diagrams are usually wrapped inmermaid `和`code blocks. For example:
        graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
      • Check if the Mermaid diagram syntax is correct, for examplegraph TD(Top to bottom) correct, arrow connector-->Are you using it correctly? A small mistake can cause the entire chart to fail to render. Suggest you test your formula and flowchart syntax in a reliable Markdown previewer to ensure its correctness.

  2. Is the content correctly rendered as HTML and marked as safe:In the Anqi CMS template system, you usually usearchiveDetailTags are used to retrieve document content. Markdown content needs to be processed by the backend and converted to HTML before it can be recognized by the MathJax and Mermaid libraries on the frontend.

    • Backend Markdown to HTML:In the document content:ContentWhen calling the field, you may need to ensure that the content has been converted to HTML by the Markdown processor. For example, when usingarchiveDetailtag to obtainContentyou can try addingrender=trueParameter, explicitly tell the system to convert it from Markdown to HTML:
      
{% 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<Convert&lt;If this happens, MathJax and Mermaid will not be able to recognize these escaped HTML and will not be able to render correctly.In order to avoid this unnecessary escaping, you need to add in the output Markdown conversion content.|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 combinerenderparameters:
      
{% archiveDetail articleContent with name="Content" render=true %}
<div>{{ articleContent|safe }}</div>
      Please note,|safeThe filter should be used cautiously, only when you completely 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 troubleshooting front-end issues.
    • Console (Console):Open the browser developer tools (usually press F12), switch to the "Console" panel.Check for JavaScript error messages.Failed to load MathJax or Mermaid, initialization error, or issues encountered during rendering may leave clues here.
    • Network:Switch to the "Network" panel, refresh the page. Check the CDN script files for MathJax and Mermaid (for exampletex-mml-chtml.jsandmermaid.esm.min.mjsDid it load successfully, is the status code 200? If a 404 (file not found), 500 (server error) or other abnormal status occurs, it means that the CDN resource failed to be obtained.
    • **Element (Elements