The `urlize` filter can it encode URLs containing special characters (such as `&`, `=`) correctly?

When using AnQi CMS for content operation, we often need to reference external links or email addresses in the articles. To ensure that these links can not only be clicked by users but also maintain the page's neatness and security, AnQi CMS has built-in many practical template filters, whereurlizeFilter is a good helper for handling such needs.

Many friends are using iturlizeWhen they are curious, when the URL contains some special characters, such as&(ampersand) or=These are commonly used for parameter separation, can it correctly encode them to avoid link failure or page rendering errors? Today, let's take a deep dive into it.urlizeThe performance of the filter in this aspect.

urlizeThe basic function of the filter.

Firstly,urlizeThe core task of the filter is very clear: it intelligently scans a piece of text content, automatically identifies strings that match the URL or email address format, and then converts them into clickable HTML<a>Tags. This is very convenient for handling user comments, messages, or any scenario that contains plain text links. For example, if you write a link in an article,欢迎访问我们的官网：https://en.anqicms.comafterurlizeit will be transformed into<a href="https://en.anqicms.com" rel="nofollow">https://en.anqicms.com</a>. By default, the security CMS will also add attributes to these automatically generated links.rel="nofollow"Attributes, which is a good default setting for SEO friendliness.

Encoding handling for special characters:&and=Can it encode correctly?

Return to the special character issue we are concerned about:&and=These characters have special meanings in the HTML environment.&Is the start symbol of HTML entities (such as&), and=In HTML attributes, used to separate keys and values. If a URL is directly included in plain text&or=without proper encoding<a>TagshrefProperties, it may very likely cause the link to break or be incorrectly parsed by the browser.

So,urlizeHow does the filter handle it?

After actual testing and document review, the Aiqi CMSurlizeThe filter performs quite reliably in this regard. It ensures that the generated<a>Tagshrefspecial characters in attributes are correctly URL-encoded. This means, like=It will remain unchanged (because it is a legal character in URL query parameters, but it may be encoded when needed, such as being part of a parameter value), while"(Double quotes) such characters will be converted%22.

For example, if we have a text URL that contains special characters:www.anqicms.com/search?q=安企CMS&category="CMS".{{ "www.anqicms.com/search?q=安企CMS&category=\"CMS\""|urlize|safe }}it generateshrefThe property will be like this:

<a href="http://www.anqicms.com/search?q=%E5%AE%89%E4%BC%81CMS&category=%22CMS%22" rel="nofollow">www.anqicms.com/search?q=安企CMS&category="CMS"</a>

You can see that the Chinese characters in the URL are安企CMSencoded as%E5%AE%89%E4%BC%81CMSwhile"Double quotes are encoded as%22This means that even if the URL contains complex query parameters and special symbols,urlizeThe filter is also responsible for converting them into URL-compliant encoding forms to ensure the validity of the links.

urlizeThe subtle aspects of parameters:trueWithfalse

urlizeThe filter also provides an optional parameter to control the escaping behavior of the displayed link text. You canurlizebehindtrueorfalse.

• urlize:trueWhen this parameter is set totrue,hrefthe attribute will be URL encoded,Linked display textContains HTML special characters (such as)&/</>) will also be encoded as HTML entities.

  {% filter urlize:true|safe %}
  我的URL是 www.anqicms.com/test="test"&key=value
  {% endfilter %}
  

  In the output result ofhref:http://www.anqicms.com/test=%22test%22&key=valueIn the output result oftext of the hyperlink:www.anqicms.com/test="test"&key=value(Note)"变成了",&变成了&)

• urlize:falseThis is the default behavior, or when you explicitly setfalsewhenhrefThe attribute will still be URL-encoded, butLinked display textits original special characters will be retained (no HTML entity encoding will be performed).

  {% filter urlize:false|safe %}
  我的URL是 www.anqicms.com/test="test"&key=value
  {% endfilter %}
  

  In the output result ofhref:http://www.anqicms.com/test=%22test%22&key=valueIn the output result oftext of the hyperlink:www.anqicms.com/test="test"&key=value(Note)"and&Keep it as is

This subtle difference mainly affects the visual presentation of links on the page. Usually, to prevent unexpected rendering of the page,urlize:trueis a safer choice as it ensures that the displayed text is also encoded as HTML entities. But if you want the displayed text of your link to be in its original form,"or&If you have absolute confidence in the content security, thenurlize:falseit may be more in line with your design requirements in certain specific scenarios.

no matter which one you choosetrueOrfalse, the core point that does not change is:urlizeFilterers will be responsible for thehrefproper URL encoding of special characters in properties, ensuring the accuracy of the link.

Summary

Anqi CMS'surlizeFilter is a powerful and intelligent tool that can effectively convert URLs and email addresses from plain text into fully functional HTML links. For common special characters in URLs,&and=，以及其他可能引起问题的字符，urlize都会在生成链接的href属性时进行正确的URL编码，确保链接的可用性和页面的稳定性。同时，通过trueandfalseParameters, you can also flexibly control the display text of the HTML entity encoding of the link to meet different content display needs.

When usingurlizeDon't forget to add when using a filter.|safebecauseurlizeIt will generate HTML code,|safeTell the template engine that this HTML is safe and does not require further escaping.

---

Common Questions (FAQ)

1. urlizeandurlencodeWhat are the differences between filters? urlizeFilters are mainly used in a section ofText.Automatically identify and convert URLs and email addresses to clickable HTML<a>tags. Its task isfind and wraplinks, while also handling the URL encoding of the links themselves.urlencodeFilter is a lower-level tool, used fora single stringURL percent-encoding, usually used when constructing query parameters or fragments of URL paths, to ensure that these strings