diff --git a/docs/extensions/metadata.md b/docs/extensions/metadata.md index 179b80eb9ef4e9a6dbe9da549c9133939dee65ac..5b77b589c7d73d155146326c986f89ead0d89fc4 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 13d23a34421a4c22c6d465d0e5ed83c7367e153d..8374c7187bdf68586fae744da5616308547b2949 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