How to introduce third-party JavaScript libraries (such as Markdown, mathematical formulas, flowcharts) in templates to enhance content display?
In AnQiCMS, introducing a third-party JavaScript library is a very effective means to make your content display more expressive and professional.For example, writing structured text with Markdown, displaying complex mathematical formulas with MathJax, or using Mermaid to draw intuitive flowcharts can greatly enrich the user's reading experience.The powerful template system of AnQiCMS provides us with a flexible integration method.
AnQiCMS template system overview
Let's briefly review the operation mechanism of AnQiCMS templates. The template files of AnQiCMS are.htmlsuffix and stored in/templateUnder the directory. You will find that the template uses a syntax similar to Django, through double curly braces{{变量}}to output content, while conditional judgment and loop control use{% 标签 %}The form. Static resources (such as custom JS scripts, CSS styles, images) are usually placed in/public/static/In the catalog.
On the template structure, AnQiCMS encourages the use ofextendsThe tag defines a basic skeleton template (usuallybase.html), and other page templates inherit this skeleton. At the same time,includeTags allow you to encapsulate commonly used code snippets (such as headers, footers, sidebars, etc.) into independent files and reference them where needed, which provides convenience for centralized management and the introduction of third-party resources.
The core strategy of introducing a third-party JavaScript library
Introducing third-party JavaScript libraries usually involves two main methods: loading through a content delivery network (CDN) or downloading the library file to a local server for reference. Regardless of the method, the core operation is to add it in the template file.<script>or<link>.
For libraries that need to take effect throughout the entire site or on multiple pages, the most recommended practice is to include them in your website'sBasic framework template (for examplebase.html)of<head>Inside the tag or</body>Before the closing tag. So, as long as the page inherits this basic template, the libraries introduced will be loaded automatically.
Choose the appropriate loading location
<head>Inside the tag:Suitable for CSS style libraries (such as Markdown styles) and those JavaScript libraries that need to be initialized or rendered before the page DOM is built (such as some mathematical formula rendering libraries and flowchart drawing libraries, which may need to process specific tags immediately upon page loading).However, it should be noted that too many scripts placed here may block page rendering and affect the loading speed of the first visit.</body>Before the closing tag:JavaScript libraries that are suitable for most operations depending on DOM elements, which ensures that the DOM elements are fully loaded without blocking the initial rendering of the page, thus enhancing the perceived loading speed of the user.
Practical Guide: Enhanced Content Display
AnQiCMS has built-in support for Markdown editors and provides relevant settings options in the background, making it particularly convenient to introduce third-party libraries for Markdown rendering, mathematical formulas, and flowcharts.
Step 1: Enable Markdown editor
Before starting, please make sure to go to the AnQiCMS backend and click sequentiallyGlobal settings -> Content settings, find andEnable Markdown editor. This is the prerequisite for all Markdown-related features to take effect.
Introduce Markdown style: improve reading experience
Markdown itself is just a markup language, to make it display beautifully on the web page, we need to introduce the corresponding CSS.github-markdown-cssIt is a popular choice that allows your Markdown content to look like GitHub's Markdown.
You can use it in yourbase.htmltemplate file<head>the tag the followinglinkTags:
<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 automatically apply a style similar to GitHub when your article content uses Markdown syntax.
Beautifully render mathematical formulas: MathJax
For content that includes complex mathematical formulas, MathJax is an indispensable tool.It can render mathematical formulas in LaTeX, MathML, and other formats into high-quality, easy-to-read images or fonts.
Similarly, inbase.htmltemplate file<head>Inside the tag, add the MathJax JavaScript reference:
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
asyncThe attribute indicates that the script will load asynchronously without blocking the page parsing. After MathJax is loaded, it will automatically scan the mathematical formula tags on the page and render them.
Dynamic drawing of flowcharts: Mermaid
Mermaid is a JavaScript-based chart drawing tool that allows you to generate flowcharts, sequence diagrams, Gantt charts, and more using simple text descriptions.This is very useful for demonstrating business processes, technical architectures, and so on.
The introduction of the Mermaid library is usually placed inbase.htmlof<head>and simple initialization is required:
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
</script>
This code passestype="module"Introduce the Mermaid module and set it up during initializationstartOnLoad: true, indicating that Mermaid automatically searches for and renders charts after the page is loaded.
Key points and注意事项
- The modification path of the template file:You can
/templateFind the template you are currently using in the directory, and edit the files in it. If your template uses.html, it is usually necessary toincludeorextends,base.htmlOr in a public header file (such aspartial/header.htmlAdd the above code in it. - CDN and local hosting:The example above used CDN services (such as cdnjs, jsdelivr) to load third-party libraries.The advantage of CDN lies in its fast loading speed and saving server bandwidth.If you have concerns about network dependency or have specific version control requirements, you can also download these library files and place them in
/public/static/您的模板名/jsor/public/static/您的模板名/cssIn the directory, then replace the CDN link in the template with the local path. - Compatibility and version:When introducing third-party libraries, please pay attention to the compatibility of their versions with your existing page scripts. Try to choose stable and widely used versions.
- Content writing:After introducing these libraries, you can use the corresponding syntax to write content in the AnQiCMS backend editor (in Markdown mode). For example:
- Markdown:Write Markdown normally.
- Mathematical formula:Use
$$...$$or$...$Enclose the formula (depending on MathJax configuration). - Flowchart:Use Mermaid's specific syntax, for example:
graph TD A[Start] --> B{Decision}; B -- Yes --> C[Perform Action]; C --> D[End]; B -- No --> D;
- Clear the cache:After modifying the template file, the browser may sometimes cache the old page content.Please try clearing the browser cache or force refresh the page (Ctrl+F5) to view the latest effect.If it still does not work, please check if there are any error messages in the browser console (F12).
By following these steps, you will be able to easily introduce third-party JavaScript libraries into the AnQiCMS template, adding more vitality and professionalism to your website content, thereby providing a richer and more attractive user experience.
Frequently Asked Questions (FAQ)
Q1: I have added the script according to the steps, but the mathematical formulas or flowcharts on the page are not rendered correctly. How should I troubleshoot?
A1: First, please check if your AnQiCMS background is already set upGlobal settings -> Content settingsinEnable Markdown editorNext, open the browser's developer tools (usually press F12), and check the 'Console' tab for any JavaScript error messages, as these are often the direct cause of rendering failures.At the same time, check the "Network" tab to confirm that all CDN resources (MathJax, Mermaid, github-markdown-css) have been successfully loaded (status code 200).Finally, check whether the mathematical formula or flowchart syntax you use in the content editor is correct, as these libraries have strict syntax requirements.
Q2: Can I download these third-party library files to host them on a local server? If so, where should the files be placed, and how should they be referenced in the template?
A2: Absolutely. After downloading the library files to your local machine, it is recommended that you place them in the static resource directory of the current template, for example/public/static/您的模板名/jsand/public/static/您的模板名/css. Then, when referencing in the template, replace the CDN link with the local path relative to your website root. For example, if your template is nameddefault, you can placegithub-markdown-cssplaced in/public/static/default/css/github-markdown.min.css, then inbase.htmlreferenced as<link rel="stylesheet" href="/static/default/css/github-markdown.min.css" />This helps reduce external dependencies and improve website stability.
**Q3: I only want to load on specific types of article pages (such as technical blogs)