From 0f8a2bc26c78bd6220b94723b362e24806042069 Mon Sep 17 00:00:00 2001
From: SeverAnna <a.koroleva@adguard.com>
Date: Thu, 11 Jun 2026 08:39:01 +0300
Subject: [PATCH 1/2] Add :contains() and clean up attributes

Introduce the recommended :contains() pseudo-class with examples

Consolidate the deprecation notice for legacy special attributes into a single paragraph and remove the repeated caution blocks
---
 .../ad-filtering/create-own-filters.md        | 37 ++++++++-----------
 1 file changed, 16 insertions(+), 21 deletions(-)

diff --git a/docs/general/ad-filtering/create-own-filters.md b/docs/general/ad-filtering/create-own-filters.md
index 1ead84171ab..23b9136d590 100644
--- a/docs/general/ad-filtering/create-own-filters.md
+++ b/docs/general/ad-filtering/create-own-filters.md
@@ -4399,16 +4399,29 @@ This rule removes all `div` elements with the attribute `some_attribute` on `exa
 
 ### Special attributes {#html-filtering-rules--special-attributes}
 
-In addition to usual attributes, which value is every element checked for, there is a set of special attributes that change the way a rule works. Below there is a list of these attributes:
+In addition to checking standard HTML attributes, you can filter elements based on their inner text or script content.
 
-#### `tag-content`
+### `:contains()`
+
+The recommended way to filter elements by their content is using the `:contains()` pseudo-class. It allows you to target elements based on the actual text or script variables they contain, supporting both plain text strings and regular expressions.
+
+**Examples:**
+
+```example.com$$script:contains(Adverts)
+example.com$$div:contains("Sponsored by")
+example.com$$script:contains(/ad_system_\d+/)
+```
+
+The first rule removes any `<script>` tag containing the word Adverts. The second targets any `<div>` containing the phrase Sponsored by. The third rule utilizes a regular expression to match dynamic script patterns.
 
 :::caution Deprecation notice
 
-This special attribute may become unsupported in the future. Prefer using the `:contains()` pseudo-class where it is available.
+The attributes listed below are legacy features kept only for backward compatibility. They may become unsupported in future updates. Prefer using the `:contains()` pseudo-class where it is available.
 
 :::
 
+#### `tag-content`
+
 This is the most frequently used special attribute. It limits selection with those elements whose innerHTML code contains the specified substring.
 
 You must use `""` to escape `"`, for instance:
@@ -4438,12 +4451,6 @@ This limitation does not apply to AdGuard Browser Extension v5.3 or later.
 
 #### `wildcard`
 
-:::caution Deprecation notice
-
-This special attribute may become unsupported in the future. Prefer using the `:contains()` pseudo-class where it is available.
-
-:::
-
 This special attribute works almost like `tag-content` and allows you to check the innerHTML code of the document. Rule will check if HTML code of the element fits the [search pattern](https://en.wikipedia.org/wiki/Glob_(programming)).
 
 You must use `""` to escape `"`, for instance:
@@ -4464,12 +4471,6 @@ This limitation does not apply to AdGuard Browser Extension v5.3 or later.
 
 #### `max-length`
 
-:::caution Deprecation notice
-
-This special attribute may become unsupported in the future. Prefer using the `:contains()` pseudo-class with a regular expression where it is available.
-
-:::
-
 Specifies the maximum length for content of HTML element. If this parameter is set and the content length exceeds the value, a rule does not apply to the element.
 
 **Default value**
@@ -4494,12 +4495,6 @@ This limitation does not apply to AdGuard Browser Extension v5.3 or later.
 
 #### `min-length`
 
-:::caution Deprecation notice
-
-This special attribute may become unsupported in the future. Prefer using the `:contains()` pseudo-class with a regular expression where it is available.
-
-:::
-
 Specifies the minimum length for content of HTML element. If this parameter is set and the content length is less than preset value, a rule does not apply to the element.
 
 For example:

From 5fb5d320d41f653c45fe0eba53363894033b5482 Mon Sep 17 00:00:00 2001
From: SeverAnna <a.koroleva@adguard.com>
Date: Thu, 11 Jun 2026 09:02:00 +0300
Subject: [PATCH 2/2] fix heading

---
 docs/general/ad-filtering/create-own-filters.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/general/ad-filtering/create-own-filters.md b/docs/general/ad-filtering/create-own-filters.md
index 23b9136d590..bf10ef43ac5 100644
--- a/docs/general/ad-filtering/create-own-filters.md
+++ b/docs/general/ad-filtering/create-own-filters.md
@@ -4401,7 +4401,7 @@ This rule removes all `div` elements with the attribute `some_attribute` on `exa
 
 In addition to checking standard HTML attributes, you can filter elements based on their inner text or script content.
 
-### `:contains()`
+#### `:contains()`
 
 The recommended way to filter elements by their content is using the `:contains()` pseudo-class. It allows you to target elements based on the actual text or script variables they contain, supporting both plain text strings and regular expressions.