As an experienced CMS website operation personnel of an enterprise, I know that the details of content presentation are crucial to user experience.Especially for websites involving professional fields such as mathematical formulas, ensuring that content is presented in the clearest and most standardized way is crucial for attracting and retaining users.AnQi CMS provides support for Markdown syntax, making it possible to insert mathematical formulas, andMathJax-scriptThe real hero behind the implementation of this function.

This article will discuss in detail.MathJax-scriptThe placement and reasons in the Anqi CMS template, helping you optimize the content display of your website.

Understand the template structure of AnQi CMS

In AnQi CMS, the template is the skeleton of website content display. According to our development specifications, template files are usually stored in/templateUnder the directory, and use a syntax similar to the Django template engine. Among them,base.htmlPlaying a core role, it is the basic template for all pages (such as article detail pages, category list pages, single pages, etc.). This means that any inbase.htmlElements defined in it, including style sheets, meta tags, and scripts, will be automatically inherited by all pages that inherit it. Static resources such as CSS, JavaScript, and images are stored in a unified location./public/static/Directory.

MathJax-scriptThe function and loading requirements

MathJaxIs a cross-browser JavaScript library used to display mathematical formulas in web browsers.It can render mathematical expressions in formats such as LaTeX, MathML, or AsciiMath into high-quality, scalable formulas.To display the mathematical formula on the page correctly,MathJaxThe script needs to be executed after the HTML containing mathematical content has been loaded, so that it can find and process these formulas.

MathJax-scriptThe placement position of the **

Based on the official documentation of Anqi CMShelp-markdown.mdin the guidance,MathJax-scriptThe **placement position is within the tag of the template you are currently usingbase.htmlthe file<head>. Here is the specific code snippet:

<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>

Why choosebase.htmlof<head>?

toMathJax-scriptinbase.htmlof<head>The tag is based on the following key considerations:

first, Ensure global coverage and consistency.due tobase.htmlIs the foundation of all pages, placing it here means that all pages on your website, as long as the Markdown editor is enabled and contains mathematical formulas, will automatically receive MathJax support.This avoids the麻烦 of adding scripts individually to each page that may contain formulas, ensuring consistency and convenience in the rendering of mathematical formulas across the entire site.

secondly,Optimize user experience, avoid content flickering.toMathJax-scriptPlace it at the top of the page, which ensures that the script starts working as soon as the page content is loaded and parsed.This helps to complete the rendering of mathematical formulas before the user sees the page content.If the page is loaded at the bottom, the user may briefly see the unrendered original LaTeX code (commonly known as "Flash of Unstyled Content" or FOUC), which can greatly affect the reading experience.

Finally,UtilizeasyncAttributes are loaded non-blocking.The script loading method provided in the document usesasyncproperties. This meansMathJax-scriptIt will be downloaded asynchronously in the background without blocking the parsing of the HTML document.After the script is downloaded, it will execute when the HTML parsing is paused.This method ensures that the script can be discovered and downloaded by the browser as soon as possible, while also minimizing the impact on the initial rendering speed of the page, which is a good practice that balances performance and functional needs.

Specific operation steps

  1. Log in to your Anqi CMS backend.
  2. Navigate to the "Template Design" area, and find the template folder you are currently using.
  3. In the template folder, find and editbase.htmlfile.
  4. In<head>Inside the tag, usually other<meta>tags or<link>After the tag,</head>Before the tag, paste the aboveMathJax-scriptcode.
  5. Savebase.htmlfile.
  6. Important reminder:Make sure you have enabled the Markdown editor in the AnQi CMS backend, usually located at "AnQi CMS backend -> Global Settings -> Content Settings".This is because MathJax is commonly used to render mathematical formulas in Markdown content, and enabling the Markdown editor is a prerequisite for its normal operation.

By following these steps, your Anqi CMS website will be able to efficiently and elegantly display content containing mathematical formulas, thereby enhancing professionalism and user satisfaction.

Frequently Asked Questions (FAQ)

1. Q: Can I place the MathJax script in another location if only a few pages of my website need mathematical formulas?

A:Yes. Although it can be placedMathJax-scriptplacedbase.htmlof<head>It is the most common and recommended practice to ensure that all pages support mathematical formulas, but if you are sure that only a very few specific pages need this feature, you can consider adding the script directly to the template files of these pages (for example, the template of an article detail page)archive/detail.html）的<head>Part. This can reduce the overhead of loading unnecessary resources on pages that do not require MathJax functionality.Make sure the script is loaded before any mathematical formula content is rendered.

2. Q: Why is it recommended to useasyncthe attribute to load the MathJax script? What will be the impact of removing it?

A: asyncA feature introduced in HTML5 that allows the browser to download script files asynchronously in the background without blocking the parsing of the HTML document and the rendering of the page.This means that users can see the main content of the page faster.Once the script has been downloaded, it will execute when HTML parsing is paused.For scripts like MathJax that need to scan and modify page content,asyncIt is a very good choice because it ensures that the script is executed while also minimizing the perceived impact on the initial page loading speed. If removedasyncThe script will be loaded synchronously, which will block HTML parsing until the script is downloaded and executed, which may slow down page loading and increase user waiting time.

3. Q: In I willMathJax-scriptadd to the template, the mathematical formula still cannot be displayed correctly. How should I investigate the problem?

A:If the MathJax script has been added but the formulas are not displayed correctly, you can check from the following aspects:

*   **启用Markdown编辑器：** 确认在安企CMS后台的“全局设置 -> 内容设置”中，您已经启用了Markdown编辑器。MathJax通常用于渲染Markdown内容中的公式，这是其工作的前提。
*   **检查代码片段准确性：** 仔细核对您添加到`base.html`中的`MathJax-script`代码是否完全正确，包括URL和`async`属性。任何拼写错误或遗漏都可能导致脚本无法加载。
*   **清空浏览器缓存：** 有时浏览器会缓存旧的HTML文件，导致新的脚本没有被加载。尝试清空浏览器缓存或使用隐身模式访问页面。
*   **检查网络加载：** 使用浏览器的开发者工具（F12）查看“网络”选项卡，确认`MathJax-script`是否成功加载（HTTP状态码为200）。如果加载失败，可能是CDN服务问题或网络连接问题。
*   **公式语法检查：** 确保您在内容中使用的数学公式语法（如LaTeX）是正确的，并且符合MathJax的解析标准。