Commit 0365afd1 authored by Aral Balkan's avatar Aral Balkan

Documented the Blockdown format as it pertains to site pages in the readme.

parent 37e9636e
......@@ -30,17 +30,18 @@ Buying Better on the App Store is one way to support us. If you want to help wit
The easiest way to get started is to follow the instructions in the readme for the [Better iOS app]( repository.
## Guide to Blockdown
# 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 database.
### Sites
## Sites
Site pages have the following sections:
#### Ethical design violations
### Ethical design violations
## Ethical design violations
......@@ -48,6 +49,9 @@ Site pages have the following sections:
This is a list of ethical design violations that gets converted to a collection of badges on the rendered site pages.
#### Trackers
The first badge is always the trackers badge. In Blockdown it is represented by a list item introduced by the word `Trackers`:
......@@ -124,5 +128,53 @@ Trackers is the only section that is required for a site entry. The other badges
![Screenshot of the Web Bugs Badge](images/readme/blockdown/web-bugs-badge-example.png)
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 Blockdown section provides statistics about the before (without the Better content blocker active) and after (with the Better content blocker active) performance of a site.
The statistics are gathered using the Safari Web Inspector’s Timelines view.
Here is an example from the [ site page](
* Weight: 11.5MB to 3.22MB
* Speed: 10.38secs to 1.75secs
* Resources: 458 to 63
* Errors: 422 to 2
* Warnings: 19 to 13
The statistics in this section are translated into a graph and table view for the app and the site by Better Builder.
![Screenshot of the After Better Section](images/readme/blockdown/after-better.png)
## 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](#trackers) section and you have its own page in the `/trackers` section of the content.
Here is an example of a site-specific blocking rule in MSON 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.
\ No newline at end of file
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment