title=Writing Adblock Plus filters

{{s1 Current Adblock Plus versions allow you to "tweak" your filters in many different ways. This document explains the choices that you have and how they can be used.}}

{{s2 Disclaimer: All filter examples given here are really only examples and are not meant to be used.}}

{{s3 Introduction to Adblock Plus filters}}

{{s4 The options described in this section should be enough for users who have to create a filter occasionally.}}

{{s5 Basic filter rules}}

{{s6 The most trivial filter you can define is of course the address of banner you want to block. However, often this address changes every time you open a page. For example it could be http://example.com/ads/banner123.gif where 123 is a random number. Here blocking the complete address won't help you, you need a more general filter — like http://example.com/ads/banner*.gif. Or maybe even http://example.com/ads/*.}}

{{s7 Note: Make sure that you are not replacing too much by wildcards. The filter http://example.com/* will definitely block all banners but it will also block everything else from example.com that you still might want to see.}}

{{s8 Defining exception rules}}

{{s9 Sometimes you will notice that one of your filters that is usually working quite well blocks in some case blocks something that it shouldn't be blocking. You don't want to remove this filter but you still don't want it to match in this one case.}}

{{s10 That's what exception rules are good for — they allow you to define cases where filters shouldn't be applied. For example if you are unhappy with your filter adv blocking http://example.com/advice.html, you can define an exception rule @@advice. Exception rules are no different from filter rules, you can use wildcards or regular expressions. You only have to precede them by @@ to indicate an exception rule.}}

{{s11 Exception rules can do more. If you specify $document option you will get an exception for the entire page. For example, if your exception rule is @@||example.com^$document and you open some page from example.com — Adblock Plus will be entirely disabled on this page and nothing will be blocked.}}

{{s12 Matching at beginning/end of an address}}

{{s13 Usually Adblock Plus treats every filter as if it had a wildcard at its beginning and end, e.g. there is not difference between the filters ad and *ad*. While this is usually unproblematic, sometimes you wish that the filter you defined only matches at the beginning or end of an address. For example you might want to block all Flash, but if you add the filter swf the address http://example.com/swf/index.html will also be blocked.}}

{{s14 Solution to this problem: add a pipe symbol to the filter to show that there should be definitely the end of the address at this point. For example the filter swf| will block http://example.com/annoyingflash.swf but not http://example.com/swf/index.html. And the filter |http://baddomain.example/ will block http://baddomain.example/banner.gif but not http://gooddomain.example/analyze?http://baddomain.example.}}

{{s15 Sometimes one wants to block http://example.com/banner.gif as well as https://example.com/banner.gif and http://www.example.com/banner.gif. This can be achieved by putting two pipe symbols in front of the filter which makes sure the filter matches at the beginning of the domain name: ||example.com/banner.gif will block all these addresses while not blocking http://badexample.com/banner.gif or http://gooddomain.example/analyze?http://example.com/banner.gif (requires Adblock Plus 1.1 or higher).}}

{{s16 Marking separator characters}}

{{s17 Often you need to accept any separator character in a filter. For example, you might write a filter that blocks http://example.com/ and http://example.com:8000/ but not http://example.com.ar/. Here the symbol ^ can be used as a placeholder for a single separator character: http://example.com^ (requires Adblock Plus 1.1 or higher).}}

{{s18 Separator character is anything but a letter, a digit, or one of the following: _ - . %. The end of the address is also accepted as separator. In the following example all separator characters are shown in red:}} http://example.com:8000/foo.bar?a=12&b=%D1%82%D0%B5%D1%81%D1%82{{s19 . So this address can be blocked with the filter ^example.com^ or ^%D1%82%D0%B5%D1%81%D1%82^ or ^foo.bar^.}}

{{s20 Comments}}

{{s21 Any rule that starts with an exclamation mark is considered a comment. It will still show up in the filter list but in grey instead of black. Adblock Plus will ignore this rule for actual blocking so it is safe to write there whatever you want. You can place a comment rule above a real filter to describe what it is doing. Or you can put a comment on top of your filter list stating your authorship (most filter list authors do that).}}

{{s22 Special comments}}

{{s23 Special comments will only have an effect in downloaded filter lists, not in custom filters.}} {{s24 They can set a number of parameters for the filter list:}}

{{s51 Advanced features}}

{{s52 The features described in this section are usually used only by power users and filterlist creators. Feel free to skip it.}}

{{s53 Specifying filter options}}

{{s54 Adblock Plus allows you to specify a number of options to modify the behavior of a filter. You list these options separated with commas after a dollar sign ($) at the end of the filter, for example:}}

*/ads/*$script,match-case

{{s55 Here */ads/* is the actual filter and script and match-case are its options. Currently the following options are supported:}}

{{s77 Using regular expressions}}

{{s79 If you want even more control about what your filters match and what they don't match, you can use regular expressions. For example the filter /banner\d+/ will match banner123 and banner321 but not banners. You can check out documentation on regular expressions to learn how to write them.}}

{{s80 Note: For performance reasons it is recommended not to use regular expressions if they can be avoided.}}

{{s81 Element hiding}}

{{s82 Basic rules}}

{{s83 Sometimes you will find advertisements that can't be blocked because they are embedded as text in the web page itself. If you look at the source code of the web page you might find something like this:}}

<div class="textad">
Cheapest tofu, only here and now!
</div>
<div id="sponsorad">
Really cheap tofu, click here!
</div>
<textad>
Only here you get the best tofu!
</textad>

{{s84 You need to download the web page so you will necessarily download the advertisements. All you can do here is to hide the advertisement so you don't need to see it. That's what element hiding is meant for.}}

{{s85 The first advertisement above is contained inside a div element with class attribute "textad". The following rule will hide exactly this combination: ##div.textad. Here ## marks an element hiding rule while the rest is a selector identifying the elements that need to be hidden. You can hide elements by their id attribute similarly, ##div#sponsorad will hide the second advertisement. You don't need to specify the element name, the rule ##*#sponsorad will work just as well. And you can hide elements by element name only, e.g. ##textad for the third advertisement.}}

{{s86 The Element Hiding Helper extension helps selecting the correct element and writing the corresponding rule without having to view the source code of the page. Basic HTML knowledge is useful nevertheless.}}

{{s87 Note: Element hiding works very differently from normal filters. This has the implication that no wildcards are supported in element hiding rules.}}

{{s88 Limiting rules to certain domains}}

{{s89 Usually you want to hide a specific ad on one specific site, you don't want your rule to be applied on other sites. For example the rule ##*.sponsor might hide valid code on some sites. But if you write it as example.com##*.sponsor it will be applied on http://example.com/ and http://something.example.com/ but not on http://example.org/. You can also specify multiple domains — simply separate them with commas: domain1.example,domain2.example,domain3.example##*.sponsor.}}

{{s90 If a domain name is preceded with "~", the rule will not be applied on pages from this domain (requires Adblock Plus 1.1 or higher). For example, ~example.com##*.sponsor will be be applied on pages from any domain but "example.com" and example.com,~foo.example.com##*.sponsor makes the rule apply on "example.com" domain with the exception of "foo.example.com" subdomain.}}

{{s91 Note: Due to the way how element hiding is implemented, you really can only limit it to full domain names. You cannot use any other part of the address and you cannot use domain as a replacement for domain.example,domain.test.}}

{{s92 Note: Element hiding rules with domain limitation can be used to hide browser's user interface elements as well. For example the filter rule browser##menuitem#javascriptConsole will hide the JavaScript Console entry in Firefox's Tools menu.}}

{{s93 Attribute selectors}}

{{s94 Some advertisers don't make it easy for you — their text advertisements have neither an id nor a class attribute. You can use other attributes to hide those, for example ##table[width="80%"] will hide tables with width attribute set to 80%. If you don't want to specify the full value of the attribute, ##div[title*="adv"] will hide all div elements with title attribute containing the string "adv". You can also check the beginning and the end of an attribute, for example ##div[title^="adv"][title$="ert"] will hide div elements with title starting with "adv" and ending with "ert". As you see, you can also use multiple conditions — table[width="80%"][bgcolor="white"] will match tables with width attribute set to 80% and bgcolor attribute set to white.}}

{{s95 Advanced selectors}}

{{s97 In general, any CSS selector supported by Firefox can be used for element hiding. For example the following rule will hide anything following a div element with class "adheader": ##div.adheader + *. For a full list of CSS list see W3C CSS specification (note that not all selectors are supported by Firefox yet).}}

{{s98 Note: This functionality is for advanced users only, you should be comfortable with CSS selectors to use it. Adblock Plus won't be able to check the syntax of the selector you are adding, if you use invalid CSS syntax you might break other (valid) rules you have. Check JavaScript Console for CSS errors.}}

{{s99 Exception rules}}

{{s100 Exception rules can disable existing rules on particular domains.}} {{s101 These are mostly useful to filter subscription authors who are extending another filter subscription that they cannot change.}} {{s102 For example, the rule ##div.textad can be disabled on example.com using the exception rule example.com#@#div.textad.}} {{s103 The combination of these two rules has exactly the same effect as the single rule ~example.com##div.textad.}} {{s104 It is recommended that you use exception rules only when you cannot change an overly general element hiding rule, in all the other cases limiting this rule to the necessary domains is preferable.}}

{{s105 Simplified element hiding syntax}}

{{s106 Adblock Plus supports simplified element hiding syntax (e.g. #div(id=foo)) for backwards compatibility only. Using this syntax is discouraged, usual CSS selectors are preferred. Support for this syntax might be removed at some point.}}

{{generic-specific-title Generic / Specific filters}}

{{generic-specific-explanation-p1 With the $generichide and $genericblock filter options the distinction between generic and specific filters becomes important.}}

{{generic-specific-explanation-p2 We classify a filter to be specific if it matches one or more domains or matches a sitekey. If a filter has no domains specified (or only domain exceptions) and no sitekey then it counts as generic. For example, example.com##div.textad is a specific filter, whereas both ##div.textad and ~example.com##div.textad are generic.}}

{{generic-specific-explanation-p3 Note that with blocking rules the domain must be specified under the $domain option for them to be considered specific. For example, ||example.com^ is considered generic whereas */ads/*$domain=example.com is site-specific.}}

{{s107 Implementing a sitekey on the server}}

{{s108 For a sitekey-restricted filter to apply, a webpage needs to return base64-encoded versions of the public key and a signature which Adblock Plus can validate. Currently, this means including them in both the HTTP response header (X-Adblock-Key: abcdpublickeydcba_abcdsignaturedcba) and the root tag of the document (<html data-adblockkey="abcdpublickeydcba_abcdsignaturedcba">).}}

{{s109 First you need to create a private RSA key (preferably 512 bit to keep the transfer volume low) and then a DER representation of the public key.}}

{{s110 The data used for creating the signature is a concatenated list of request variables (namely URI, host and user agent) separated by the NUL character "\0". For example:}} 

  /index.html?q=foo\0www.example.com\0Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:30.0) Gecko/20100101 Firefox/30.0

{{s111 Finally, generate the signature for this string by using the signature algorithm SEC_OID_ISO_SHA_WITH_RSA_SIGNATURE (default when using OpenSSL).}}