Better content in Blockdown format.

Name Last Update
.gitlab/issue_templates Loading commit data...
experimental Loading commit data...
images/readme/better Loading commit data...
legal Loading commit data...
sites Loading commit data...
trackers Loading commit data...
.gitignore Loading commit data...
CHANGELOG Loading commit data... Loading commit data...
LICENSE Loading commit data... Loading commit data...
deploy Loading commit data... Loading commit data... Loading commit data...
save Loading commit data... Loading commit data...


Better protects you from unethical web sites. It makes your web experience safer, lighter, and faster.

Better enforces the Ethical Design Manifesto. It helps the Web respect human rights, effort, and experience.

Better is curated by, a tiny two-person-and-one-husky social enterprise striving for social justice in the digital age. Better is free, open, and transparent.


This repository contains the Better content: Better’s database of information on trackers and other malware as well as the web sites that host them.

This content is in Blockdown format. Blockdown is an extension of Markdown with special vocabulary to describe web malware. Blockdown can also contain WebKit content blocking rules. The Blockdown pages in Better’s content repository both describe web malware and contain the rules to block them.

This content is processed by Better Builder to generate the Better web site as well as the data for the Better iOS App, including a WebKit blockerList.json file.

A seminal advantage of Better is that its database is human-readable, open, and extensible via pull requests. (The database is curated by using the Ethical Design Manifesto as the criteria for blocking rules.)

Contributing to the content is as easy as creating an account on and editing a content page in your browser.

I’m not a developer, I just want to experience a Better web.

Get Better from the App Store.

How can I support Better?

Buying Better on the App Store is one way to support us. If you want to help with the ongoing costs of developing and maintaining Better, you can donate to or, even better, become a patron by setting up a recurring donation.

I’m a developer, let me in!

The easiest way to get started is to follow the instructions in the readme for the Better iOS app repository.

Testing locally.

Better Builder will automatically pick up your changes as you save and rebuild your local data.

To persist your changes locally, commit them in Git and push to origin:

git commit -am "My awesome content update"
git push origin master

Note that these changes will be destroyed if you run the Better Builder installer (or the Better iOS installer, which runs the Better Builder installer as part of its own installation process). To not lose any work, save your changes regularly by pushing to production, as explained below.

Saving your changes by pushing to production

You can push to production with:


Or, manually run what the save script does, which is:

git push live master


Before you can deploy, you must set up a GPG key and configure Git to use it. This is used to sign your tags.

Then, if you have commit rights to the content repository, just run the deployment script:


This will create a tag (you will have to enter a tag mesage when prompted, describing the release) and push it to production. Please make sure that you have already committed your changes and pushed them to production either via git push live master or by running the ./save script, which does the same thing.

# Guide to Blockdown

Better content is authored in Blockdown.

Blockdown is Markdown with an extended high-level vocabulary for describing web malware for the Better knowledge base.


Site pages have the following sections:

Ethical design violations

## Ethical design violations

This is a list of ethical design violations that gets converted to a collection of badges on the rendered site pages. The Trackers part of the list, detailed below, is updated automatically by Better Inspector


The first badge is always the trackers badge. In Blockdown it is represented by a list item introduced by the word Trackers:

  * (Trackers)
    * Automatically
    * Generated
    * List
    * of
    * Trackers

This gets automatically translated by Better Builder to a badge similar to the one below:

Screenshot of the trackers badge

Tapping on the badge displays a popover with links to the actual trackers.

Screenshot of the trackers popover

The other badges are manually added if they apply to the site in question:


* (Aggressive)

Attempts to block content blockers.

Screenshot of the Aggressive Badge


* (Doorslam)

Interrupts and blocks using modal dialogs.

Screenshot of the Doorslam Badge


* (Clickbait)

Uses exploitative, addictive content syndication network(s).

Screenshot of the Clickbait Badge


* (Fingerprint)

Uses hidden Canvas fingerprinting.

Screenshot of the Fingerprint Badge

Web Bug

* (Web bug)

Uses invisible tracking pixels.

Screenshot of the Web Bugs Badge

We might create new badges as and when we find new types of web malware and unethical practices to document and warn people about.

After Better section

## After Better

The After Better section provides statistics about the before (without the Better content blocker active) and after (with the Better content blocker active) performance of a site.

It is automatically generated by Better Inspector

Screenshot of the After Better Section

Block Rules section

This is the section where we enter the actual WebKit content blocking rules. Each rule is written in a strict subset of MSON (Markdown JSON) and has a brief explanation detailing what the rule does and why.

The blocking rules in this section serve the following purposes, in line with the Ethical Design Manifesto

  • Remove any first-party trackers (respect human rights)
  • Improve the usability of the site by removing first-party impediments like doorslams (respect human effort)
  • Improve the experience of the site (respect human effort) – we should especially aim to create a better experience after trackers have been removed (like removing empty spaces left over, etc.)

Please note that this is not the place to put blocking rules for trackers. Each tracker encountered should be entered into the Trackers section and you have its own page in the /trackers section of the content.

Blockdown syntax

Here is an example of a site-specific blocking rule in Blockdown format:

- trigger:
  - url-filter:
