How the `linebreaks` and `linebreaksbr` filters convert newline characters in multi-line text to HTML's `

`or`
` tag?

When managing content in Anqi CMS, we often encounter a situation: when multi-line text is entered in the background editing box, it is displayed as a single line on the front-end page, or the newline characters are displayed as text directly. This is because browsers default to ignoring single newline characters when rendering HTML (\nIf you want the content to be displayed like it is in the editing box, you need to use the powerful template filter provided by AnQiCMS, especiallylinebreaksandlinebreaksbr.

These filters are practical tools in the AnQiCMS template engine, their function is to convert line breaks in text content into HTML tags that browsers can recognize and render, thereby ensuring that your multi-line text is displayed as expected on the website.

linebreaksbrFilter: The preferred choice for simple line breaks

linebreaksbrThe filter, as the name implies, will replace all line breaks in the text (\n) directly with HTML's<br/>Label. This is very useful for those who need simple line breaks instead of paragraph breaks, such as:

• Address informationWhen you need to display detailed address on the contact page, you may want each address element to be displayed independently, rather than being cramped together.
• Product Features ListIf the product description contains multiple short features, it is desired that each feature occupy a separate line,linebreaksbrit can be put to use.
• poetry or lyricsThese contents usually require strict line-by-line display.

Usage example:

Assuming your backend text content is:

公司名称：AnQiCMS
联系电话：123-4567-8900
公司地址：某某市某某区某某街道123号

In the template, you can use it like thislinebreaksbr:

<div class="contact-info">
    <h3>联系方式</h3>
    <p>{{ system.contact_details|linebreaksbr|safe }}</p>
</div>

After rendering, the browser will display as:

<div class="contact-info">
    <h3>联系方式</h3>
    <p>公司名称：AnQiCMS<br/>联系电话：123-4567-8900<br/>公司地址：某某市某某区某某街道123号</p>
</div>

In this way, each piece of information will occupy a separate line on the page.

It is noteworthy that when using this filter, it is usually necessary to add|safeFilter. This is because AnQiCMS (and many other template engines) for security reasons, by default, will escape the output HTML content, to<to<etc.|safeTell the template engine that this part of the content is safe, no escaping is needed, and it can be parsed directly as HTML. If it is missing|safeyour<br/>Tags may be displayed in plain text form rather than actual line breaks.

linebreaksFilter: A Tool for Semantically Structuring Paragraphs.

withlinebreaksbrCompared tolinebreaksThe filter provides a more semantic processing method, it focuses more on converting multi-line text into structured paragraphs. Specifically:

• It will convert a single newline character to<br/>tags, likelinebreaksbr.
• But more importantly, it will convert two or more consecutive newline characters (usually represented as the start of a new paragraph in a text editor) to HTML.<p>and</p>Paragraph wrapped in tags.

This processing method makeslinebreaksThe filter is very suitable for processing long articles, blog posts, or any text that requires clear paragraph structure. It can better preserve the original structure of your content and make it more visually readable, and it is also more friendly to search engines because it uses semanticized<p>.

Usage example:

Assuming your backend article content is:

这是文章的第一段内容。
它包含一些重要的信息，并且在这里结束。

这是文章的第二段内容。
它与第一段通过空行分隔，理应是独立的段落。

In the template, you can use it like thislinebreaks:

<div class="article-content">
    <h2>{{ article.title }}</h2>
    <div class="main-body">
        {{ article.full_content|linebreaks|safe }}
    </div>
</div>

After rendering, the browser will display as:

<div class="article-content">
    <h2>文章标题</h2>
    <div class="main-body">
        <p>这是文章的第一段内容。<br/>它包含一些重要的信息，并且在这里结束。</p>
        <p>这是文章的第二段内容。<br/>它与第一段通过空行分隔，理应是独立的段落。</p>
    </div>
</div>

Here, the content is correctly divided into two<p>paragraphs, and the line breaks within the paragraph are<br/>represented. Similarly,|safethe filter is also indispensable here.

How to chooselinebreaksandlinebreaksbr?

The choice of filter depends mainly on the semantics and expected display effect of your content:

• If you need is a simple inline line break, not involving explicit paragraph concepts, such as addresses, short sentence lists, or product features, thenlinebreaksbrit is a lighter and more direct choice.
• If you are processing a long article, news content, or any other long text that requires clear paragraph structure and you want to preserve the original intent of the paragraphs, thenlinebreaksProvide more semantically meaningful HTML output, which helps improve the readability and SEO friendliness of the content.

They are all practical tools in AnQiCMS template development, enhancing user experience and content presentation quality.By flexibly using these two filters, you can easily solve the problem of displaying multiline text on web pages, making your content more beautiful and readable on AnQiCMS-driven websites.

Further reading:linenumbersFilter

In addition to handling line breaks, AnQiCMS also provideslinenumbersA filter that can number each line of multi-line text, starting from 1, like "1. ".For example, if you need to display content with line numbers in a code block or some specific text area,{{ code_block|linenumbers|safe }}it can be put to use.

---

Frequently Asked Questions (FAQ)

1. Q: Why did I uselinebreaksorlinebreaksbrFilter, but the page still displays plain text<br/>or<p>Tag, rather than actual line breaks or paragraphs?

   • A:This is usually because you forgot to add at the end of the filter chain|safeThe filter. AnQiCMS to prevent XSS attacks, the default will escape all HTML tags to the corresponding entity characters (such as<to<)|safeThe filter tells the template engine that this part of the content is safe HTML that can be rendered as is without escaping. So, make sure your template code is{{ variable|linebreaksbr|safe }}or{{ variable|linebreaks|safe }}.

2. Q: Do these filters automatically handle Markdown syntax?For example, is the text input to my backend in Markdown format directly convertible to HTML?

   • A:No.linebreaksandlinebreaksbrThe filter focuses solely on converting native line breaks(\nConvert to HTML's<br/>or<p>tags. They do not parse or convert Markdown syntax. If your content is in Markdown format, you