readme.md 3.61 KB
Newer Older
Aral Balkan's avatar
Aral Balkan committed
1
# Better
Aral Balkan's avatar
Aral Balkan committed
2

Aral Balkan's avatar
Aral Balkan committed
3
Better protects you from unethical web sites. It makes your web experience safer, lighter, and faster.
Aral Balkan's avatar
Aral Balkan committed
4

Aral Balkan's avatar
Aral Balkan committed
5
Better enforces the [Ethical Design Manifesto](https://ind.ie/ethical-design). It helps the Web respect human rights, effort, and experience.
Aral Balkan's avatar
Aral Balkan committed
6

Aral Balkan's avatar
Aral Balkan committed
7
Better is curated by Ind.ie, a social enterprise that defends human rights. It’s free, open, and transparent.
Aral Balkan's avatar
Aral Balkan committed
8

Aral Balkan's avatar
Aral Balkan committed
9
## Content
Aral Balkan's avatar
Aral Balkan committed
10

Aral Balkan's avatar
Aral Balkan committed
11
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.
Aral Balkan's avatar
Aral Balkan committed
12

Aral Balkan's avatar
Aral Balkan committed
13
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.
Aral Balkan's avatar
Aral Balkan committed
14

Aral Balkan's avatar
Aral Balkan committed
15
This content is processed by [Better Builder](https://source.ind.ie/better/builder) to generate the [Better web site](https://better.fyi) as well as the data for the [Better iOS App](https://source.ind.ie/better/app), including a WebKit `blockerList.json` file.
Aral Balkan's avatar
Aral Balkan committed
16

Aral Balkan's avatar
Aral Balkan committed
17
A seminal advantage of Better is that its database is human-readable, open, and extensible via pull requests. (The database is curated by Ind.ie using the Ethical Design Manifesto as the criteria for blocking rules.)
Aral Balkan's avatar
Aral Balkan committed
18

19
Contributing to the content is as easy as creating an account on [source.ind.ie](https://source.ind.ie) and editing a content page in your browser.
20

Aral Balkan's avatar
Aral Balkan committed
21
## I’m not a developer, I just want to experience a Better web.
22

Aral Balkan's avatar
Aral Balkan committed
23
Get Better from the App Store.
24

Aral Balkan's avatar
Aral Balkan committed
25 26 27 28 29 30
## 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 Ind.ie](https://ind.ie/fund/) or, even better, [become a patron](https://ind.ie/fund/) by setting up a recurring donation.

## I’m a developer, let me in!

31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76
The easiest way to get started is to follow the instructions in the readme for the [Better iOS app](https://source.ind.ie/better/app) repository.

## Guide to Blockdown

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

### Sites

Site pages have the following sections:

#### Ethical design violations

```markdown
## 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 first badge is always the trackers badge. In Blockdown it is represented by a list item introduced by the word `Trackers`:

```markdown
  * Trackers (exposes you to NNN third-party sites)
```

We get the statistic for the number of third-party sites that a person browsing the site is exposed to by using [Mozilla Lightbeam](https://www.mozilla.org/en-US/lightbeam/).

Following the badge heading list item, there is a sublist of site URLs. For example, here’s an excerpt from the [cultofmac.com site page](https://better.fyi/sites/cultofmac.com):

```markdown
* Trackers (exposes you to 155 third-party sites)
  * w.soundcloud.com
  * goroost.com
  * taboola.com
  * google-syndication.com
  *
```

This gets automatically translated by [Better Builder](https://source.ind.ie/better/builder) to a badge similar to the one below:

![Screenshot of the trackers badge](images/readme/blockdown-trackers-badge-example.png)

Specifically, the builder counts the number of trackers for you and juxtapositions that with the number of third-party sites that you entered manually.

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

![Screenshot of the trackers popover](images/readme/blockdown-trackers-popover-example.png)