How to embed custom HTML code in the Markdown content of Anqi CMS without escaping?

As an experienced website operator familiar with Anqi CMS, I am well aware of the importance of flexibility and control in the content creation process for presenting high-quality content.Especially when it is necessary to seamlessly integrate custom HTML code into Markdown content, mastering the correct approach is indispensable.AnQiCMS as an enterprise-level content management system has achieved a good balance between content rendering and security.Next, I will introduce how to embed custom HTML code in the Markdown content of AnQiCMS without being escaped.

In AnQiCMS, content creation is usually done through the Markdown editor.Markdown's concise syntax makes writing articles efficient, but sometimes to achieve specific layouts, interactive effects, or embed third-party services, we may need to directly insert HTML code into the Markdown content.However, for security reasons, AnQiCMS defaults to escaping the HTML content output by the page.This means that you have written in Markdown<p>这是一个自定义段落</p>May be displayed on the page in a literal sense<p>这是一个自定义段落</p>Instead of an actual paragraph element.

To solve this problem, the core lies in understanding the template rendering mechanism and security strategy of AnQiCMS.AnQiCMS's template engine is similar to Django template, which automatically escapes HTML tags when outputting variables to prevent cross-site scripting attacks (XSS).This mechanism although enhances the security of the website, but also limits the customization of content display.To achieve the rendering of custom HTML without sacrificing security, AnQiCMS providessafefilter.safeThe filter explicitly informs the template engine that the content it processes is reviewed and safe HTML, no additional escaping operations are required.

You can directly insert custom HTML code in the AnQiCMS Markdown editor. This means that whether it is simple<div>Tags, inline styles, or more complex HTML structures can be directly written into your Markdown content.The system will store these HTML codes along with the Markdown text.When the page is requested and rendered, this embedded HTML will become part of the Markdown content, waiting to be processed by the template engine.

Implement the key steps to customize HTML that is not escaped, focused in your template file:

You need to make sure that you have enabled the Markdown editor by further entering the "Content Settings" option under the "Global Settings" in the AnQiCMS backend.This is the basis for you to write content in Markdown format.

Next, when you are editing content, whether it is writing documents, configuring category descriptions, or creating single-page content, you can directly embed the required custom HTML code in the Markdown editor. For example, if you want to add a custom information box with a specific background color and button to an article, you can write it like this:

这是一个常规的Markdown段落。

<div style="background-color: #e0f7fa; padding: 15px; border-radius: 8px; border: 1px solid #b2ebf2;">
  <h3 style="color: #00796b;">自定义信息提示</h3>
  <p>您可以在这里放置任何HTML内容，例如<b>加粗文本</b>或链接：<a href="https://en.anqicms.com" target="_blank">访问AnQiCMS</a>。</p>
  <button style="background-color: #00bcd4; color: white; padding: 10px 15px; border: none; border-radius: 5px; cursor: pointer;" onclick="alert('自定义按钮被点击！')">点击此处</button>
</div>

这是另一个Markdown段落，紧随自定义HTML之后。

Finally, in your template file (such as the one used to display article details'archive/detail.html, or single page details'page/detail.htmletc.), when you call stored Markdown content (usuallyContentThe variable when using the|safeFilter. This is the key to ensure that the embedded HTML code can be correctly parsed and rendered by the browser. Here is an example of calling the document content in a template.

<article class="content-area">
    <h1>{{ archiveDetail with name="Title" }}</h1>
    <div class="post-meta">
        <span>发布日期: {{ archiveDetail with name="CreatedTime" format="2006-01-02" }}</span>
        <span>浏览量: {{ archiveDetail with name="Views" }}</span>
    </div>
    <div class="article-body markdown-rendered">
        {# 关键步骤：使用 |safe 过滤器防止HTML转义 #}
        {% archiveDetail articleContent with name="Content" %}
        {{ articleContent|safe }}
    </div>
</article>

In the above example,{{ articleContent|safe }}Ensured that all HTML code embedded in the Markdown editor, including its style and JavaScript events, will be rendered as expected on the web page and not escaped into plain text. For categorized content (categoryContent) or single page content (pageContent), should also be processed in the same way.

Please pay close attention to,safeThe filter gives you the power to render any HTML on the page, but it also brings potential security risks. When you usesafeWhen using a filter, you are explicitly telling the system that you trust the content in the variable to be safe HTML and that it does not need to be escaped. If malicious HTML or JavaScript code is introduced through user input or other untrusted sources and is not filteredsafeFiltering can lead to cross-site scripting attacks (XSS), which can harm the website and user data security. Therefore, caution should be exercised in any scenario where user content is allowed to be submitted or external data is imported.safeFilter and ensure that the content source is reliable or has undergone strict security review.

Frequently Asked Questions

Ask: Why do I write HTML directly in Markdown, but the page displays code instead of rendering effects? Answer: This is AnQiCMS to enhance website security, the default is to escape HTML tags in the output content.If you want the embedded HTML code to be rendered by the browser instead of displaying it as code itself, you need to use the corresponding variable in the template file.|safeFilter and explicitly inform the template engine that this content is safe HTML.

Question: Use|safeWhat are the security risks of the filter? Yes,|safeThe filter indicates that the template engine should skip HTML escaping and render the content directly.This means that if the rendered content contains malicious or unreviewed HTML/JavaScript code, this code will be executed in the user's browser, which may lead to cross-site scripting attacks (XSS), and consequently, steal user information or disrupt page functionality.Therefore, in using|safeMake sure you trust the content source completely.

Question: Besides,|safe，Can AnQiCMS have other methods to prevent HTML from being escaped? Answer: In AnQiCMS template engine,|safeThe filter is the standard and recommended way to process the content of a single variable without escaping. Although template engines usually also support global{% autoescape off %}and{% autoescape on %}The tag is used to control the escape behavior of a specific area, but when rendering content, it is used for specific content variables.|safeIt is usually more accurate and secure to control, as it only acts on the data you specify.