In the operation of the Anqi CMS website, for Markdown-related scripts, in addition to in the Englishbase.htmlIn addition to configuring in the file, it is usually not necessary to add these scripts repeatedly in other template files.This is a comprehensive consideration of the AnQiCMS template inheritance mechanism, content rendering process, and website performance optimization.
AnQiCMS design philosophy emphasizes efficiency and customization, its template system uses syntax similar to Django template engine, the core beingbase.htmlAs the basic framework of the website.This file carries the universal layout, common stylesheet, and global JavaScript script of the website.help-markdown.mdThe guidance, introducing GitHub Markdown CSS, MathJax, and Mermaid-related scriptsbase.htmlof<head>In the region, these features are already effective throughout the entire website.
To be specific,github-markdown-cssIt provides a default beautification style for Markdown content, making the parsed HTML content more readable.MathJaxis a JavaScript library used to display mathematical formulas on web pages, which can render formulas in LaTeX or MathML formats into high-quality mathematical expressions.MermaidIt is a JavaScript library that allows users to create diagrams such as flowcharts, sequence diagrams, etc. using Markdown-like text syntax.These are front-end display function enhancements, which require the browser to load the corresponding CSS and JavaScript libraries to parse and display correctly.
Place these scripts together inbase.html文件中，是实现网站全局功能统一管理和性能优化的**实践。因为几乎所有内容页面（如文章详情页、单页、列表页等）都会继承或包含base.htmlThis means that regardless of which page the user visits, these necessary Markdown rendering support scripts will only be loaded once. If on each content detail page template (for examplearchive/detail.htmlorpage/detail.htmlIntroducing these scripts separately will lead to redundant loading, which not only increases server bandwidth consumption and extends page loading time, but also imposes an unnecessary burden on the client browser, thereby damaging the user experience.
AnQiCMS's template engine is responsible for converting the Markdown text content input from the backendto Englishto standard HTML structure. For example,tag-/anqiapi-archive/142.htmlis mentionedContentField will be automatically converted to HTML by the Markdown editor, or it can be done throughrender=trueParameter is manually specified for conversion. This conversion process is completed on the server side or during template rendering.base.htmlThe scripts introduced in it, are those that perform styling and functional enhancement on the already converted HTML on the browser sideFurther styling and functional enhancement.For example, if the content contains mathematical formulas, MathJax will scan and render these formulas after the page is loaded; if the content contains Mermaid chart syntax, Mermaid will convert it into an SVG chart.
Therefore, from the perspectives of functional implementation, performance optimization, and ease of maintenance, the design and documentation of AnQiCMS clearly indicate that these Markdown-related scripts should be placed atbase.htmlIn this global template file, there is no need to add it repeatedly in other specific page templates.This centralized management approach ensures consistency, efficiency, and reduces the complexity of later maintenance.
Frequently Asked Questions
Q1: Why does AnQiCMS not automatically load these scripts after I enable the Markdown editor?
AnQiCMS as a highly customizable CMS, provides users with great flexibility.Although the Markdown editor is enabled in the background, the content can be converted to HTML when saved, but the style of front-end display and additional features (such as mathematical formulas, flowcharts) require specific front-end library support.These libraries may need to be loaded from a CDN, or users may choose to host them themselves, or even may need to customize their loading behavior or version.base.htmlIntegrate, to adapt to different customization requirements and performance optimization strategies, rather than forcing automatic loading of resources that may not be needed by all users.
Q2: If I forget tobase.htmlWhat will happen if you add these Markdown-related scripts?
If you havebase.htmlIf these scripts are missing, you will see Markdown text content (because the CMS backend has already converted it to HTML), but the display effect will be affected.The specific manifestation is: The missing GitHub Markdown CSS can lead to Markdown elements (such as headings, lists, code blocks) lacking standard styles, which may look rather ordinary or be inconsistent with the overall style of the page.It is more important that the mathematical formulas in the content will not be rendered by MathJax, but will be displayed in their original LaTeX or MathML code form; Mermaid charts such as flowcharts and sequence diagrams will also not be correctly parsed and rendered, but will only show their text definitions, which will seriously affect the users' understanding and reading experience of this content.
Q3: Can I put these Markdown scripts in a separate local (partial) template file, thenbase.htmlreference it in{% include %}reference tags?
Technically, this is feasible. You can create a local file named, for examplepartial/markdown_scripts.htmland put all Markdown-related<link>and<script>tags in it, then inbase.htmlof<head>use a control character inside{% include "partial/markdown_scripts.html" %}Cite this. This approach will not affect the loading effect of the script, and it can help further refine complex template structuresbase.htmlThe content, making it more concise. However, for these scripts that belong to the global basic functions of the website, it is recommended to place them directlybase.htmlThis is the most direct, standard, and easy-to-understand and maintain method, avoiding unnecessary template file nesting levels.