What are the differences between the `linebreaks` and `linebreaksbr` filters in handling text line breaks?

In AnQi CMS template development, handling newline characters in text content is a common requirement.Sometimes we want to display the text entered by the user with natural line breaks in a structured paragraph form, and sometimes we only want to simply convert each line break into an HTML line break tag. At this point,linebreaksandlinebreaksbrThese two filters come into play. Although they can both handle line breaks, the resulting HTML structures and semantics are quite different in actual applications.

linebreaksFilter: Generate structured paragraphs for text

linebreaksThe filter is intended to convert newline characters in plain text to HTML paragraph tags (<p>) and line break tags (<br/>Therefore, it presents a more semantic structure on the web.

When we have a piece of text entered by a user or extracted from a database, which contains multiple lines of content and which can be logically considered as independent paragraphs, linebreaksIt is very applicable. It treats continuous lines (separated by a single newline) as inline breaks within the same paragraph and uses<br/>It breaks the tag apart; when two consecutive newline characters are encountered, it treats them as the start of a new paragraph and separates the text before and after<p>tags.

Description of the working principle:

• Double newline characters (\n\n)It will be converted into<p>and</p>Tags to define a new paragraph.
• A single newline character (\n)(If it does not constitute a new paragraph) will be converted to)<br/>Tags to implement inline line breaks.

Application scenarios:

• Display of blog post content
• Text that needs to be segmented in the product detailed description
• Comments submitted by users, hoping to automatically generate paragraph structure
• Any scenario where natural line breaks need to be converted to semantic paragraphs

Example code (from Anqi CMS document):

{{ archive.Description|linebreaks|safe }}

Possible HTML output:Assumearchive.DescriptionThe content is:

这是一个简单的文本。

这也是一个段落。
对吗？

是的！

ThenlinebreaksThe generated HTML will be:

<p>这是一个简单的文本。</p>
<p>这也是一个段落。<br />对吗？</p>
<p>是的！</p>

As can be seen, double line breaks generate new lines<p>Tags, while a single newline generates within a paragraph<br/>.

linebreaksbrFilter: Simple inline line breaks

withlinebreaksdifferent,linebreaksbrThe filter is more direct and simple. It will only replace each newline in the text with\nAll are uniformly converted to HTML line break tags(<br/>), without adding any<p>.

This means it does not attempt to identify paragraph structure and will not use the text in<p>Enclosed in tags. Whether it is one or multiple consecutive line breaks, they are ultimately displayed as a series of lines on the page.<br/>.

Description of the working principle:

• All line breaks (\n)are directly converted to<br/>.
• without adding any<p>Tag.

Application scenarios:

• Display of address information, for example:

  
  安企科技有限公司
  中国广东省广州市天河区
  某某街道某某号
  

• Display of poetry or lyrics, strictly maintaining the independence of each line
• Fine line breaks within each list item in the list
• Any scene that does not require paragraph semantics, just needs to be forced to break lines.

Example code (from Anqi CMS document):

{{ archive.Description|linebreaksbr|safe }}

Possible HTML output:Used withlinebreakssamearchive.DescriptionContent:

这是一个简单的文本。

这也是一个段落。
对吗？

是的！

ThenlinebreaksbrThe generated HTML will be:

这是一个简单的文本。<br /><br />这也是一个段落。<br />对吗？<br /><br />是的！

All newline characters are simply and brutally replaced with<br/>, there is no<p>tag wrapping.

The core distinction and choice path.

• Semantic and structure: linebreaksGenerate with meaning.<p>Tags, more suitable for representing paragraphed text content, and more friendly to SEO.linebreaksbrThen only generate.<br/>Lacks paragraph semantics, it is more suitable to implement simple forced line breaks within existing block-level elements.
• CSS style: <p>is a block-level element, it has default margins (margin) and other styles, which are easy to control with CSS.<br/>It is an inline element, used only for line breaks, it does not introduce additional layout space, and its style control granularity is small.
• Output Result: linebreaksThe output may include<p>and<br/>Two types of tags, whereaslinebreaksbrThe output only includes<br/>.

Choose which filter to use, depending on the structure and style of text you want to display on the web page. If you need structured paragraphs and want to make use of<p>The semantic and style control ability of the tag, thenlinebreaksis a better choice; if it is just a simple inline break, and you do not want to introduce the semantic and extra style of paragraphs,linebreaksbrthen it is more direct and lightweight.

Frequently Asked Questions (FAQ)

1. Why did I uselinebreaksorlinebreaksbrFilter, but the text displayed on the page still does not have line breaks, or the HTML tags are displayed directly?This is usually because you forgot to add at the end of the filter chain.|safeThe filter. AnqiCMS (and many other template engines) to prevent XSS attacks, defaults to escaping all output HTML content. WhenlinebreaksorlinebreaksbrGenerated<p>or<br/>the tag, if not added|safe, these tags will be escaped as<p>or<br/>, the browser will display it as plain text instead of parsing it as an HTML element. Therefore, the correct usage is{{ archive.Description|linebreaks|safe }}.

2.linebreaksandlinebreaksbrWhat is different when handling consecutive blank lines? linebreaksbrIt will simply convert each newline (including newline characters between consecutive blank lines) to<br/>. This means that if there are two consecutive blank lines, it will generate two<br/>tags. AndlinebreaksIt will handle more intelligently: If two consecutive newline characters separate two different logical paragraphs, it will generate an independent one for each paragraph<p>Label. If an empty line appears within a paragraph, such as文本A\n\n文本B,linebreaksit will generate `

Text A</