How to manually control the Markdown to HTML rendering of the `Content` field in the document?

In content management systems, Markdown is a lightweight markup language that is widely popular for its simplicity and efficiency.AnQiCMS (AnQiCMS) understands the importance of content flexibility to users, and therefore provides flexible mechanisms to handle the Markdown rendering of document content.ContentWhen manually controlling the Markdown to HTML rendering of the field, the system provides intuitive and powerful methods.

Understand the Markdown processing mechanism of AnQi CMS

Firstly, understanding the basic processing method of Markdown content by Anqi CMS is crucial.The system provides a 'Content Settings' option in the 'Global Settings' on the backend, where you can choose whether to enable Markdown editor by default.

• When the Markdown editor is globally enabled:Document'sContentThe field will be displayed as HTML on the front-end page if it contains Markdown formatted content, usuallyIt will be automatically rendered as HTMLThis means that the content you write in Markdown in the background can be presented in a structured HTML format on the website without any additional operation.
• When disabling Markdown editor globally:If you choose to disable the Markdown editor, the system will not process automaticallyContentMarkdown markers within the field. In this case, the front-end page willoutput the original Markdown text directlyand will not convert it to HTML.

However, relying solely on global settings may not always meet the needs of content display.For example, you may want to automatically render Markdown on most pages, but want to display the original Markdown code in specific documents; or vice versa, even if the global setting has disabled Markdown, certain specific content still needs to be rendered as HTML.This is when finer manual control is needed.

Fine control: Through template tags,renderParameters

AnQi CMS provides manual control on the template level with its powerful template tag system,Contentfield rendering capability. The core is to usearchiveDetail/categoryDetailorpageDetailWhen accompanied by a label named 【en】：When accompanied by a label namedrenderThe parameter.

ThisrenderThe parameter accepts a boolean valuetrueorfalse:

• render=true：Force Markdown to HTML rendering.Even if the global setting disables the Markdown editor, when you explicitly specify it in the template tags,render=truethe system will ignore the global setting and force theContentThe Markdown content in the field is parsed and rendered into HTML.
• render=falsePrevent Markdown from being rendered into HTML.On the contrary, even if the global setting has enabled the Markdown editor, when you specify in the template tagrender=falsethe system will block access toContentThe automatic rendering of the field directly outputs the original Markdown text.

In actual use, you would call the content like this in the template file:

{# 强制渲染Markdown内容为HTML，即使全局Markdown编辑器是关闭的 #}
<div>
    {% archiveDetail articleContent with name="Content" render=true %}{{articleContent|safe}}</div>
</div>

{# 阻止Markdown渲染，显示原始Markdown文本，即使全局Markdown编辑器是开启的 #}
<div>
    {% archiveDetail articleContent with name="Content" render=false %}{{articleContent|safe}}</div>
</div>

Please note the critical|safeFilter.No matter whether you force rendering or prevent rendering,ContentThe content of the field may contain or may contain HTML tags.The rendered result of Markdown is always HTML, and if you want to display the original HTML content, you also need to ensure that the browser can correctly parse it.|safeThe role of the filter is to inform the template engine that this content is safe and does not need to be escaped as HTML entities, and can be output directly as HTML. If there is no|safeEven after rendering, the HTML will be displayed in its original text form (such as<p>Hello</p>displayed as<p>Hello</p>) on the page, which is not the effect we want.

Actual operation scenario example

1. Scene one: I want a technical article to display the original Markdown code snippet, but other articles to be rendered normally.

   • Step:Ensure that the Markdown editor is enabled in the "Global Settings" backend (this is the default behavior for most articles). For the article that needs to display the original Markdown, in the corresponding template file (for exampledetail.htmlWithin the parentheses, find the callContentAdd the field whererender=false.

   {# 这部分将显示原始Markdown代码，不会被渲染 #}
   <pre class="language-markdown">
       <code>
           {% archiveDetail techContent with name="Content" render=false %}{{techContent|safe}}
       </code>
   </pre>
   

2. Scenario two: My website uses Markdown globally by default, but the specific "About Us" page requires HTML structure.

   • Step:Disable Markdown editor in the "Global Settings" section. For the "About Us" single page (usually inpage/detail.htmlor custom templates), find the call to itsContentAdd the field whererender=true.

   {# 即使全局Markdown关闭，这里也会将Content内容渲染成HTML #}
   <div class="about-us-content">
       {% pageDetail aboutUsContent with name="Content" render=true %}{{aboutUsContent|safe}}</div>
   </div>
   

By using flexibilityrenderParameters, you can display according to your actual content requirements,ContentExact control over the Markdown rendering of fields, thus achieving a diverse presentation of front-end pages while maintaining the convenience of content management.

---

Common Questions (FAQ)

Q1: If I enable the Markdown editor in the background but do not use it in the template, how will the document content be displayed?renderWhat will happen to the parameter?

A1:If you have enabled the Markdown editor in the background but did not explicitly specify the parameter when calling the field in the templateContentin the templaterenderthe system willdefault to the global settings of the backgroundThis means if yourContentfield contains Markdown syntax, it will be automatically rendered into HTML and displayed on the frontend page.renderThe existence of the parameter is to provide finer-grained control, allowing you to override global behavior in specific situations.

Q2: Why is my Markdown content displayed as raw text on the page instead of rendered HTML, even though I have setrender=true?

A2:The most common reason is that youare missing|safeFilter). Whenrender=trueWhen, the system will convert Markdown to an HTML string. If this HTML string has not been|safeThe processing of the filter, for security reasons, the template engine will escape</>the HTML special characters to</>The browser treats it as plain text instead of parsing it as an HTML structure. Make sure your template code looks like:{{yourContentVariable|safe}}.

Q3: BesidesarchiveDetailWhat other tags are supported?renderHow to control Markdown rendering parameters?

A3:ExceptarchiveDetailTags are used for document content such as articles/products, in addition to managing single pages and category details in Aigle CMS, such aspageDetail[Used for single-page content] andcategoryDetail[Used for category descriptions or content], also supportsrenderparameters to control itsContentfield (orDescriptionThe Markdown rendering behavior when the field contains Markdown.This maintains consistency across different content types, allowing you to flexibly manage the display methods of various types of content.