The `mermaid` initialization script should be placed in which part of `base.html` to load correctly?
In the operation practice of AnQi CMS websites, we deeply understand that it is crucial to provide users with rich and diverse content display forms.With the introduction of the Markdown editor in the new Anqi CMS, content creators can easily insert mathematical formulas and flowcharts, which undoubtedly greatly enhances the expressiveness of the content.However, the correct display of these advanced contents cannot be achieved without the collaborative efforts of front-end scripts.mermaidThe initialization script is in the AnQiCMS template system.base.htmlIn the file, where should it be placed to ensure it loads and runs normally.
First, let's understandbase.htmlIn the core position of the AnQiCMS template structure. According to the AnQiCMS template production conventions,base.htmlIs a key file that carries the public code of the website, it usually contains the header, footer, and other shared parts that are inherited and referenced by each page.This means that any global styles, metadata, or JavaScript scripts that need to be effective throughout the entire site should be included in this basic template file.base.htmlit can effectively improve the maintainability and loading efficiency of the template.
mermaidIt is a powerful JavaScript library that allows us to define and render flowcharts, sequence diagrams, and more with simple text syntax.It normally works depending on the loading and execution of JavaScript.mermaidThe initialization script uses the ES Module import method and is set tostartOnLoad: trueThis means it expects to automatically scan the document and render the chart when the page is fully loaded.
Based onmermaidthis feature and the AnQiCMS template loading mechanism,mermaidThe initialization script should be placed inbase.htmlthe file<head>Label inside.In particular, it is located after other possibly required global stylesheets (such as GitHub Markdown CSS) and auxiliary scripts (such as MathJax mathematical formula rendering scripts).
Place the script in<head>tag, which can ensure that the browser has already loaded and prepared before parsing the main content of the pagemermaidScript. So when the browser starts rendering the DOM element containing the Mermaid chart, mermaidThe library is ready and can quickly identify and process these charts, avoiding the problem of charts not displaying or flickering (FOUC, Flash Of Unstyled Content) due to the script loading lag.
secondly,mermaidThe initialization script containsimporta statement indicating it is an ES module. Modern browsers typically load and execute the module asynchronously when parsing to<script type="module">but place it in<head>It is still **practice, because it ensures that the module is identified at an early stage of document structure parsing. At the same time,mermaid.initialize({ startOnLoad: true });The configuration ensures that the script will automatically run after the DOM content of the page is loaded, without manual triggering, which is in line with its design intention and simplifies the integration work of developers.
The following is based on the AnQiCMS document,base.htmlthe recommended placement method for related scripts and style introductions, including,mermaidThe correct position for initializing the script:
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>您的网站标题</title>
<!-- 其他Meta标签和CSS样式链接 -->
<!-- 在网页上应用Markdown默认样式 -->
<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" />
<!-- 网页上数学公式的正确显示 -->
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
<!-- 网页上流程图的正确显示（Mermaid初始化脚本） -->
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
</script>
</head>
<body>
<!-- 您的网站内容 -->
</body>
</html>
In summary, themermaidplace the initializing script atbase.htmlthe file<head>The content inside the tag ensures that the flowchart is correctly loaded and rendered on the AnQiCMS website.This not only conforms to the HTML standard recommendations, but also ensures that users can enjoy a smooth and complete visual experience when accessing the page.
Frequently Asked Questions (FAQ)
1. WhymermaidThe script needs to be placed<head>in the tag instead<body>at the end of the tag?
tomermaidThe script is placed<head>To ensure that the script is loaded and initialized before the browser parses and renders the page content (especially DOM elements that may contain Mermaid charts).mermaid.initialize({ startOnLoad: true });The configuration means that the script will listen for page load events and automatically scan and render charts when the DOM content is ready. If the script is placed<body>At the end, there may be a phenomenon of chart rendering lag or page content flicker (Flash Of Unstyled Content), affecting user experience.Preloading and initializing can make the chart appear earlier and more stably in front of the user.
2. If the Mermaid diagram on the page does not render, what aspects should I check?
If the Mermaid diagram is not rendered normally, you can check from the following aspects:
- Script path and CDN availability: Check
mermaidThe CDN address of the script (for examplehttps://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjsWhether correct and whether the CDN service is accessible. - Mermaid chart syntax: Confirm that the Mermaid chart syntax you are using in the Markdown content conforms to the official specification.A small syntax error can cause the chart to not render.
- AnQiCMS background settings: Make sure you have enabled the Markdown editor in the "Global Settings -> Content Settings" of the AnQiCMS backend.This is the premise for supporting Mermaid chart display.
- Browser developer tools: Open the browser's developer tools (usually press F12), check the 'Console' tab for JavaScript error messages, or the 'Network' tab to
mermaidIs the script loading failed.
3. BesidesmermaidWhat types of scripts or styles are also recommended to be placedbase.htmlof<head>in the tag?
exceptmermaidAny layout, basic style, metadata, or functional scripts that need to take effect before the content of the page is displayed should be placed inbase.htmlof<head>tags. This includes:
- The website's global CSS stylesheet: Such as custom theme styles, UI framework styles (such as Bootstrap, Tailwind CSS).
- SEO-related meta tags: Such as
meta description/meta keywords/link canonicaletc. - Web font loading: Such as Google Fonts, Adobe Fonts, they are usually through
<link>tags or@importRule introduction. - Website icon:
<link rel="icon">or<link rel="apple-touch-icon">. - Other global JavaScript libraries: Such as MathJax used to process mathematical formulas, or statistical code that needs to be executed at the beginning of page loading (although some statistical code is recommended to be placed
<body>The bottom does not block page rendering).