In AnQiCMS, introducing a third-party JavaScript library is a very effective means to make your content display more expressive and professional.For example, by using Markdown to write structured text, using MathJax to display complex mathematical formulas, or utilizing Mermaid to draw intuitive flowcharts, can greatly enrich the user's reading experience.AnQiCMS's powerful template system provides us with a flexible integration method.

Overview of AnQiCMS template system

Let's take a simple review of the template operation mechanism of AnQiCMS. The template files of AnQiCMS are.htmlsuffix, and stored in a unified manner/templateThe directory. You will find that the template uses a syntax style similar to Django, through double curly braces{{变量}}to output content, and conditional judgment and loop control are used{% 标签 %}The format in question. Static resources (such as custom JS scripts, CSS styles, images) are usually placed in/public/static/In the catalog.

AnQiCMS encourages the use of structure in templates.extendsLabel defines a basic skeleton template (usuallybase.html)，other page templates inherit from this skeleton. At the same time,includeThe tag allows you to encapsulate frequently used code snippets (such as headers, footers, sidebars, etc.) into independent files, and reference them where needed, which provides convenience for us to centrally manage and import third-party resources.

Introduce the core strategy of using third-party JavaScript libraries

Introducing third-party JavaScript libraries usually involves two primary methods: loading through a Content Delivery Network (CDN) or downloading the library file to a local server and referencing it. Regardless of the method, the core operation is to add in the template file.<script>or<link>Label.

For libraries that need to take effect throughout the entire site or be used on multiple pages, the recommended practice is to include them in your websiteBasic skeleton templates (for example)base.html)of<head>inside tags or</body>End tag before. 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 JavaScript libraries that need to initialize or render content 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 when the page is loaded).But it should be noted that placing too many scripts here may block page rendering and affect the loading speed on the first load.
  • </body>End tag before:Applicable to most JavaScript libraries that operate 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.

English 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 integrate third-party libraries for Markdown rendering, mathematical formulas, and flowcharts.

Step 1: Enable Markdown Editor

Before you start, please make sure to go to the AnQiCMS backend, click sequentiallyGlobal Settings -> Content Settings, find andEnable Markdown Editor. This is the prerequisite for all Markdown-related features to take effect.

Introduce Markdown style: enhance 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-cssis a popular choice that allows your Markdown content to look like GitHub's Markdown.

you can use in yourbase.htmlTemplate file's<head>tag, add 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" />

So, when your article content uses Markdown syntax, it will automatically apply styles similar to GitHub.

Beautifully present mathematical formulas: MathJax

For content containing complex mathematical formulas, MathJax is an indispensable tool.It can render mathematical formulas in formats such as LaTeX, MathML into high-quality, easy-to-read images or fonts.

Similarly, inbase.htmlTemplate file's<head>标签内，添加MathJax的JavaScript引用：

<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 and will not block the parsing of the page. After MathJax is loaded, it will automatically scan for mathematical formula tags in the page and render them.

Dynamic drawing of flowchart: Mermaid

Mermaid is an English-based JavaScript chart drawing tool that allows you to generate flowcharts, sequence diagrams, Gantt charts, and more using simple text descriptions.This is very useful for displaying business processes, technical architectures, and the like.

The introduction of the Mermaid library is usually placed inbase.htmlof<head>And a 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 achieves that bytype="module"Introduce the Mermaid module and set it up during initializationstartOnLoad: true,indicating that Mermaid will automatically find and render charts after the page is loaded.

Key points and注意事项

  1. Template file modification path:You can in/templateFind the template you are currently using in the directory, and edit the one in.htmlthe file. If your template usesincludeorextends, it usually needs to bebase.htmlor public header files (such aspartial/header.html) add the above code.
  2. CDN and local hosting:All the examples above used CDN services (such as cdnjs, jsdelivr) to load third-party libraries.The advantage of CDN lies in fast loading speed and bandwidth saving./public/static/您的模板名/jsor/public/static/您的模板名/cssin the directory, then replace the CDN link in the template with the local path.
  3. Compatibility and version:When introducing third-party libraries, please pay attention to their compatibility with your existing page scripts. Try to choose stable and widely used versions.
  4. 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.
    • Math formula:Use$$...$$or$...$Enclose formula (depending on MathJax configuration).
    • Flow chart:Using Mermaid's specific syntax, for example:
      graph TD
    A[Start] --> B{Decision};
    B -- Yes --> C[Perform action];
    C --> D[End];
    B -- No --> D;
  5. Clear 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 effects.If it still does not work, please check the browser console (F12) for any error messages.

By following these steps, you will be able to easily integrate third-party JavaScript libraries into AnQiCMS templates, adding more vitality and professionalism to your website content, thereby providing a richer and more attractive user experience.

Common Questions (FAQ)

Q1: I have added the script according to the steps, but the mathematical formula or flowchart on the page is not rendered correctly. How should I troubleshoot?

A1: Firstly, please check if your AnQiCMS backend is already set upGlobal Settings -> Content SettingsinEnable Markdown Editor.其次，打开浏览器的开发者工具（通常按F12），查看“控制台”（Console）标签页是否有任何JavaScript错误信息，这通常是渲染失败的直接原因。Also, 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 requirements for syntax.

Q2: Can I download these third-party library files to the local server for hosting? If so, where should the files be placed, and how should they be referenced in the template?

A2: Absolutely. After downloading the library files locally, it is recommended that you place them in the static resources 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 directory. For example, if your template name isdefault，you can refer togithub-markdown-cssfile placed in/public/static/default/css/github-markdown.min.css, then inbase.htmlas<link rel="stylesheet" href="/static/default/css/github-markdown.min.css" />This helps to reduce external dependencies and improve website stability.

**Q3: I only want to load on specific types of article pages (such as technical blogs)