From 8301023de7318339f71c48d1effc7d196ce9c2e7 Mon Sep 17 00:00:00 2001
From: Sean Madsen <sean@seanmadsen.com>
Date: Sun, 22 Jan 2017 08:36:19 -0700
Subject: [PATCH] /markdownrules.md updates * documenting custom header IDs *
 removing rule about using one H1 element (that's in style guide now) *
 clarifying thad admonitions only work when enabled

---
 docs/markdownrules.md | 43 ++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 40 insertions(+), 3 deletions(-)

diff --git a/docs/markdownrules.md b/docs/markdownrules.md
index 50325a93..158be8fe 100644
--- a/docs/markdownrules.md
+++ b/docs/markdownrules.md
@@ -105,10 +105,37 @@ Heading 2
 ---------
 ```
 
-***Convention:*** Each page should have one and only one *Heading 1*,
-which should be at the top of the page as a page title. Other headings within
-page content should be level 2 or greater.
+### Heading IDs
 
+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.
+
+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 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
 
@@ -320,6 +347,16 @@ Add a custom title (make sure to quote the title):
     Stand back. I'm about to try science!
 ```
 
+### Enabling
+
+Admonitions only work in MkDocs when the following code is used to enable
+the [Admonition extension](https://pythonhosted.org/Markdown/extensions/admonition.html):
+
+```yml
+markdown_extensions:
+  - markdown.extensions.admonition
+```
+
 ## Images
 
 Images function mostly the same as hyperlinks, but preceded by an exclamation
-- 
GitLab