How does AnQiCMS support Markdown content editing and correctly render mathematical formulas and flowcharts on the front end?
AnQiCMS deeply understands the desire of content creators for efficient and flexible editing tools.The new version introduces the Markdown editor, greatly enhancing the convenience of content publishing.What is even more surprising is that AnQiCMS not only supports basic Markdown syntax, but also allows complex mathematical formulas and flowcharts to be elegantly presented on the front end of your website through simple configuration.This is undoubtedly a powerful boost for websites that need to display professional knowledge, technical documentation, or educational content.
Enable Markdown editing feature
Firstly, you need to make sure that the Markdown editor is enabled in the AnQiCMS backend.Log in to the admin management interface, navigate to the "Content Settings" option under "Global Settings".Here, you will find an option to enable the Markdown editor, check it and save the settings.After completing this step, when you create or edit a document, the content editor will automatically switch to Markdown mode, allowing you to create content using concise and efficient Markdown syntax.
Write Markdown content
In the Markdown editor, you can use it as usual#Indicates the title,*or-Represent a list, enclosed in backticks`Represent inline code, enclosed in triple backticks"`Represent code blocks, etc.
For mathematical formulas, you can use LaTeX syntax, which is a widely adopted formula typesetting language in academic and scientific fields. For example, inline formulas can be written using a single$Enclosed, such as$E=mc^2$;Block formulas are enclosed with double$$symbols to display them independently and centered, such as$$ \int_a^b f(x)dx $$.
For flowcharts, Mermaid syntax is a commonly used choice, which allows you to generate charts using text descriptions. For example, a simple flowchart can be created using the following syntax:
```mermaid
graph TD;
A[开始] --> B(处理);
B --> C{判断?};
C -- 是 --> D[结果1];
C -- 否 --> E[结果2];
D --> F(结束);
E --> F;
```
After entering this content in the editor and saving the document, you need to configure the front-end to correctly render these special contents.
The key to front-end rendering: introduce external support libraries
Although AnQiCMS's Markdown editor accepts and saves these special syntaxes, the browser itself does not directly support their rendering.Therefore, we need to introduce some front-end JavaScript libraries and CSS style sheets to 'translate' these syntaxes and convert them into user-friendly visual content.These operations are usually introduced in your website template'sbase.htmlthe file<head>Completed within the tag.
Optimize Markdown style：In order to make the rendered Markdown content more beautiful and professionally formatted on the front end, you can introduce
github-markdown-css。Just addbase.htmlof<head>in<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 will provide a concise reading experience for your Markdown content, similar to GitHub, and enhance the overall visual effect of the content.
Elegant display of mathematical formulasIn order to display LaTeX-written mathematical formulas correctly and have a professional typesetting effect, we need the MathJax library. In
base.htmlof<head>add the following<script>Tags:<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>MathJax will asynchronously identify and render LaTeX formulas on the page during loading, converting them into a readable layout style. Whether it is complex calculus or simple algebraic expressions, they can be clearly displayed.
Dynamic presentation of flowcharts: The Mermaid library is responsible for parsing Mermaid syntax into interactive flowcharts or various charts. In
base.htmlof<head>add the following<script>code:<script type="module"> import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs'; mermaid.initialize({ startOnLoad: true }); </script>Please note that this code uses ES module imports. After Mermaid is initialized, it will intelligently search for Mermaid syntax blocks on the page and convert them into SVG graphics, making your flowcharts dynamic and easy to understand.
Actual effect and content value
With these configurations, when your users visit pages containing Markdown text, mathematical formulas, or flowcharts, they will see professionally formatted content with clear formulas and dynamically displayed flowcharts.This not only greatly enhances the professionalism and readability of the content, but also liberates content creators, allowing them to focus on content creation and the transmission of knowledge, without worrying about complex layout work.This is a leap forward in content presentation for technical blogs, educational websites, product documentation, or any website that needs to convey complex information, and it can attract and retain readers more effectively.
Cautionary notes and **practice
- These external CDN resources require the user's browser to be able to access them normally.If your target user group has a special network environment or security requirements, you may need to consider downloading these JavaScript libraries and CSS files to your server locally for deployment to achieve more fine-grained control and optimization.
- After enabling the Markdown editor, the functionality and display method of the original rich text editor will change.Make sure your content team is familiar with Markdown syntax.
- If you have inserted custom content that needs to be rendered as HTML in Markdown (for example, certain special HTML fragments), and you want AnQiCMS to automatically convert it to HTML instead of displaying it as raw Markdown, you can pay attention to the AnQiCMS template tags in
Contentfield'srenderParameter, use appropriately|safefilter. - The versions of the Mermaid and MathJax libraries will continue to be updated. It is recommended to consult their official documentation when introducing them to understand the latest versions and potential compatibility issues.
Frequently Asked Questions (FAQ)
Q: Why did I enable the Markdown editor and add a formula, but the front end still displays the original LaTeX code?A: This is usually because the MathJax library has not been loaded or initialized correctly on the front-end page. Please check if you have correctly included the MathJax library in
base.htmlthe file.<script>tags and make sureMathJax-scriptofasyncattributes andsrcThe path is not incorrect. Additionally, confirm that the syntax of the LaTeX formula you have written in Markdown is correct, for example, whether the inline formula uses single$Wrap, whether the block-level formula uses double$$.Q: The flow chart does not display or displays the original Mermaid code instead of the graphic?A: In this case, you need to check
base.htmlwhether the Mermaid inclusion code is complete and error-free, especiallytype="module"andmermaid.initialize({ startOnLoad: true });These are the key parts. Ensure that your template environment supports ES module imports.Next, please carefully check whether the Mermaid syntax you have written in Markdown is in accordance with the specifications, any minor syntax error can lead to rendering failure.It is a good practice to consult the official Mermaid documentation to ensure syntax compatibility.**Q: CDN resources introduced will affect the website loading speed