When using AnQiCMS to write articles, we often hope that the content is not limited to plain text or simple rich text, but can support richer formats, especially the convenience brought by Markdown syntax, as well as the indispensable mathematical formulas in scientific and technical content.This not only improves the quality of the content, but also provides a better reading experience for the readers.

AnQiCMS knows the importance of content diversity, and therefore provides support for Markdown in the system.But to render these Markdown contents, especially complex mathematical formulas, correctly and beautifully on the web, it indeed requires some front-end configuration.This is like writing the skeleton of an article in Markdown, and we still need suitable 'decoration materials' to make it shine.

Enable Markdown Editor: The First Step in Content Creation

Firstly, let's make sure that the article content can be edited and saved in Markdown format. This requires simple settings in the AnQiCMS backend:

  1. Log in to the AnQiCMS admin panel.
  2. Go toGlobal Settingsthen selectContent Settings.
  3. In this interface, you will find an option forEnable Markdown Editor. Check this option and save, so that you can choose to use the Markdown editor to write content when adding or editing articles.

When you use the Markdown editor to write articles, AnQiCMS will automatically convert your Markdown syntax content to basic HTML. For example, you enter the# 标题Will become<h1>标题</h1>,**加粗**Will become<strong>加粗</strong>.

Introduce front-end rendering capabilities: bring math formulas to life

Markdown editor can help convert content to HTML, but for highly specialized symbols like mathematical formulas, browsers themselves cannot understand and render them directly.This requires us to rely on some powerful third-party JavaScript libraries to parse and render these complex mathematical symbols, and at the same time, to present Markdown content with better visual effects, we also need a set of beautiful CSS styles.

These front-end rendering libraries and style files are usually introduced through content delivery networks (CDN) to ensure loading speed and stability. We need to include them in the public header file of the website template, which is typicallybase.htmlor similar global template files) add the corresponding code.

1. Add beautiful styles to Markdown content

To make the rendered Markdown content look professional and easy to read, we can introduce a universal Markdown style library, such asgithub-markdown-css. You can inbase.htmlthe file<head>Tags inside, add the following style reference:

<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" />

In this way, your Markdown content on the page will have a simple and beautiful style similar to GitHub.

2. English translation: Implement the correct display of mathematical formulas

The next part is the core content——displaying mathematical formulas.We also need to use a powerful JavaScript library to complete this task, MathJax is one of the most commonly used and powerful ones.It can parse LaTeX, MathML, and other formats of mathematical formulas and render them into clear mathematical symbols.

Inbase.htmlthe file<head>Tags, following the above Markdown style, add the MathJax reference script:

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

This script will asynchronously load the MathJax library. Once MathJax is loaded, it will automatically scan the mathematical formulas on the page and convert them into a readable format.

In the article content, you can use standard LaTeX syntax to write mathematical formulas. MathJax supports the following two main methods of writing formulas by default:

  • Inline Formula (Inline Math):Used to embed brief mathematical expressions in text paragraphs. You can use$ ... $to enclose inline formulas, for example:$E=mc^2$, the rendered effect is\(E=mc^2\).

  • Block Formula (Display Math):Used for independent display of longer or important mathematical formulas, which are usually centered and occupy a separate line. You can use$$ ... $$to enclose block-level formulas, for example:

    $$ \int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2} $$

    The rendered effect is: $\( \int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2} \) English$

额外场景：手动渲染Markdown内容 (English)

通常，通过AnQiCMS后台Markdown编辑器发布的内容会自动被系统渲染。但如果你的Markdown内容并非直接来自内置编辑器，例如是从外部导入的数据，或是存储在自定义字段（如English编辑器）introduction/contentField) you may need to manually indicate the system for rendering in the template.

AnQiCMS provides a very practicalrenderfilter. When you select the document details tag (archiveDetail）、分类详情标签（EnglishcategoryDetail）或单页详情标签（EnglishpageDetail）等获取可能包含Markdown的内容时，可以配合Englishrender过滤器来确保其正确转换。English

For example, if you have a custom fieldintroductionstored in Markdown format, and you want to display it in a frontend template:

{% archiveDetail introduction with name="introduction" %}
{{ introduction|render|safe }}

Here are the|rendertell AnQiCMS tointroductionVariable Markdown text is converted to HTML.|safeThe filter is crucial, it indicates to the template engine that this HTML content is safe and does not require further escaping, thus preventing HTML tags from being displayed as raw strings and ensuring the rendering effect.

Summarize

To implement professional rendering of Markdown content and display of mathematical formulas in AnQiCMS, you need:

  1. In the AnQiCMS backend,Global Settings > Content SettingsEnable Markdown Editor.
  2. Edit the website template'sbase.htmlfile, in<head>tags insidegithub-markdown-cssThe stylesheet provides a beautiful display effect for Markdown content.
  3. Similarly inbase.htmlthe file<head>Labels inside, introduce the MathJax JavaScript library to parse and render mathematical formulas in the page.
  4. In article content, use standard LaTeX syntax ($...$for in-line,$$...$$)to write mathematical formulas.
  5. If the Markdown content comes from non-standard sources (such as custom fields), ensure that the content is rendered correctly as HTML in the template.{{ 变量|render|safe }}the method, ensure that the content is rendered correctly as HTML.

Through these simple configurations, your AnQiCMS website can present more professional and rich content forms, whether it's popular science articles, technical tutorials, or academic papers, they can all be presented to the readers in **status**.

Common Questions (FAQ)

1. I have configured it according to the steps, but the mathematical formulas on the page are still not displayed correctly, why is that?

First, please checkbase.htmlMathJax in the file<script>Is the label correctly added and not blocked from loading by other JavaScript errors? Confirm that the syntax of the mathematical formula you are using is supported by MathJax LaTeX, for example, inline formulas use$E=mc^2$English block formula usage$$ \int x^2 dx $$Additionally, some browser plugins may interfere with the rendering of MathJax, try viewing in private mode or disabling plugins.

2. Will my website load slower after introducing MathJax and Github Markdown CSS?

Since MathJax and Github Markdown CSS are both loaded via CDN (Content Delivery Network), their loading speed is usually fast.CDN will select the nearest server node to the user for distribution, which is helpful for optimizing the global user access experience.However, if you have extreme requirements for website performance, you can consider downloading these static resources to your own server and managing them through the resource storage feature of AnQiCMS, but this usually requires more professional server configuration and maintenance experience.

3. If I want to customize the font or color of a mathematical formula, does AnQiCMS support it?

MathJax provides rich configuration options to customize the display style of formulas. You can do this by adding the MathJax script and then in another<script>Tag add MathJax configuration code.For example, you can configure the rendering engine, font, color, and other settings.base.htmlThe JavaScript code to implement height customization, for details, please refer to the official MathJax documentation.