When building a website with AnQiCMS, we often need to display multi-line text, such as article content, product feature descriptions, code snippets, and even comments.How to properly implement line breaks for this multiline text on the page, and further add line numbers to certain specific content (such as code), is the key to improving reading experience.Luckyly, AnQiCMS's powerful template engine provides a very convenient solution, and we can easily implement these features by using built-in filters.

Understanding multi-line text in AnQiCMS

In the AnQiCMS backend, when you enter multiline text in the content editor (such as in the "Publish Document" interface, or in the "Multiline Text" field created in a custom content model) and press the Enter key, the system will store it as containing a line break (\nThe plain text. However, standard HTML renders multiple consecutive spaces, tabs, and new lines as a single space.This means that if you output unprocessed text directly in the template, the browser will not display the line breaks you enter in the background.

For example, if you enter in the background:

这是第一行。
这是第二行。

这是第四行（第三行为空行）。

Use it directly in the template:{{ archive.Content }}The output, the browser will probably only display as:这是第一行。 这是第二行。 这是第四行（第三行为空行）。

To solve this problem, AnQiCMS provides a special filter to convert the newline characters in the text to the HTML line break tags that browsers can recognize.

Implement text line break processing

The AnQiCMS template provides two commonly used filters for handling the line break requirements of multi-line text, each with its own focus, and can be flexibly selected according to the actual situation.

1. Basic newline: UselinebreaksbrFilter

linebreaksbrThe filter is the most direct way to handle newlines. Its role is to replace each independent newline in the text with\nsimply to the HTML's<br/>Label. This is very suitable for those who only want to achieve the natural vertical separation of text, without forming a strict HTML paragraph structure, such as some brief descriptions, list items, or address information.

The method of use is very intuitive, you just need to add it after the variable you need to process|linebreaksbrThe filter can be used. Since this filter generates HTML tags, in order for the browser to correctly parse and display these tags, you also need to add it at the end of the filter chain.|safefilter.

{# 假设有一个多行文本变量 `item.Description` #}
<div>
    {{ item.Description | linebreaksbr | safe }}
</div>

{# 如果是文档内容字段，且后台未开启Markdown处理 #}
<article>
    <h1>{{ archive.Title }}</h1>
    <div>
        {{ archive.Content | linebreaksbr | safe }}
    </div>
</article>

After such processing, every line of text you input in the background will be displayed independently on the front-end page, achieving clear line breaks.

2. Paragraph-style line breaks: uselinebreaksFilter

If your need is more inclined towards structured paragraph display,linebreaksthe filter will be a better choice. It will not only replace single line breaks with<br/>Labels will also replace consecutive two or more newline characters (usually representing a blank line) with HTML's<p>and</p>Label. This helps to automatically organize long text content into paragraphs that conform to HTML semantics, which is particularly suitable for content that requires good reading structure, such as article text and product descriptions.

withlinebreaksbrsimilar,linebreaksThe filter also needs to be with|safeThe filter is used in conjunction to ensure that the generated HTML tags can be correctly rendered by the browser.

{# 假设有一个多行文本变量 `longText` #}
<section>
    {{ longText | linebreaks | safe }}
</section>

{# 如果是文档内容字段，且后台未开启Markdown处理 #}
<article>
    <h1>{{ archive.Title }}</h1>
    <div class="article-content">
        {{ archive.Content | linebreaks | safe }}
    </div>
</article>

UselinebreaksAfter the filter, your multiline text will be presented in a more standardized paragraph format, enhancing the readability and page structure.

Implement line number display

For scenarios that require line numbering, such as displaying code examples, log outputs, or detailed step lists, AnQiCMS provideslinenumbersA filter that automatically adds line number prefixes to each line of text, the default format is1./2.etc.

linenumbersFilters are usually used in conjunction with other line break filters to ensure that line numbers are correctly matched with each line of content. Similarly, since it generates HTML structure (for example<pre>and<code>Labels, as well as line numbers), you still need to add|safeFilters to ensure that the browser correctly parses.

{# 假设有一个代码片段存储在 `archive.CodeSnippet` 自定义字段中 #}
<pre class="code-block">
    <code>{{ archive.CodeSnippet | linenumbers | safe }}</code>
</pre>

{# 也可以结合换行过滤器，确保文本在添加行号前已经有正确的换行结构 #}
<div class="log-output">
    {{ archive.LogContent | linebreaksbr | linenumbers | safe }}
</div>

BylinenumbersFilter, you can make those multi-line plain text content come alive, convenient for readers to track and refer to specific lines.

Considering the actual application scenarios

  • Content and Markdown:AnQiCMS supports enabling the Markdown editor to write article content. If your content (such asarchive.ContentIt is written through a Markdown editor, then Markdown itself will handle the line breaks and paragraph structure of the text and convert it to HTML. In this case, you can directly uselinebreaksorlinebreaksbrThe filter may not be necessary, and it may even produce unintended effects. However,linenumbersThe filter can still number the plain text content (i.e., visible text lines) converted from Markdown, which may be useful in certain special layouts.
  • code snippet: We recommend creating a special "Multi" in the content model for cases where code needs to be displayed on the website