-
-
Notifications
You must be signed in to change notification settings - Fork 191
Static filter syntax
uBlock Origin supports Adblock Plus ("ABP") filter syntax, so you can refer to existing filter syntax documentation from Adblock Plus web site.
However uBlock Origin does not support some very specific cases, and also adds its own extensions to ABP filter syntax (which at time of writing are not recognized by ABP).
document for exception filters (those prefixed with @@):
Not supported. The purpose of the document option when used with an exception filter is to disable uBlock Origin completely. The purpose of the document option in static exception filters is mostly for the sake of "acceptable ads" support, which uBlock Origin does not support.
The reason it is not supported is to be sure that users explicitly disable uBlock Origin themselves if they wish (through whitelisting), not having some external filter list decide for them.
uBlock Origin extends Adblock Plus filter syntax.
uBlock Origin can also parse HOSTS file-like resources. However, this creates an ambiguity with ABP filter syntax, which is pattern-based. For exemple, consider the following filter entry:
example.com
ABP filter syntax dictates that this is interpreted as "block network requests which URL contains example.com at any position". However if the entry comes from a HOSTS file, the interpretation must be "block network requests to the site example.com".
So in uBlock Origin, any entry which can be read as a valid hostname, will be assumed to be a HOSTS file entry. If ever you want such filter to be parsed as an ABP filter, just add a wildcard at the end:
example.com*
The wildcard character * can be used to apply a filter to all URLs. This is not recommended though, unless you further narrow the filter using filter options. Examples:
-
*$third-party: block all 3rd-party network requests. -
*$script,domain=example.com: block all network requests to fetch script resources fromexample.com.
Usually, it is far more convenient to use dynamic filtering rules in lieu of such generic static filters.
For the Adblock Plus like wildcard character *, uBlock Origin uses /* instead. This is due to uBlocks ability to read HOSTS files where a filter like @@*arrow.gif is a valid hostname. So in this case use @@/*arrow.gif instead. The first filter will allow http://some-arrow.gif while the second filter will allow http://anydomain.com/some-arrow.gif See #997 for details.
document for block filters:
This will cause web pages which match the filter to be subjected to strict blocking.
first-party:
This is equivalent to ~third-party. Provided strictly for convenience (0.9.9.0).
important:
The filter option important means to ignore all exception filters (those prefixed with @@).
It applies only to network block filters. The important option will allow you to block with 100% certainty specific network requests.
Example: ||google-analytics.com^$important,third-party will block all network requests to google-analytics.com, disregarding any existing network exception filters. Another example: ||twitter.com^$important,third-party. Etc.
inline-script:
To specifically disable inline script tags in a main page: ||example.com^$inline-script.
Entity-based cosmetic filters: Filters which are to be applied to a specific entity:
google.*###tads.c
An entity is defined as follow: a formal domain name with the Public Suffix part replaced by a wildcard.
Examples: google.* will apply to all similar Google domain names: google.com, google.com.br, google.ca, google.co.uk, etc. Another example: facebook.* will apply to all similar Facebook domain names: facebook.com, facebook.net.
Since the base domain name is used to derive the name of the "entity", google.evil.biz would not match google.*.
script:contains(...):
uBlock Origin supports a special cosmetic filter which purpose is to prevent the execution of specific inline script tags in a main HTML document. See "Inline script tag filtering" for further documentation.