From ef8d5b96b736b9c75e07479d82bf8774e55a231e Mon Sep 17 00:00:00 2001
From: Sean Madsen <sean@seanmadsen.com>
Date: Mon, 13 Feb 2017 11:57:58 -0700
Subject: [PATCH] meta docs - improvements after the switch to Material Closes
 #90

---
 docs/documentation.md |  34 +++--
 docs/markdownrules.md | 339 ++++++++++++++++++++++--------------------
 mkdocs.yml            |   1 +
 3 files changed, 197 insertions(+), 177 deletions(-)

diff --git a/docs/documentation.md b/docs/documentation.md
index ba961afb..381f7e1c 100644
--- a/docs/documentation.md
+++ b/docs/documentation.md
@@ -14,7 +14,7 @@ This page describes the documentation systems within CiviCRM and how to contribu
 
 ## Guide books in MkDocs
 
-We are using [MkDocs](http://www.mkdocs.org) to produce guides, and have the following:
+We are using [MkDocs](http://www.mkdocs.org) to produce books, and have the following:
 
 | Book | English | French
 | ---- | ------- | ------ |
@@ -36,7 +36,7 @@ We are using [MkDocs](http://www.mkdocs.org) to produce guides, and have the fol
 [u-r-fr]: https://github.com/civicrm-french/civicrm-user-guide
 [d-r]: https://github.com/civicrm/civicrm-dev-docs
 
-The content for each of these guides is written in [markdown](/markdownrules.md), stored in text files, and hosted in a repository on GitHub. Then, the books are automatically published to **docs.civicrm.org** using our custom [documentation infrastructure](https://github.com/civicrm/civicrm-docs).
+The content for each of these books is written in [markdown](/markdownrules.md), stored in text files, and hosted in a repository on GitHub. Then, the books are automatically published to **docs.civicrm.org** using our custom [documentation infrastructure](https://github.com/civicrm/civicrm-docs).
 
 ### Languages
 
@@ -62,7 +62,7 @@ We welcome contributions, small and large, to documentation!
 Before diving into editing, you may find helpful information within the following resources:
 
 - [Markdown syntax](/markdownrules.md) - necessary (but simple) syntax to format content
-- Markdown coding standards - *[coming soon](https://github.com/civicrm/civicrm-dev-docs/issues/43)*
+- [Markdown code standards](/markdownrules.md#standards) - recommendations for markdown syntax to use
 - [Style guide](/best-practices/documentation-style-guide.md) - to maintain consistent language and formatting
 - [Documentation chat room](https://chat.civicrm.org/civicrm/channels/documentation) - live discussion, fast (most of the time) answers to your questions
 - [Documentation mailing list](https://lists.civicrm.org/lists/info/civicrm-docs) - low traffic, mostly used for informational updates regarding documentation projects
@@ -70,37 +70,43 @@ Before diving into editing, you may find helpful information within the followin
 
 ### Submitting issues
 
-The simplest way to help out is to *describe* a change that you think *should* be made by writing a new issue in the issue queue for the guide book you are reading. Then someone will see your issue and act on it, hopefully fast. Each guide book has its own issue queue. First find the GitHub repository for the book (listed in the above table), then when viewing on GitHub, click on "Issues". You will need an account on GitHub to submit a new issue, but creating one is quick and free.
+The simplest way to help out is to *describe* a change that you think *should* be made by writing a new issue in the issue queue for the book you are reading. Then someone will see your issue and act on it, hopefully fast. Each book has its own issue queue. First find the GitHub repository for the book (listed in the above table), then when viewing on GitHub, click on "Issues". You will need an account on GitHub to submit a new issue, but creating one is quick and free.
 
 ### Editing through GitHub
 
-A slightly more helpful way to plug in is to suggest specific changes by making the changes within the text editor on GitHub. To do this, you would go to the repository, find the markdown file for the page you'd like to change (look at the page's URL in your browser to help figure out where the file is within the repository), then click on the pencil icon at the top right of the page on GitHub. When you make a change, you are essentially forking (i.e. copying) the entire guide into your personal account on GitHub, changing that fork and then requesting to merge your fork into the main guide.
+A slightly more helpful way to contribute is to suggest specific changes by making the changes within the text editor on GitHub. To do this, you would go to the repository, find the markdown file for the page you'd like to change (look at the page's URL in your browser to help figure out where the file is within the repository), then click on the pencil icon at the top right of the page on GitHub. When you make a change, you are essentially forking (i.e. copying) the entire book into your personal account on GitHub, changing that fork and then requesting to merge your fork into the main book.
 
 ### Editing locally with MkDocs
 
-The most advanced way to work on a guide book is to use git to download all the markdown files to your computer, edit them locally, preview the changes with [MkDocs](http://mkdocs.org/), then use git to push those changes to your personal fork, and finally make a "pull request" on the main repository. This approach makes editing very fast and easy, but does require a bit of setup, and some knowledge of how git works.
+The most advanced way to work on a book is to use git to download all the markdown files to your computer, edit them locally, preview the changes with [MkDocs](http://mkdocs.org/), then use git to push those changes to your personal fork, and finally make a "pull request" on the main repository. This approach makes editing very fast and easy, but does require a bit of setup, and some knowledge of how git works.
 
 1. Install [pip](https://pypi.python.org/pypi/pip) (python package manager)
 
     - OS X: `brew install python`
     - Debian/Ubuntu: `sudo apt-get install python-pip python-wheel`
 
-1.  Install MkDocs.
+1.  Install MkDocs, plus the [Material theme](http://squidfunk.github.io/mkdocs-material/) and the [Pygments syntax highlighter](http://pygments.org/).
 
-        sudo pip install mkdocs
+    ```bash
+    sudo pip install mkdocs mkdocs-material pygments
+    ```
 
-1.  Obtain the source files for the guide you want to edit
+1.  Obtain the source files for the book you want to edit
     1.  Find the repository on GitHub *(see "repository" links above, or the "GitHub" link on the bottom left of screen of the documentation you are reading)*
     1.  Fork the repository on GitHub.
     1.  Clone *your fork* of the repository to your computer
+				
+        ```bash
+        git clone https://github.com/YourGitHubUserName/civicrm-dev-docs.git
+        cd civicrm-dev-docs
+        ```
 
-            git clone https://github.com/YourGitHubUserName/civicrm-dev-docs.git
-            cd civicrm-dev-docs
-
-1. Launch a local copy of the guide
+1. Launch a local copy of the book
     1. Run:
 
-            mkdocs serve
+        ```bash
+        mkdocs serve
+        ```
 
         -   If you get `[Errno 98] Address already in use` then try using a
             different port with `mkdocs serve -a localhost:8001`
diff --git a/docs/markdownrules.md b/docs/markdownrules.md
index b82774c8..626b3c5f 100644
--- a/docs/markdownrules.md
+++ b/docs/markdownrules.md
@@ -1,21 +1,25 @@
 # Markdown Syntax
 
-Learning [Markdown](https://en.wikipedia.org/wiki/Markdown)
-language is useful for:
+Markdown is a language used by many platforms to specify basic text formatting. This page describes its syntax, with a focus on features that work well within CiviCRM's documentation guide books.
 
-*   Writing CiviCRM [extensions](extend) -- In order for your extension to be
-    compliant, you must provide extension documentation, written in markdown.
-*   Writing other *.md* files that display on [GitHub]
-*   Contributing to CiviCRM [documentation](documentation)
-*   Chatting on [Mattermost](http://chat.civicrm.org)
-*   Q&A on [Stack Exchange](http://civicrm.stackexchange.com)
 
-[GitHub]: https://github.com
+## Platform differences
 
-Markdown language is mostly consistent across these platforms, but some
-discrepancies do exist. The `mkdocs` specific guide for markdown, as used in
-this book is
-[here](http://www.mkdocs.org/user-guide/writing-your-docs).
+Many platforms which use markdown have expanded or modified the [original syntax](https://daringfireball.net/projects/markdown/syntax), which has created subtle differences among various platforms.
+
+Platform-specific markdown references:
+
+* [Mattermost markdown](https://docs.mattermost.com/help/messaging/formatting-text.html)
+* [Stack Exchange markdown](http://stackoverflow.com/editing-help)
+* [GitHub markdown](https://help.github.com/categories/writing-on-github/)
+* CiviCRM's guide book markdown:
+    * Books are built with MkDocs which parses markdown with [Python-Markdown](https://pythonhosted.org/Markdown/).
+    * **But** the extra markdown features available depend heavily on the *theme* and *markdown extensions* used within the book.
+    * [Material](http://squidfunk.github.io/mkdocs-material/) is the recommended theme to be used for CiviCRM guide books
+    * [Extensions included within Python-Markdown](https://pythonhosted.org/Markdown/extensions/) can be enabled in the book's `mkdocs.yml` file without installing anything.
+    * [PyMdown Extensions](http://facelessuser.github.io/pymdown-extensions/) is a 3rd party package that provides many additionally useful extensions.
+
+The remainder of this page will focus on the markdown syntax which can be used within MkDocs books with the Material theme and common markdown extensions.
 
 
 ## CiviCRM markdown code standards {:#standards}
@@ -28,13 +32,16 @@ To maintain some consistency and peace of mind for documentation content editors
 * **Headings:** use hashes like `## Heading 2`.
 
 
-## Basics
+## Basic inline formatting
 
-*   `*italics*`
-*   `**bold**`
-*   `***bold and italic***`
-*   `~~strikethrough~~` *(GitHub/Mattermost/StackExchange)*
-*   `<del>strikethrough</del>` *(mkdocs)*
+| Code | Result | Extension required |
+| :-- | :-- | :-- |
+| `*italics*` | *italics* |  |
+| `**bold**` | **bold** |  |
+| `***bold and italic***` | ***bold and italic*** |  |
+| `` `monospace` `` | `monospace` |  |
+| `~~strikethrough~~` | ~~strikethrough~~ | [Tilde](http://facelessuser.github.io/pymdown-extensions/extensions/tilde/) |
+| `==highlight==` | ==highlight== | [Mark](http://facelessuser.github.io/pymdown-extensions/extensions/mark/) |
 
 Alternate syntax: Underscores for `_italics_` and `__bold__` also work on most
 platforms.
@@ -42,34 +49,51 @@ platforms.
 
 ## Hyperlinks
 
-*   A basic hyperlink (in a sentence)
+### External hyperlinks
+
+A basic external hyperlink in a sentence:
+
+```
+Try [CiviCRM](https://civicrm.org) for your database.
+```
+
+### Internal hyperlinks
 
-        Try [CiviCRM](https://civicrm.org) for your database.
+An internal hyperlink on mkdocs. Both of the following syntaxes work because the `.md` is optional. *Make sure to use an absolute path and precede the path with a slash, as shown below.*
+
+```
+[extensions](/extensions/basics)
+[extensions](/extensions/basics.md)
+```
+
+### Named hyperlinks
+
+If you're using a one link in many place throughout a page, you can define the URL in one place as follows
+
+```
+See [CRM-1234] for more details.
 
-*   An internal hyperlink on mkdocs. The `.md` is optional.
-    *Make sure to use an absolute path and precede the path with a slash,
-    as shown below.*
+My favorite issue is [CRM-1234].
 
-        [extensions](/extensions/basics)
-        [extensions](/extensions/basics.md)
+[CRM-1234]: https://issues.civicrm.org/jira/browse/CRM-1234
+```
 
-*   With long URLs, the following syntax is better.
+(The third line can be placed anywhere in the file.)
 
-        See [this issue][CRM-19799] for more details.
+### Named hyperlinks with custom text
 
-        [CRM-19799]: https://issues.civicrm.org/jira/browse/CRM-19799
+```
+After learning [how to foo a bar][foobar], then you can party!
 
-    -   The second line can be placed anywhere in the file.
-    -   Optionally, if the link ID ("CRM-19799" in this case) is omitted, you
-        can use the link text ("this issue") to reference the link in the
-        second line.
+[foobar]: https://example.com/foobar
+```
 
 
 ## Line breaks and whitespace
 
 **Single line breaks** in markdown code are eliminated in display:
 
-```md
+```
 This text will all show up
 on the
 same
@@ -82,7 +106,7 @@ where possible.
 
 **Double line breaks** create separate paragraphs:
 
-```md
+```
 This is
 one paragraph.
 
@@ -108,7 +132,7 @@ syntax within the CiviCRM community.
 An alternate syntax called "setext style headers" works for h1 and h2 as
 follows (but please avoid creating new content with this syntax).
 
-```md
+```
 Heading 1
 =========
 
@@ -116,77 +140,66 @@ Heading 2
 ---------
 ```
 
-### Heading IDs
+### Custom heading IDs
+
+!!! tip "Extension required"
+    To use custom heading IDs in MkDocs, insert the following code in `mkdocs.yml` to enable the [Attribute Lists](https://pythonhosted.org/Markdown/extensions/attr_list.html) extension:
+
+    ```yml
+    markdown_extensions:
+      - markdown.extensions.attr_list
+    ```
 
-Heading IDs allow you to link to specific sections in a page by appending
-the heading ID to the page URL. Most markdown platforms (e.g. MkDocs, GitHub)
-automatically set a heading ID for every heading and do so using the text of
-the heading itself. Sticking with the default is great is most cases, however
-sometimes you want to override it. Some markdown platforms (e.g. MkDocs)
-allow you to set *custom* heading IDs to override the automatically chosen
-value.
+Custom heading IDs allow you to link to specific sections in a page by appending the heading ID to the page URL. Most markdown platforms (e.g. MkDocs, GitHub) automatically set a heading ID for every heading and do so using the text of the heading itself. Sticking with the default is great is most cases, however sometimes you want to override it.
 
 Setting a custom ID:
 
-```md
+```
 ## How to foo a bar {:#foo}
 ```
 
 This is helpful when you think that readers are likely to frequently link
 to this section in the future.
 
-* Custom heading IDs will remain the same (thus preserving incoming links) even
-after the text of the heading is edited.
+* Custom heading IDs will remain the same (thus preserving incoming links) even after the text of the heading is edited.
 * Custom heading IDs create shorter URLs.
 
-Custom heading IDs only work in MkDocs when the following code is used to enable
-the [Attribute Lists](https://pythonhosted.org/Markdown/extensions/attr_list.html)
-extension:
-
-```yml
-markdown_extensions:
-  - markdown.extensions.attr_list
-```
 
 ## Lists
 
 ### Unordered lists
 
-```md
-*   My first item is here.
-*   My second item is here and a
-    bit longer than the first.
-*   Then, a third.
+```
+* My first item is here.
+* My second item is here and a
+  bit longer than the first.
+* Then, a third.
 ```
 
 Alternate syntax:
 
-*   Unordered lists also recognize `-` and `+` as item delimiters.
-*   Markdown is somewhat flexible with the quantity and position of spaces when
-    making lists, but using 3 spaces after the dash means that sub-lists look
-    nicer in code.
+* Unordered lists also recognize `-` and `+` as item delimiters.
+* Markdown is somewhat flexible with the quantity and position of spaces when making lists.
 
 
 ### Ordered lists
 
-```md
-1.  Item
-1.  Item
-1.  Item
+```
+1. Item
+1. Item
+1. Item
 ```
 
 Alternate syntax:
 
-*   Ordered lists items are automatically re-numbered sequentially upon display
-    which means all items can begin with `1`, or they can be ordered
-    sequentially in code.
+* Ordered lists items are automatically re-numbered sequentially upon display which means all items can begin with `1`, or they can be ordered sequentially in code.
 
 
 ### Nested lists
 
-List items must be indented 4 spaces:
+List sub-items must be indented 4 spaces:
 
-```md
+```
 1.  Item
     1.  Item
     1.  Item
@@ -204,14 +217,14 @@ List items must be indented 4 spaces:
 
 Use backticks to create inline monospace text:
 
-```md
+```
 Some `monospace text` amid a paragraph.
 ```
 
 And if you need to put a backtick inside your monospace text, begin and end
 with two backticks:
 
-```md
+```
 Some ``monospace text with `backticks` inside``, and all amid a paragraph.
 ```
 
@@ -220,15 +233,14 @@ Some ``monospace text with `backticks` inside``, and all amid a paragraph.
 
 A block of **"fenced code"** with three or more backticks on their own line.
 
-````md
+````
 ```
 CODE
 BLOCK
 ```
 ````
 
-*Fenced code can use more backticks when necessary to represent code with
-3 backticks (which is what you'd see in the source for this page).*
+*Fenced code can use more thank three backticks when necessary to represent code that contains 3 backticks (which is what you'd see in the source for this page).*
 
 Alternate syntax: For fenced code, the tilde `~` character also works
 in place of the backtick character but should be avoided for consistency.
@@ -236,7 +248,7 @@ in place of the backtick character but should be avoided for consistency.
 
 A block of **"indented code"** with four spaces at the start of each line:
 
-```md
+```
     CODE
     BLOCK
 ```
@@ -244,46 +256,58 @@ A block of **"indented code"** with four spaces at the start of each line:
 
 ### Syntax highlighting for code
 
-*   For code blocks, most platforms (e.g. mkdocs, GitHub) will guess guess the
-    language of the code and automatically apply syntax highlighting to the
-    display.
-*   To force a particular type of syntax highlighting, use fenced code with a
-    keyword (like `javascript` in this case) as follows:
-
-        ```javascript
-        var cj = CRM.$ = jQuery;
-        ```
-
-*   Available language keywords for forced syntax highlighting differ slightly
-    by markdown platform, but here are some common ones:
-    `as`, `atom`, `bas`, `bash`, `boot`, `c`, `c++`, `cake`, `cc`, `cjsx`,
-    `cl2`, `clj`, `cljc`, `cljs`, `cljsc`, `cljs.hl`, `cljx`, `clojure`,
-    `coffee`, `_coffee`, `coffeescript`, `cpp`, `cs`, `csharp`, `cson`, `css`,
-    `d`, `dart`, `delphi`, `dfm`, `di`, `diff`, `django`, `docker`,
-    `dockerfile`, `dpr`, `erl`, `erlang`, `f90`, `f95`, `freepascal`, `fs`,
-    `fsharp`, `gcode`, `gemspec`, `go`, `groovy`, `gyp`, `h`, `h++`,
-    `handlebars`, `haskell`, `haxe`, `hbs`, `hic`, `hpp`, `hs`, `html`,
-    `html.handlebars`, `html.hbs`, `hx`, `iced`, `irb`, `java`, `javascript`,
-    `jinja`, `jl`, `js`, `json`, `jsp`, `jsx`, `julia`, `kotlin`, `kt`, `ktm`,
-    `kts`, `lazarus`, `less`, `lfm`, `lisp`, `lpr`, `lua`, `m`, `mak`,
-    `makefile`, `markdown`, `matlab`, `md`, `mk`, `mkd`, `mkdown`, `ml`, `mm`,
-    `nc`, `objc`, `obj-c`, `objectivec`, `ocaml`, `osascript`, `pas`, `pascal`,
-    `perl`, `php`, `pl`, `plist`, `podspec`, `powershell`, `pp`, `ps`, `ps1`,
-    `puppet`, `py`, `python`, `r`, `rb`, `rs`, `rss`, `ruby`, `rust`, `scala`,
-    `scheme`, `scm`, `scpt`, `scss`, `sh`, `sld`, `smalltalk`, `sql`, `st`,
-    `swift`, `tex`, `thor`, `v`, `vb`, `vbnet`, `vbs`, `vbscript`, `veo`,
-    `xhtml`, `xml`, `xsl`, `yaml`, `zsh`
+*   For code blocks, some platforms (e.g. GitHub) will guess guess the language of the code and automatically apply syntax highlighting to the display.
+*   To force a particular type of syntax highlighting, use fenced code with a keyword (like `javascript` in this case) as follows:
+
+    ````
+    ```javascript
+    var cj = CRM.$ = jQuery;
+    ```
+    ````
+
+*   Available language keywords:
+    *   Differ slightly by markdown platform
+    *   Common language keywords that work on most platforms: `bash`, `css`, `docker`, `html`, `javascript`, `js`, `json`, `markdown`, `md`, `perl`, `php`, `python`, `ruby`, `scss`, `sh`, `smarty`, `sql`, `xhtml`, `xml`, `yaml`
+    *   The Material theme for MkDocs will use the Pygments python library when possible, and in this case provide syntax highlighting for [over 300 languages](http://pygments.org/docs/lexers).
+
 *   Syntax highlighting cannot be forced for indented code.
-*   Syntax highlighting is not available for inline code.
+*   Syntax highlighting for inline code is possible with [InlineHilite](http://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/) but not recommended.
 *   [Stack Exchange syntax highlighting][stack exchange syntax highlighting] is
     done differently.
 
 [stack exchange syntax highlighting]: http://stackoverflow.com/editing-help#syntax-highlighting
 
+
+
 ### Code blocks within lists
 
-You can use **indented code within lists** by keeping a blank line
-above/below and indenting *4 spaces more than your list content*, like this:
+#### Fenced code within lists
+
+!!! tip "Extension required"
+    To use fenced code within lists in MkDocs, install [PyMdown Extensions](http://facelessuser.github.io/pymdown-extensions) and then insert the following code in `mkdocs.yml` to enable the [Superfences](http://facelessuser.github.io/pymdown-extensions/extensions/superfences/) extension:
+
+    ```yml
+    markdown_extensions:
+      - pymdownx.superfences
+    ```
+
+Then insert fenced code into a list as follows:
+
+````md
+*   First item
+*   Look at this code:
+
+    ```md
+    code
+    block
+    ```
+
+*   More list items
+````
+
+#### Indented code within lists
+
+You can use indented code within lists without needing any markdown extensions. Keep a blank line above and below the code and indent the code *4 spaces more than your list content*, like this:
 
 ```md
 *   First item
@@ -305,42 +329,17 @@ above/below and indenting *4 spaces more than your list content*, like this:
 *   Fun, right?
 ```
 
-**Fenced code within lists** is shown below. It works on GitHub but **not
-mkdocs**:
-
-````md
-*   First item
-*   Look at this code:
-
-    ```md
-    code
-    block
-    ```
 
-*   More list items
-````
 
 ## Admonitions
 
-### Types
-
-!!! note
-    I am a "note" admonition.
-
-!!! tip
-    I am a "tip" admonition.
-
-!!! warning
-    I am a "warning" admonition.
-
-!!! danger
-    I am a "danger" admonition.
-
-Other types
+!!! tip "Extension required"
+    To use admonitions in MkDocs, insert the following code in `mkdocs.yml` to enable the [Admonitions](https://pythonhosted.org/Markdown/extensions/admonition.html) extension:
 
-*   "hint", "important" (visually identical to "tip")
-*   "attention", "caution" (visually identical to "warning")
-*   "error" (visually identical to "danger")
+    ```yml
+    markdown_extensions:
+      - markdown.extensions.admonition
+    ```
 
 ### Syntax
 
@@ -348,7 +347,7 @@ Simple example:
 
 ```md
 !!! note
-    This feature is only available as of CiviCRM 4.5.
+    Here is a note for you.
 ```
 
 Add a custom title (make sure to quote the title):
@@ -358,31 +357,52 @@ Add a custom title (make sure to quote the title):
     Stand back. I'm about to try science!
 ```
 
-### Enabling
+(You can also add an admonition *without* a title by passing an empty string `""` in place of the title.)
+
+### Types
 
-Admonitions only work in MkDocs when the following code is used to enable
-the [Admonition extension](https://pythonhosted.org/Markdown/extensions/admonition.html):
+The types of admonitions available for use in MkDocs depend on the theme being used. The Material theme [supports](http://squidfunk.github.io/mkdocs-material/extensions/admonition/#types) the following types:
+
+!!! note
+    I am a "note" admonition and look the same as "seealso".
+
+!!! tip
+    I am a "tip" admonition and look the same as "hint" and "important".
+
+!!! warning
+    I am a "warning" admonition and look the same as "attention" and "caution".
+
+!!! danger
+    I am a "danger" admonition and look the same as "error".
+
+!!! summary
+    I am a "summary" admonition and look the same as "tldr".
+
+!!! success
+    I am a "success" admonition and look the same as "check" and "done".
+
+!!! failure
+    I am a "failure" admonition and look the same as "fail" and "missing".
+
+!!! bug
+    I am a "bug" admonition.
 
-```yml
-markdown_extensions:
-  - markdown.extensions.admonition
-```
 
 ## Images
 
 Images function mostly the same as hyperlinks, but preceded by an exclamation
 point and with alt text in place of the link text.
 
-```md
-![Alt text](image.png)
+```
+![Alt text](/directory/image.png)
 ```
 
 or
 
-```md
+```
 ![Alt text][id]
 
-[id]: image.png
+[id]: /directory/image.png
 ```
 
 
@@ -393,18 +413,11 @@ or
 *   Blockquotes
 
         > This text is a blockquote, typically used
-        > to represent prose written by a person. It
-        > will be displayed slightly indented.
+          to represent prose written by a person. It
+          will be displayed slightly indented.
 
 [Emojis]: http://www.webpagefx.com/tools/emoji-cheat-sheet/
 [Tables]: https://help.github.com/articles/organizing-information-with-tables
 
-## External references
-
-*   [Mattermost markdown](https://docs.mattermost.com/help/messaging/formatting-text.html)
-*   [Stack Exchange markdown](http://stackoverflow.com/editing-help)
-*   [GitHub markdown](https://help.github.com/categories/writing-on-github/)
-*   [Official markdown reference](https://daringfireball.net/projects/markdown/syntax)
-    (though somewhat difficult to read)
 
 
diff --git a/mkdocs.yml b/mkdocs.yml
index 130471a5..2457520a 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -13,6 +13,7 @@ markdown_extensions:
   - pymdownx.inlinehilite
   - pymdownx.tilde
   - pymdownx.betterem
+  - pymdownx.mark
 pages:
 - Home: index.md
 - Basics:
-- 
GitLab