As an experienced CMS website operation personnel for Anqi, I fully understand that providing rich and professional display forms is crucial for attracting and retaining users in an increasingly complex network content environment.For websites that contain technical content, scientific formulas, or flowcharts, the MathJax and Mermaid plugins can greatly enhance the readability and professionalism of the content.AnQi CMS is committed to providing efficient and customizable content solutions, therefore, introducing these features in the template is relatively direct.
The specific steps and considerations for introducing MathJax and Mermaid plugins in the Anqi CMS template:
Preparation: Enable Markdown editor:
Firstly, ensure that your safe CMS system has enabled the Markdown editor.The Markdown editor is a new feature added to Anqi CMS, which allows you to use Markdown syntax when creating content, including the original text of mathematical formulas and flowcharts.To enable this feature, please log in to the AnQi CMS backend management interface and navigate to the 'Content Settings' option under 'Global Settings'.In there, you will find an option to enable Markdown editor.This is to ensure that the formulas and charts you enter in the content can be correctly identified and processed.
Locate the template file:base.htmlOr public header file
In AnQi CMS, the introduction of the overall layout and functional scripts of the website is usually in the basic template file, such asbase.htmlor throughincludePublic header file introduced by tag (such aspartial/header.htmlThe operation is carried out in the template directory. These files are the skeleton shared by all pages.We need to add the MathJax and Mermaid reference code to these files<head>Within tags to ensure they are loaded and executed correctly when the page loads.
Introduce the default Markdown style
Although MathJax and Mermaid focus on rendering formulas and charts, if you want Markdown content (such as titles, lists, code blocks, etc.) to have a beautiful and unified default style on the front-end page, you can consider introducing a Markdown stylesheet.This is not usually mandatory, but it can significantly improve the user experience.The AnqiCMS recommends using CDN services to include, such as from cdnjs'sgithub-markdown-cssIn yourbase.htmlor in the public header files.<head>tag, add the following.<link>Tags:
<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" />
This code will apply a classic GitHub Markdown style to your Markdown content, making it more professional and readable.
Enable mathematical formulas: Integrated MathJax
To display mathematical formulas using LaTeX syntax correctly on the front-end page, we need to introduce the MathJax library.MathJax can parse LaTeX or MathML tags in web pages and render them as high-quality mathematical symbols.This website is indispensable for publishing scientific papers, technical reports, or any content that includes complex mathematical expressions.
Through the jsDelivr CDN service, in yourbase.htmlor in the public header files.<head>Tag, after the Markdown style, add the following<script>Tags:
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
asyncThe attribute ensures that the script is loaded asynchronously, without blocking the rendering of other content on the page, thus optimizing the user experience.id="MathJax-script"is the recommended identifier by MathJax, andsrcThe URL contains MathJax's TeX, MathML, and CHTML output support, which is the most commonly used configuration.
Render flowcharts and diagrams: Integrated with Mermaid
Mermaid is a JavaScript-based tool that allows you to create various charts such as flowcharts, sequence diagrams, Gantt charts, and more using a simple Markdown-like syntax.This is a powerful feature for websites that need to explain complex concepts or business processes in a graphical way.
Similarly, through the jsDelivr CDN service, in yourbase.htmlor in the public header files.<head>Add the following after the MathJax script inside the tag<script>code block:
<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 first imports the Mermaid library in the form of an ES module and then callsmermaid.initialize({ startOnLoad: true })Method.startOnLoad: trueThe parameter indicates that Mermaid automatically scans the document after the page is loaded, finds, and renders all charts defined by Mermaid syntax.This method ensures that even if the page content is dynamically loaded, Mermaid will try to render.
Completion and testing done
After completing the above steps, please make sure to save the modified template file.Next, create a new document in the Anqi CMS backend and test the syntax of MathJax and Mermaid in the document content.
For example, a simple MathJax formula might be:$$E=mc^2$$.
A simple Mermaid flowchart might be:
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
After publishing the document, visit the front-end page, check if the mathematical formula is rendered correctly as clear images or layout, and if the flowchart is displayed as an interactive graphic.If everything is normal, your Anqi CMS website now has powerful mathematical formula and chart display capabilities.
Through these integrations, your website content will no longer be limited to plain text, but can be presented in a more attractive and professional way to convey complex information, thus better serving your audience and enhancing the overall value of your website.
Frequently Asked Questions (FAQ)
1. Why is my math formula or Mermaid diagram not displayed correctly, but instead shows the original code?
First, please confirm that you have enabled the Markdown editor in the "Global Settings" -> "Content Settings" of the Anqi CMS backend.This is the key to ensure that the system recognizes formulas and charts as special content rather than ordinary text.Secondly, check if you have correctly added the MathJax and Mermaid script code to the template file (such asbase.html）的<head>Tags within, and no syntax errors. Ensure that the CDN link is accessible, the network connection is normal.Finally, please check if the syntax of the formulas or charts in your Markdown content is correct, for example, whether the MathJax formulas use the correct delimiters (such as$$...$$or$....$)，Is the Mermaid diagram displayed withmermaid...Block quote wrapping.
2. Can I include MathJax and Mermaid without using a CDN?
Of course you can. The document recommends using CDN for quick deployment and to take advantage of the global acceleration benefits that CDN brings.If you consider security, offline environment, or complete control of resource versions, you can choose to download the MathJax and Mermaid library files to your server and modify the templates in the following way,srcorhrefThe path, pointing to where you store these files locally. For example, you can place the downloaded MathJax files in/public/static/js/mathjax/the directory, and then place the MathJax script insrcto/static/js/mathjax/es5/tex-mml-chtml.jsMake sure the local file path is consistent with the template reference path.
3. Can Mermaid charts be automatically rendered if my page content is dynamically loaded?
Mermaid'smermaid.initialize({ startOnLoad: true })The configuration will indeed automatically scan and render the chart when the page is first loaded.However, if the content of your page is loaded dynamically through AJAX and other methods, these newly loaded charts may not render automatically.In this case, you need to manually call Mermaid's rendering method after the dynamic content is loaded.For example, in your JavaScript code, when new Mermaid chart content is added to the DOM, you can callmermaid.contentLoaded()ormermaid.run()Rescan and render. For specific methods, please refer to the official Mermaid documentation.