Commit 4b15f4ca authored by Aral Balkan's avatar Aral Balkan

Updated readme with latest Blockdown syntax updates.

parent a5c9b423
......@@ -71,7 +71,7 @@ This will create a tag (you will have to enter a tag mesage when prompted, descr
Better content is authored in Blockdown.
Blockdown is Markdown with an extended high-level vocabulary for describing web malware for the Better database.
Blockdown is Markdown with an extended high-level vocabulary for describing web malware for the Better knowledge base.
## Sites
......@@ -188,7 +188,9 @@ The blocking rules in this section serve the following purposes, in line with th
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:
### Blockdown syntax
Here is an example of a site-specific blocking rule in Blockdown format:
```markdown
```mson
......@@ -203,25 +205,69 @@ The Blockdown parser in Better supports all of the [WebKit content blocking rule
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 in Blockdown is third-party.
2. The default for rules to be case sensitive.
1. The default load type is ‘third-party’.
2. The default action type is ‘block’.
2. The default is for rules to be case sensitive.
So, if you do not specify a `load-type` or `url-filter-is-case-sensitive` properties in your rules, they will behave as if you had specified:
So, if we take the following fully-specified rule:
```markdown
```mson
- trigger:
- url-filter:
- 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:
```markdown
```mson
- 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:
```markdown
```mson
- url-filter: somedomain.ext
``` 
```
You may, of course, override these by explicitly specifying those properties in your rules.
But surely, we can do better than that. So we handle this special case in Blockdown by not requiring the url-filter key either:
```markdown
```mson
somedomain.ext
``` 
```
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:
```json
{
"trigger": {
"load-type": [
"third-party"
],
"url-filter-is-case-sensitive": true,
"url-filter": "^[^:]+://+([^:/]+\\.)?somedomain\\.ext[:/]?"
},
"action": {
"type": "block"
}
}
```
## Automatic URL filter compilation
## 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](https://webkit.org/blog/4062/targeting-domains-with-content-blockers/).
......
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