From 7cf7ff98a28b71924bd74eba02d2f2896be5715d Mon Sep 17 00:00:00 2001
From: squidfunk <martin.donath@squidfunk.com>
Date: Sun, 11 Feb 2018 19:18:33 +0100
Subject: [PATCH] Added documentation for Disqus overrides

---
 docs/extensions/metadata.md | 55 +++++++++++++++++++++++++------------
 docs/getting-started.md     | 33 ++++++++++++----------
 2 files changed, 55 insertions(+), 33 deletions(-)

diff --git a/docs/extensions/metadata.md b/docs/extensions/metadata.md
index 179b80eb..5b77b589 100644
--- a/docs/extensions/metadata.md
+++ b/docs/extensions/metadata.md
@@ -49,7 +49,35 @@ see on the current page when you scroll to the top. It's as simple as:
 hero: Metadata enables hero teaser texts
 ```
 
-### Overriding the title
+### Linking sources
+
+When a document is related to a specific set of source files and the `repo_url`
+is defined inside the project's `mkdocs.yml`, the files can be linked using the
+`source` key:
+
+``` markdown
+source: file.js
+```
+
+The filename is appended to the `repo_url` set in your `mkdocs.yml`, but can
+be prefixed with a `path` to ensure correct path resolving:
+
+Example:
+
+``` markdown
+path: tree/master/docs/extensions
+source: metadata.md
+```
+
+Result:
+
+See the [source][2] section for the resulting output.
+
+  [2]: #__source
+
+### Overrides
+
+#### Page title
 
 The page title can be overridden on a per-document level:
 
@@ -62,7 +90,7 @@ to the provided value. It will also override the default behavior of Material
 for MkDocs which appends the site title using a dash as a separator to the page
 title.
 
-### Overriding the description
+#### Page description
 
 The page description can also be overridden on a per-document level:
 
@@ -73,28 +101,19 @@ description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
 This will set the `meta` tag containing the site description inside the
 document `head` for the current page to the provided value.
 
-### Linking sources
+#### Disqus
 
-When a document is related to a specific set of source files and the `repo_url`
-is defined inside the project's `mkdocs.yml`, the files can be linked using the
-`source` key:
+As describe in the [getting started guide][3], the Disqus comments section can
+be enabled on a per-document level:
 
 ``` markdown
-source: file.js
+disqus: your-shortname
 ```
 
-The filename is appended to the `repo_url` set in your `mkdocs.yml`, but can
-be prefixed with a `path` to ensure correct path resolving:
-
-Example:
+Disqus can be disabled for a specific page by setting it to an empty value:
 
 ``` markdown
-path: tree/master/docs/extensions
-source: metadata.md
+disqus:
 ```
 
-Result:
-
-See the [source][2] section for the resulting output.
-
-  [2]: #__source
+  [3]: ../getting-started.md#disqus
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 13d23a34..8374c718 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -593,11 +593,14 @@ automatically included.
     `site_url` value must be set in `mkdocs.yml` for the Disqus integration to
     load properly.
 
+Disqus can also be enabled or disabled for specific pages using [Metadata][23].
+
   [22]: https://disqus.com
+  [23]: extensions/metadata.md#disqus
 
 ## Extensions
 
-MkDocs supports several [Markdown extensions][23]. The following extensions
+MkDocs supports several [Markdown extensions][24]. The following extensions
 are not enabled by default (see the link for which are enabled by default)
 but highly recommended, so they should be switched on at all times:
 
@@ -613,20 +616,20 @@ markdown_extensions:
 For more information, see the following list of extensions supported by the
 Material theme including more information regarding installation and usage:
 
-* [Admonition][24]
-* [Codehilite][25]
-* [Footnotes][26]
-* [Metadata][27]
-* [Permalinks][28]
-* [PyMdown Extensions][29]
-
-  [23]: http://www.mkdocs.org/user-guide/writing-your-docs/#markdown-extensions
-  [24]: extensions/admonition.md
-  [25]: extensions/codehilite.md
-  [26]: extensions/footnotes.md
-  [27]: extensions/metadata.md
-  [28]: extensions/permalinks.md
-  [29]: extensions/pymdown.md
+* [Admonition][25]
+* [Codehilite][26]
+* [Footnotes][27]
+* [Metadata][28]
+* [Permalinks][29]
+* [PyMdown Extensions][30]
+
+  [24]: http://www.mkdocs.org/user-guide/writing-your-docs/#markdown-extensions
+  [25]: extensions/admonition.md
+  [26]: extensions/codehilite.md
+  [27]: extensions/footnotes.md
+  [28]: extensions/metadata.md
+  [29]: extensions/permalinks.md
+  [30]: extensions/pymdown.md
 
 ## Full example
 
-- 
GitLab