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

In content management systems, Markdown, as a lightweight markup language, is widely popular for its simplicity and efficiency.AnQiCMS (AnQiCMS) fully understands the importance of content flexibility to users, and therefore provides a flexible mechanism to handle the Markdown rendering of document content.When you need to refer to the document ofContentWhen manually controlling the Markdown to HTML rendering, the system provides an intuitive and powerful method.

Understand the Markdown processing mechanism of AnQi CMS

Firstly, understanding how Anqi CMS handles Markdown content is crucial.The system provides a "Content Settings" option in the "Global Settings" in the background, where you can choose whether to enable Markdown editor by default.

• When the Markdown editor is enabled globally:The document'sContentIf a field contains Markdown format content, when displayed on the front-end page, the system will usuallyrender it automatically as HTMLThis means that the content you write in Markdown in the background can be presented in a structured HTML form on the website without any additional operation.
• When the Markdown editor is globally disabled:If you choose to disable the Markdown editor, the system will not process automaticallyContentMarkdown markup within a 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 sometimes does not meet the needs of all content display.For example, you may want to automatically render Markdown on most pages, but in certain documents, you may want to display the original Markdown code;Or conversely, even if Markdown is globally disabled, certain specific content still needs to be rendered as HTML.This is when a finer manual control is needed.

Fine control: through template tagsrenderParameter

AnQi CMS provides you with the ability to manually control at the template level through its powerful template tag systemContentthe ability to render fields. The core is to usearchiveDetail/categoryDetailorpageDetailWhen content detail tags are accompanied by a namedrenderthe parameter.

ThisrenderThe parameter accepts a boolean valuetrueorfalse:

• render=true: It is mandatory to render Markdown to HTML.Even if the global settings disable the Markdown editor, when you explicitly specify in the template tagrender=truethe system will ignore the global settings and force toContentThe Markdown content in the field is parsed and rendered into HTML.
• render=false: Prevent Markdown from rendering to HTML.On the contrary, even if the global settings have enabled the Markdown editor, when you specify in the template tagrender=falsethe system will block access toContentField auto-rendering, output the original Markdown text directly.

In actual use, you will 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.Whether you are forcing rendering or blocking rendering,ContentThe content of the field may contain or may contain HTML tags.The result of Markdown rendering is necessarily HTML, and if you want to display the original HTML content, you also need to ensure that the browser can correctly parse it.|safeThe filter's role 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 none|safeThis is even rendered as raw text in the HTML (like<p>Hello</p>displayed as<p>Hello</p>) displayed on the page, which is not the effect we want.

Actual operation scenario example

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

   • Steps:Make sure the Markdown editor is enabled in the background "Global Settings" (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.htmlIn the middle, 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 globally defaults not to use Markdown, but the specific "About Us" page needs HTML structure.

   • Steps:Disable Markdown editor in the background "Global Settings". 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 flexible applicationrenderParameter, you can adjust according to the actual content display requirements, toContentThe field's Markdown rendering is precisely controlled to maintain content management convenience while realizing the diversity of front-end page presentation.

Frequently Asked Questions (FAQ)

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

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

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

A2:The most common reason is that youhave missed out on|safeFilter. Whenrender=trueWhen, the system will convert Markdown to an HTML string. If this HTML string has not been|safeThe filter process, the template engine, for security reasons, will escape the special HTML characters in</>etc.</>This causes the browser to display it as plain text, rather than parsing it as HTML. Make sure your template code looks like this:{{yourContentVariable|safe}}.

Q3: BesidesarchiveDetailWhich tags support this?renderParameters to control Markdown rendering?

A3:exceptarchiveDetailTags used for document content such as articles/products, in Anqi CMS, tags are used to manage single pages and category details, such aspageDetail(Used for single page content) andcategoryDetail(Used for category description or content), also supportsrenderparameters to control itsContentfield (orDescriptionThe Markdown rendering behavior when a field contains Markdown.This maintains consistency across different content types, allowing you to flexibly manage the display of various content.