In the operation of the Anqi CMS website, for Markdown-related scripts, in addition tobase.htmlIn addition to configuration in the file, it is usually not necessary to add these scripts again in other template files.This is a comprehensive consideration based on the inheritance mechanism of AnQiCMS templates, content rendering process, and website performance optimization.
The design philosophy of AnQiCMS emphasizes efficiency and customizability, its template system adopts syntax similar to the Django template engine, the core beingbase.htmlAs the foundation of a website. This file carries the universal layout, common style sheets, and global JavaScript scripts of the website.After enabling the Markdown editor in the AnQiCMS background global settings, and following the official documentationhelp-markdown.mdThe guidance, to introduce GitHub Markdown CSS, MathJax, and Mermaid related scriptsbase.htmlof<head>When the area is enabled, these features are already in effect throughout the entire website.
To be specific,github-markdown-cssIt provides the default styling for Markdown content, making the parsed HTML content more readable.MathJaxIt is 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. AndMermaidIt is a JavaScript library that allows users to create flowcharts, sequence diagrams, and other charts 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 in one locationbase.htmlIn the document, it is a**practice**that unifies the management of the global functions of the website and optimizes performance. Because almost all content pages (such as article detail pages, single pages, list pages, etc.) will inherit or includebase.htmlThis means that no matter which page the user visits, these necessary Markdown rendering support scripts will only be loaded once. If in each content detail page template (such asarchive/detail.htmlorpage/detail.htmlThese scripts introduced individually will cause redundant loading, not only increasing server bandwidth consumption and extending page loading time, but also bringing unnecessary burden to the client browser, which will damage the user experience.
The AnQiCMS template engine is responsible for converting the Markdown text content input from the background into standard HTML structure.TranslateFor example,tag-/anqiapi-archive/142.htmlmentionedContentThe field will automatically convert Markdown to HTML when the Markdown editor is enabled, or you can userender=trueThe parameter is manually specified for conversion. This conversion process is completed on the server side or in the template rendering phase. Andbase.htmlScripts that are introduced are those that perform further style rendering and feature enhancement on the already converted HTML on the browser sideFurther style rendering and feature enhancementFor 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 to an SVG chart.
Therefore, from the perspective of functional implementation, performance optimization, and ease of maintenance, the design and documentation of AnQiCMS clearly states that these Markdown-related scripts should be placed atbase.htmlThis global template file does not need to be repeated in other specific page templates.This centralized management 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.Therefore, AnQiCMS chooses to entrust the control of these front-end resource references to website operators, through manual editingbase.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 when you add these Markdown-related scripts?
If you are inbase.htmlThese 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 issue is that GitHub Markdown CSS is missing, which causes Markdown elements (such as headings, lists, code blocks) to lack standard styles and may look quite ordinary or inconsistent with the overall page style.What is more, mathematical formulas in the content will not be rendered by MathJax, but will be displayed in their original LaTeX or MathML code form;Flowcharts and sequence diagrams, etc., will also not be correctly parsed and rendered, but will only display their text definitions, which will severely affect users' understanding and reading experience of the content.
Q3: Can I put these Markdown scripts in a separate partial template file and thenbase.htmlpass through{% include %}reference tags?
Technically, this is feasible. You can create a local file named for examplepartial/markdown_scripts.htmland place all Markdown-related<link>and<script>tags inside it, then proceed tobase.htmlof<head>Use within tags{% include "partial/markdown_scripts.html" %}Reference. This method will not affect the loading effect of the script, and it is helpful to further refine complex template structures.base.htmlThe content is made more concise. However, for these scripts that belong to the global basic functions of the website, they are directly placed inbase.htmlThis is the most direct, standard, and easy-to-understand and maintain method, avoiding unnecessary nesting levels of template files.