An efficient and customizable content management system, AnQi CMS provides great flexibility in content display.For content creation, we are well aware of the convenience and popularity of Markdown.github-markdown.min.cssProviding a consistent and aesthetically pleasing style.However, as website operators, we often encounter situations where we need to customize the personalized style of the content rendered after Markdown according to brand image, user experience, or specific business requirements.
This article will detail how to implement custom CSS styles after Markdown rendering in the Anqi CMS, completely摆脱default stylesgithub-markdown.min.cssLimit, making your content display more distinctive.
Understand the template structure and Markdown rendering mechanism of AnQi CMS
In the Anqi CMS, the presentation of website pages is inseparable from its powerful template system. According to the documents "Some Basic Conventions for Template Creation" and "Directory and Templates for Template Creation", our template files are usually in.htmlThe suffixes are stored in the directory./templateUnder the directory, while static resources such as CSS, JS, and images are managed in a unified manner/public/static/Within the directory. Pages usually have a basic template, such asbase.htmlEnglish translation: , used to define the overall layout of the website and to include global resources.
The document 'How to Properly Use Markdown and Display Mathematical Formulas and Flowcharts on Web Pages' clearly points out that in order to apply the default Markdown style on a web page, we need to inbase.htmlThe file header should add the following line of code:
<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 line of code is responsible for loading from the external CDNgithub-markdown.min.css，of all Markdown-rendered HTML elements provides default GitHub style. Markdown itself does not contain style, it simply converts specific markups to standard HTML tags (such as,# 标题will be converted to<h1>,**粗体**will be converted to<strong>）。Therefore, to customize the Markdown style, essentially it is to define CSS styles for these HTML tags converted from Markdown.
Remove default Markdown style
The first step of customization is to remove or disable the defaultgithub-markdown.min.css. If you directly inbase.htmlMay not take effect due to CSS selector weight issues, or increase unnecessary code volume. The most direct and effective method is tobase.htmlFind and comment out or delete the above importsgithub-markdown.min.cssof<link>Label.
in your templatebase.htmlFile, locate the following code line similar to:
{# ... 其他样式或元数据 ... #}
<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" />
{# ... 其他样式或元数据 ... #}
Comment it out:
{# ... 其他样式或元数据 ... #}
{# <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" /> #}
{# ... 其他样式或元数据 ... #}
or directly delete this line of code.After completing this step, your Markdown content on the page will no longer have the default GitHub style, and it will usually be presented with the browser's default HTML element styles.
Create a custom Markdown style import
Next, we will create our own CSS file to define the styles of Markdown content. According to the static resource management conventions of Anqi CMS, we can place the custom CSS file in/public/static/css/Under the directory, for example namedcustom-markdown.css.
You can use tools such as FTP, SFTP, or Baota panel, etc., in the root directory of the website./public/static/css/Create a new CSS file under the path,custom-markdown.css.
in the newly createdcustom-markdown.cssIn the file, you can start defining styles for HTML elements rendered by Markdown. Here is a simple example showing how to define styles for some common Markdown elements:
/* custom-markdown.css */
/* 定义整个Markdown内容容器的样式 */
.markdown-body {
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, "Fira Sans", "Droid Sans", "Helvetica Neue", sans-serif;
line-height: 1.6;
color: #333;
padding: 20px;
background-color: #fff;
border-radius: 5px;
box-shadow: 0 2px 5px rgba(0, 0, 0, 0.1);
}
/* 标题样式 */
.markdown-body h1 {
font-size: 2.2em;
border-bottom: 1px solid #eee;
padding-bottom: 0.3em;
margin-top: 1em;
margin-bottom: 16px;
color: #2196f3; /* 蓝色 */
}
.markdown-body h2 {
font-size: 1.8em;
border-bottom: 1px dashed #eee;
padding-bottom: 0.3em;
margin-top: 1em;
margin-bottom: 16px;
color: #4caf50; /* 绿色 */
}
.markdown-body h3 {
font-size: 1.4em;
margin-top: 1em;
margin-bottom: 16px;
color: #ff9800; /* 橙色 */
}
/* 段落样式 */
.markdown-body p {
margin-bottom: 1em;
}
/* 链接样式 */
.markdown-body a {
color: #0366d6;
text-decoration: none;
}
.markdown-body a:hover {
text-decoration: underline;
}
/* 列表样式 */
.markdown-body ul, .markdown-body ol {
margin-left: 20px;
margin-bottom: 1em;
}
.markdown-body ul li {
list-style-type: disc;
}
.markdown-body ol li {
list-style-type: decimal;
}
/* 引用块样式 */
.markdown-body blockquote {
border-left: 4px solid #ccc;
padding: 0 1em;
color: #6a737d;
margin: 1em 0;
background-color: #f9f9f9;
}
/* 行内代码样式 */
.markdown-body code {
background-color: rgba(27,31,35,.05);
border-radius: 3px;
padding: 0.2em 0.4em;
font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, Courier, monospace;
font-size: 85%;
color: #e91e63; /* 粉色 */
}
/* 代码块样式 */
.markdown-body pre {
background-color: #282c34;
color: #abb2bf;
padding: 1em;
border-radius: 5px;
overflow-x: auto;
font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, Courier, monospace;
}
.markdown-body pre code {
background-color: transparent;
padding: 0;
color: inherit;
font-size: 100%;
}
/* 表格样式 */
.markdown-body table {
width: 100%;
border-collapse: collapse;
margin-bottom: 1em;
font-size: 0.9em;
}
.markdown-body table th, .markdown-body table td {
border: 1px solid #ddd;
padding: 8px;
text-align: left;
}
.markdown-body table th {
background-color: #f2f2f2;
font-weight: bold;
}
Define the custom style after, you need tobase.htmlinclude this new CSS file. In the position where the default style was previously removed, add the following code:
{# ... 其他样式或元数据 ... #}
<link rel="stylesheet" href="{% system with name='TemplateUrl' %}/css/custom-markdown.css" />
{# ... 其他样式或元数据 ... #}
Here we used{% system with name='TemplateUrl' %}Label. According to the description in the 'System Tags' document,TemplateUrlCan obtain the template static file address, which ensures that your CSS file can be loaded correctly, even in multi-site or different deployment environments while maintaining the correctness of the path.
Important reminder:
Markdown content is wrapped by a container with a specific class or id by default in AnQi CMS (usually the result of editor rendering). To ensure that your CSS styles are applied only to Markdown content and do not affect other parts of the page, it is recommended to wrap Markdown content in a container with a specific class.divElement inside, for examplemarkdown-body.If you cannot directly control the class of the outer container of the content, you may need to check the browser developer tools to understand the actual HTML structure of the rendered Markdown content and write more targeted CSS selectors.
For example, in your article detail template (such asarchive/detail.html) the rendered content of Markdown is usually through{% archiveDetail archiveContent with name="Content" %}{{archiveContent|safe}}{% endarchiveDetail %}This label output. You can wrap this output with a layer outside of itdiv:
<div class="markdown-body">
{%- archiveDetail articleContent with name="Content" render=true %}
{{articleContent|safe}}
{% endarchiveDetail %}
</div>
Please noterender=true参数，它明确告诉系统对内容进行Markdown到HTML的转换。If your Markdown editor is enabled, it is usually not necessary to explicitly set this parameter, but for compatibility and clarity, it is a good habit to include it.
Test and optimize
After completing the above steps, you need to clear the cache of Anqi CMS (operated in the "Update Cache" feature in the background), then refresh your website page to check if the Markdown content style is displayed as expected.
Use the browser's developer tools (usually press F12 key), you can check the HTML structure of the rendered Markdown content and adjust CSS styles in real time.This helps you understand how Markdown syntax is converted to HTML elements, and accurately locate the style rules that need to be modified.
Iterate and test until your Markdown content presents the visual effect you expect.This method not only provides complete style control, but also makes your website content more consistent with the overall design.
Common Questions and Answers (FAQ)
1. I have added custom CSS and cleared the cache, but the Markdown style still does not change, why is that?
This is usually caused by several reasons. First, please make sure that you have completely removed the default.github-markdown.min.cssCitation, not just overlay. Next, check if your custom CSS file path is correct, as well asbase.htmlintroducing the file in<link>Label is written correctly. You can use the browser's developer tools network tab to viewcustom-markdown.cssFile has been loaded successfully. If the loading fails, please check the path.
Another common reason is the priority issue of CSS selectors.If your custom CSS selector weight is not high enough, it may be overridden by other default styles or framework styles..markdown-body h1or add after the style declaration!important（Not recommended for abuse, but can be used for debugging). Also, ensure that your Markdown content is indeed enclosed by a container that has.markdown-bodyclass:divor an appropriate container.
2. How to know what HTML tags Markdown will generate, so that I can write CSS specifically?
The most direct and effective method is to write various Markdown syntaxes (such as headings, paragraphs, lists, links, code blocks, tables, etc.) in a simple Markdown document, and then view the rendering results of the document in the browser.Use the browser's developer tools (usually open by pressing F12), right-click on an element within the Markdown content, and select "Inspect Element" to see the corresponding HTML tag structure of the Markdown syntax.
For example, you will find after checking:
# Headingwill generate<h1>## Subheadingwill generate<h2>This is a paragraph.will generate<p>* List itemwill generate<ul><li>1. Ordered itemwill generate<ol><li>`inline code`will generate<code>- `