From c4a8ad356e05ce6be356d387fe39560008a3fe59 Mon Sep 17 00:00:00 2001
From: Ines Montani <ines@ines.io>
Date: Thu, 3 Nov 2016 13:06:29 +0100
Subject: [PATCH] Update website README.md

---
 website/README.md | 43 +++++++++++++++++++++++++++++++++++--------
 1 file changed, 35 insertions(+), 8 deletions(-)

diff --git a/website/README.md b/website/README.md
index 0c5340445..48e2a1bc4 100644
--- a/website/README.md
+++ b/website/README.md
@@ -50,7 +50,14 @@ p
     |  like this: #[+a("https://google.com") Google].
 ```
 
-Note that for external links, `+a("...")` is used instead of `a(href="...")` – it's a mixin that takes care of adding all required attributes.
+Note that for external links, `+a("...")` is used instead of `a(href="...")` – it's a mixin that takes care of adding all required attributes. If possible, always use a mixin instead of regular HTML elements. The only plain HTML elements we use are:
+
+| Element | Description |
+| --- | --- |
+| `p` | paragraphs |
+| `code` | inline `code` |
+| `em` | *italicized* text |
+| `strong` | **bold** text |
 
 ### Mixins
 
@@ -91,20 +98,40 @@ Code blocks are implemented using `+code` or `+aside-code` (to display them in t
 
 You can find the documentation for the available mixins in [`_includes/_mixins.jade`](_includes/_mixins.jade).
 
-### Linking to the Github repo
+### Helpers for linking to content
+
+Aside from the `+a()` mixin, there are three other helpers to make linking to content more convenient.
+
+#### Linking to GitHub
 
 Since GitHub links can be long and tricky, you can use the `gh()` function to generate them automatically for spaCy and all repositories owned by [explosion](https://github.com/explosion):
 
-```pug
-//- Syntax: gh(repo, [file], [branch])
+```javascript
+// Syntax: gh(repo, [file], [branch])
 
-+src(gh("spaCy", "spacy/matcher.pyx"))
-
-//- https://github.com/explosion/spaCy/blob/master/spacy/matcher.pyx
+gh("spaCy", "spacy/matcher.pyx")
+// https://github.com/explosion/spaCy/blob/master/spacy/matcher.pyx
 
 ```
 
-`+src()` creates a link with a little source icon to indicate it's linking to a code source.
+#### Linking to source
+
+`+src()` generates a link with a little source icon to indicate it's linking to a code source. Ideally, it's used in combination with `gh()`:
+
+```pug
++src(gh("spaCy", "spacy/matcher.pyx")) matcher.pxy
+```
+
+#### Linking to API reference
+
+`+api()` generates a link to a page in the API docs, with an added icon. It should only be used across the workflows in the usage section, and only on the first mention of the respective class.
+
+It takes the slug of an API page as the argument. You can also use anchors to link to specific sections – they're usually the method or property names.
+
+```pug
++api("tokenizer") #[code Tokenizer]
++api("doc#similarity") #[code Doc.similarity()]
+```
 
 ### Most common causes of compile errors