How to customize the CSS style of Markdown rendering instead of using the default `github-markdown.min.css`?

AnQi CMS is an efficient and customizable content management system that provides great flexibility in content display.For content creation, we are well aware of the convenience and popularity of Markdown.The new version of AnQi CMS also fully supports Markdown editors and can render the content into HTML by default, it will also introducegithub-markdown.min.cssTo provide a consistent and aesthetically pleasing style. However, as website operators, we often encounter situations where we need to customize the styles of Markdown-rendered content based on brand image, user experience, or specific business requirements.

This article will provide a detailed guide on how to implement custom CSS styles for Markdown rendering in AnQi CMS, completely摆脱default stylegithub-markdown.min.cssLimit, making your content display more distinctive.

Understand the template structure and Markdown rendering mechanism of Anqi CMS.

In 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 "Catalog and Templates for Template Creation", our template files are usually in.htmlsuffixes stored in/templateUnder the directory, while static resources such as CSS, JS, and images are uniformly managed in/public/static/directory. Pages usually have a basic template, such asbase.htmlIt is used to define the overall layout of the website and to introduce global resources.

The document 'How to Properly Use Markdown on AnQi CMS Website and Display Mathematical Formulas and Flowcharts' clearly states that in order to apply the default Markdown style on the web page, we need tobase.htmlAdd the following line of code to the top of the file:

<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 an external CDNgithub-markdown.min.cssto provide default GitHub-style styling for all HTML elements rendered by Markdown. Markdown itself does not contain styling, it simply converts specific marking syntax into standard HTML tags (such as,# 标题will be translated to<h1>,**粗体**will be translated to<strong>Therefore, to customize the Markdown style, essentially it is to define CSS styles for the HTML tags generated by Markdown.

Remove the default Markdown style

The first step in customization is to remove or disable the defaultgithub-markdown.min.css. If you directly enterbase.htmlThe style may be overridden, which may cause some styles not to 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 introductiongithub-markdown.min.cssof<link>.

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 will no longer have the default GitHub style on the page, and will usually be presented with the browser's default HTML element styles.

Create and introduce custom Markdown styles

Next, we will create our own CSS file to define the style 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., to create a new CSS file in the root directory of the/public/static/css/path, for examplecustom-markdown.css.

in the newly createdcustom-markdown.cssIn the file, you can start defining styles for HTML elements rendered from Markdown. The following is a simple example showing how to define styles for 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;
}

After defining the custom style, you need tobase.htmlinclude this new CSS file. At 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" />
{# ... 其他样式或元数据 ... #}

We used here{% system with name='TemplateUrl' %}Label. According to the 'System Tags' document, TemplateUrlYou can obtain the template static file address, which ensures that your CSS files can be loaded correctly, even in multi-site or different deployment environments while maintaining the correct path.

Important reminder:

Markdown content is wrapped by default in AnQi CMS within a container with a specific class or id (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 the Markdown content in a container with a specific class.divfor examplemarkdown-bodyIf 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 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 outsidediv:

<div class="markdown-body">
    {%- archiveDetail articleContent with name="Content" render=true %}
    {{articleContent|safe}}
    {% endarchiveDetail %}
</div>

Please noterender=trueThe parameter explicitly tells the system to perform a Markdown to HTML conversion.If your Markdown editor is enabled, it is usually not necessary to explicitly set this parameter, but it is a good habit to do so for compatibility and clarity.

Test and optimize

After completing the above steps, you need to clear the cache of Anqí CMS (operate 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), and you can check the rendered HTML structure of the Markdown content and adjust CSS styles in real time.This helps you understand how Markdown tags are converted to HTML elements, and accurately locate the style rules that need to be modified.

Iteratively 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.

Frequently Asked Questions (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 you have completely removed the default.github-markdown.min.cssReference, not just overwrite. Next, check if the path to your custom CSS file is correct, as well asbase.htmlto include the file in<link>The label is written correctly. You can use the browser's developer tools network tab to viewcustom-markdown.cssThe file has loaded successfully. If it fails to load, 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.Please try to add a more specific parent selector before your selector, for example.markdown-body h1or add it after the style declaration.!important(Not recommended for abuse, but it can be used for debugging). At the same time, make sure that your Markdown content is indeed wrapped in a container.markdown-bodyclassdivor an appropriate container.)

How do I know which HTML tags Markdown will generate so that I can write CSS specifically?

The most direct and effective method is to write various Markdown syntaxes in a simple Markdown document (such as headings, paragraphs, lists, links, code blocks, tables, etc.), and then view the rendered results of the document in a browser.Use the browser's developer tools (usually open by pressing F12), right-click on an element in the Markdown content, select 'Inspect Element', and you can see the corresponding HTML tag structure of the Markdown syntax.

For example, by checking, you will find:

• # Headingit will generate<h1>
• ## Subheadingit will generate<h2>
• This is a paragraph.it will generate<p>
• * List itemit will generate<ul><li>
• 1. Ordered itemit will generate<ol><li>
• `inline code`it will generate<code>
• `