In website content display, we often encounter such needs: multi-line text edited in the background can be automatically converted to paragraphs with HTML tags on the front-end page<p>or newline tag<br>The format, rather than being simply crammed together into a long string of text.AnQiCMS provides a flexible and powerful method to solve this problem, whether it is through the built-in editor features or by using template filters for fine control, it can be easily achieved.

One, use the content editor to enable automatic conversion

When you create or edit articles, product details, single pages, or category content through the AnQiCMS backend, you will usually use the content editor.These editors (including rich text editors and Markdown editors) inherently have the ability to automatically convert the line breaks you enter into the corresponding HTML tags.

If you have enabled the Markdown editor in the background (you can do so in theGlobal settings -> Content settingsFind and enable it, then the newline characters you enter, especially two consecutive newlines, will be automatically recognized and rendered as HTML paragraph tags<p>. And a single newline character may be converted to<br/>. This means that as long as you are in the background content field (for example文档内容/页面内容or分类内容Normal segmentation and line breaks are performed, when AnQiCMS displays this content in the front-end template, it will intelligently convert it to HTML format with<p>or<br/>tags.

For example, when calling document content in your template, you will usually use something like{% archiveDetail articleContent with name="Content" %}{{articleContent|safe}}</div>tags. If the content is entered through a Markdown editor,articleContentThe variable will automatically include the converted HTML structure. Among which the|safeThe filter is crucial, it tells the template engine that this content is safe HTML, does not require additional escaping, so<p>and<br/>it can be rendered normally in the browser.

Second, use template filters for fine control

In addition to the automatic conversion of the editor, AnQiCMS also provides powerful template filters that allow you to perform more detailed HTML formatting conversions on multiline plain text content.This is particularly useful when handling plain text data obtained directly from a custom multi-line text field without going through a content editor.

1.linebreaksFilter: Smart paragraph and line break processing

When you want to convert the paragraph format of plain text into standard HTML paragraph tags<p>Keep the line breaks within the text, please.linebreaksThe filter is your ideal choice. It works in a way similar to many blogging systems: it recognizes consecutive two newline characters (i.e., blank lines) as a paragraph end and uses<p>...</p>Enclosed in tags. While individual line breaks are converted to<br/>.

This method is very suitable for converting user input, unformatted multi-line comments, product descriptions, or service descriptions into HTML format with paragraph structure and retained internal line breaks.

For example, if you have a custom multi-line text field namedproduct_descriptionyou can call and handle it in the template like this:

{# 假设 product.product_description 变量中包含多行纯文本内容 #}
<div class="product-description">
    {{ product.product_description|linebreaks|safe }}
</div>

Remember to do this here|safeThe filter is also indispensable, it ensures thatlinebreaksThe HTML tags generated by the filter can be correctly parsed and displayed by the browser.

2.linebreaksbrFilter: Simple line break conversion

If your requirement is simpler, you just want to replace each newline in plain text with the HTML<br/>tag without needing the paragraph tag<p>thenlinebreaksbrThe filter will be more direct and lightweight. It will not judge blank lines and paragraphs, but insert one when it encounters a newline.<br/>.

This method is suitable for scenarios where you need to keep the text compactly aligned but also want to have a simple line break between each natural paragraph or list item, such as address information, contact list, and brief points of explanation, etc.

For example, if you have a custom multi-line text field in the contact information settings to display the company address, you can call it like this:

{# 假设 contact.address_lines 变量中包含多行纯文本地址信息 #}
<address>
    {{ contact.address_lines|linebreaksbr|safe }}
</address>

Similarly,|safeThe filter ensures<br/>The key to correct rendering of labels.

How to choose a way that suits you?

  • For the main content area (such as article details, main body)：Use the built-in AnQiCMS backend editor function first.If you are accustomed to Markdown, enabling the Markdown editor will bring a more convenient writing experience and automatic HTML conversion.
  • For custom multi-line text fields (such as product highlights, brief descriptions)If this text content requires strong paragraph sense and structure,linebreaksThe filter would be a better choice. It can convert multiple natural paragraphs into HTML.<p>Labels, make text more readable.
  • For simply separating each line of content (such as addresses, list items): If you don't need strict paragraph division, but just want each line to occupy a line by itself,linebreaksbrthe filter is more suitable, as it can convert each newline character to<br/>.

AnQiCMS through built-in editor features and flexible template filters, allows you to have a variety of choices when displaying multiline text content, ensuring that your website content is both aesthetically pleasing and semantically standard.

Frequently Asked Questions (FAQ)

Q1: Why did I uselinebreaksorlinebreaksbrFilter, but what is displayed on the page is<p>...</p>or<br/>Such original HTML tags, not actual paragraphs and line breaks?

A1:This is usually because you forgot to add after the filter.|safeFilter. The AnQiCMS template engine, for security reasons, defaults to escaping all output content to HTML, to<to&lt;etc. WhenlinebreaksorlinebreaksbrGenerate HTML tags after, if not|safeTell the template engine that these tags are safe, they will be escaped and displayed as original text. The correct way to use it is{{ 你的变量|linebreaks|safe }}or{{ 你的变量|linebreaksbr|safe }}.

Q2: I have already formatted the multi-line text in the background content editor, and I still need to use it in the templatelinebreaksfilter?

A2:Generally, it is not necessary. The rich text editor or Markdown editor on the AnQiCMS backend has already converted your formatting (including paragraphs and line breaks) into standard HTML format when saving content.When you call this content directly in the template (for example{{ archive.Content|safe }}when it will be displayed directly as formatted HTML.linebreaksorlinebreaksbrThe filter is mainly used to process those multi-line "plain text" contents that have not been processed by the editor, such as text input through custom fields.

Q3:linebreaksandlinebreaksbrWhat are the specific differences between the filters, and how should I choose?

A3:The main difference between them lies in the way they handle newline characters:

  • linebreaksFilter:More intelligent and semantic. It will recognize consecutive two newline characters (representing an empty line) as a paragraph end, and<p>...</p>Text enclosed by tags. A single newline character in the text will be converted to<br/>Tags. This is suitable for text that requires clear paragraph structure.
  • linebreaksbrFilter:It is more direct and simple. It will replace each newline character (whether single or consecutive) without discrimination, replacing it with HTML's<br/>tags without generating any<p>Tags. This is applicable to scenarios where only simple line breaks are needed, without strict paragraph division, such as addresses, list items, or poetry.

Choose which one depends on the HTML structure and visual effects you want the text to display. If you want the browser to handle paragraph spacing and maintain the semantic segmentation of the text, chooselinebreaksIf you just want to start each line of text on a new line, selectlinebreaksbr.