- action:
  - type: block

The Blockdown parser in Better supports all of the WebKit content blocking rules. Instead of JSON, however, we enter blocking rules in MSON. All Blockdown rules are combined by Better Builder into a single blockerList.json file.

Blockdown differs from plain WebKit content blocker rules in several ways to make authoring easier and to aid in readability:

  1. The default load type is ‘third-party’.
  2. The default action type is ‘block’.
  3. The default is for rules to be case sensitive.

So, if we take the following fully-specified rule:

- trigger:
  - url-filter: somedomain.ext
  - load-type: third-party
  - url-filter-is-case-sensitive: true
- action
  - type: block

We can simplify it naïvely by removing the properties that have defaults:

- trigger:
  - url-filter: somedomain.ext
- action

Which leaves us with a valid rule but a sad-looking empty action section. In Blockdown neither the trigger nor action sections are required, so we can remove those also. This leaves us with:

  - url-filter: somedomain.ext

But surely, we can do better than that. So we handle this special case in Blockdown by not requiring the url-filter key either:


Ah, better! ;)

All of the above Blockdown rules are equivalent and will compile into the following fully-formed and highly specific WebKit content blocking rule in JSON:

  "trigger": {
   "load-type": [
    "url-filter-is-case-sensitive": true,
    "url-filter": "^[^:]+://+([^:/]+\\.)?somedomain\\.ext[:/]?"
  "action": {
    "type": "block"

Automatic URL filter compilation

Blockdown automatically compiles simple url-filter properties to regular expressions with higher specificity as recommended in the domain targeting recommendations by WebKit engineer Benjamin Poulain.

This means that you can author your entries in plain text, like this:

  - url-filter: some-domain.ext

And Blockdown will compile them into the following form in the blockerList.json:

  "url-filter": "^[^:]+://+([^:/]+\\.)?some-domain\\.ext[:/]?"

Further reading on WebKit content blocking

Investigation process

Currently, you need to have commit rights to the Content repository to use the Better commandline commands. However, you can use Git directly to fork the repository and submit merge requests and you can add and edit pages through the online GitLab interface without commit rights.

Find who owns and runs the tracker

  1. Start by editing the tracker

    better/edit drafts/trackers/

    This will create an issue in GitLab (or update an existing issue, if one already exists) and create or checkout a branch for you. It will also open your working copy of the tracker page in your system editor and in the browser.

  2. Enter the tracker URL into your browser in a private window to see if it loads.

    Make sure you don’t have an VPNs or extensions blocking or making your browser behave differently from the norm. If you have any tracker blockers already enabled, it may make it harder to investigate!

  3. If it doesn’t load, or if you get a blank page, perform a whois.

    We are currently using for these so we can link to is as a source when stating ownership information. However, you will sometimes get more information from a direct whois look-up on your machine. In Terminal: whois

  4. Some trackers use a domain proxy or a cloaking service (e.g., Domains by Proxy) to further hide their origins. In this case:

    • Open up the source of a site that the tracker originated on in the Web Developer console (Timeline view) of Safari (or in the web inspector of your browser of choice)
    • Try to recreate the original call. This might give you more clues about its origin.

To find which sites a tracker is on, perform a search on the ~/ folder. For example, you can open up the folder in your text editor and do a global search for the tracker name.

You can also use Better Inspector to search for strings within requests. e.g., to find all URLs that contain, run:

    ./inquiry --local

Other useful tools:

Add the tracker/site name to the tracker markdown file

The name should be formatted as:

**TrackerName** by Corporation (domain.tld)

If the tracker name is the same as the corporation name (e.g. Adlucent by Adlucent) then just keep the tracker name, and don’t incude the corporation name. When you edit a tracker markdown file for the first time, the domain.tld will already be in the title.

Add the site description

Add a concise one-line description of what the tracker, or the tracker owner, does.

Usually the tracker sites have vague marketing spiel to describe themselves. Often a clearer description can be found in their privacy policy. If you can’t find a concise description in their own words, try to find their entry on Wikipedia, Bloomberg or Crunchbase.

Other useful tools:

Include references in Notes

  • Whether it’s the domain whois, or where you found the site description, include a link back to every source in the Notes section.
  • Include a link to the tracker/corporation Privacy Policy (if it exists!)
  • If you end up looking through the source file to find more information, you can include relevant code snippets in markdown.

You can use sub-lists in Notes by using indented lists in markdown. See the Demandbase tracker for an varied use of Notes

Handling duplicate trackers

Loads of trackers have multiple domains for the same tracker, or group of trackers. In this case, we don’t want duplicate entries that don’t stay in sync.

  1. The first tracker found and investigated is the canonical tracker.

  2. Any further trackers with the same name/owner should link to the canonical tracker in place of the description. Example from tracker:

    > See [](/trackers/
  3. The Ethical Design Violations are still necessary, as the type of violation might vary between the domains.

  4. The Block Rule is still necessary, as it blocks this specific domain.

  5. The only Notes necessary is the source for the domain origin. Any other notes can be added to the canonical tracker.

Read more in the Better Content styleguide.

Discussions on the Investigations processes can be found on the forum.