How to correctly render Markdown format in HTML and display mathematical formulas in the article content?
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 Markdown support in the system.But to render these Markdown contents, especially complex mathematical formulas, correctly and beautifully on the web, indeed, we need to do some front-end configuration.This is like using Markdown to write the skeleton of an article, and we still need appropriate 'decorating materials' to make it shine.
Enable Markdown Editor: The First Step of 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:
- Log in to the AnQiCMS backend.
- Go toGlobal Settingsand then selectContent settings.
- In this interface, you will find an option to useEnable 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
The Markdown editor can help us convert content to HTML, but browsers themselves cannot directly understand and render highly professional symbols such as mathematical formulas.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, in order 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 place them in the public header file of the website template, usuallybase.htmlAdd the corresponding code in the global template file similar to this one.)
1. Add beautiful styles to the Markdown content.
We can introduce a universal Markdown style library to make the rendered Markdown content look professional and easy to read, for examplegithub-markdown-css. You can usebase.htmlthe file<head>Add the following style reference within the tag:
<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 way, your Markdown content will have a simple and beautiful style similar to GitHub on the page.
2. Implement the correct display of mathematical formulas
The core part is coming up - displaying mathematical formulas. We also need to rely on a powerful JavaScript library to accomplish 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>Add the MathJax reference script immediately after the above Markdown style tag:
<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 types of formula writing methods by default:
Inline Formula (Inline Math):Used to embed short 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 to display long or important mathematical formulas independently, 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} \)$
Extra scenario: manually render Markdown content
Generally, content published through the AnQiCMS backend Markdown editor is automatically rendered by the system. However, if your Markdown content does not come directly from the built-in editor, for example, if it is imported from external data or stored in custom fields (such asintroduction/contentIn the field, you may need to manually indicate the system for rendering in the template.
AnQiCMS provides a very practicalrenderfilter. When you leave the document details tagarchiveDetail）、Category Detail Tag（categoryDetail）Or Single Page Detail Tag（pageDetail）Etc. When obtaining content that may contain Markdown, you can userendera filter to ensure proper conversion.
For example, if you have a custom fieldintroductionStored content in Markdown format, and you want to display it in the front-end template:
{% archiveDetail introduction with name="introduction" %}
{{ introduction|render|safe }}
Here|renderTell AnQiCMS tointroductionThe Markdown text in the variable is converted to HTML.|safeThe filter is crucial, it indicates to the template engine that this HTML content is safe, does not require further escaping, thus avoiding HTML tags from being displayed as raw strings, ensuring the rendering effect.
Summarize
You need to implement professional Markdown content rendering and display of mathematical formulas in AnQiCMS:
- In the AnQiCMS background,Global Settings > Content SettingsEnable Markdown Editor in Chinese.
- Edit the website template's
base.htmlFile, in<head>Tags inside the introductiongithub-markdown-cssThe stylesheet provides beautiful display effects for Markdown content. - Similarly, in
base.htmlthe file<head>Within the tag, introduce the MathJax JavaScript library to parse and render mathematical formulas on the page. - Use standard LaTeX syntax in the article content (
$...$for inline,$$...$$for block-level) to write mathematical formulas. - If Markdown content comes from non-standard sources (such as custom fields), use it in the template
{{ 变量|render|safe }}to ensure that the content is correctly rendered as HTML.
By these simple configurations, your AnQiCMS website can display more professional and rich content forms, whether it is popular science articles, technical tutorials, or academic papers, they can be presented to readers in **status**.
Frequently Asked 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.htmlthe MathJax in the file<script>Did the tag add correctly and was it not blocked by other JavaScript errors. Confirm that the syntax of the mathematical formula you are using is LaTeX supported by MathJax, such as inline formulas using$E=mc^2$Block-level formulas are used$$ \int x^2 dx $$Additionally, certain browser extensions may interfere with MathJax rendering; try viewing in incognito mode or disabling extensions.
2. Will my website's loading speed slow down after introducing MathJax and Github Markdown CSS?
Since MathJax and Github Markdown CSS are loaded via CDN (Content Delivery Network), their loading speed is usually fast.CDN will select the server node closest to the user for distribution, which helps to optimize the global user access experience.However, if you have the highest requirements for website performance, you can consider downloading these static resources to your own server and managing them through the AnQiCMS resource storage feature, but this usually requires more professional server configuration and maintenance experience.
3. Does AnQiCMS support customizing the font or color of mathematical formulas?
MathJax provides a rich set of configuration options for customizing the display style of formulas. You can do this after including the MathJax script, in another<script>Add MathJax configuration code to the tag. For example, you can configure the rendering engine, font, color, and so on.AnQiCMS itself does not provide backend settings to modify these MathJax underlying configurations, but since MathJax is a JavaScript library running on the front end, you can modify it directlybase.htmlJavaScript code to implement high customization, for specific details, please refer to the official MathJax documentation.