Added nodes on snippets and fixed some documentation errors

docs/reference/admonitions.md

@@ -46,24 +46,20 @@ markdown_extensions:
 
 ### SuperFences
 
-[:octicons-file-code-24: Source][6] · [:octicons-workflow-24: Extension][7]
+The [SuperFences][6] extension, which is also part of [Python Markdown
-
+Extensions][5], allows for the __nesting of code and content blocks inside
-The [SuperFences][7] extension, which is also part of [Python Markdown
+admonitions__, and is therefore strongly recommended:
-Extensions][5], allows for the __nesting of content blocks inside admonitions__, 
-and is therefore strongly recommended:
 
 ``` yaml
 markdown_extensions:
   - pymdownx.superfences
 ```
-
+  [6]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
-  [6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_typeset.scss
-  [7]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
 
 ## Usage
 
 Admonitions follow a simple syntax: a block must start with `!!!`, followed
-by a single keyword which is used as the [type qualifier][8] of the block. The
+by a single keyword which is used as the [type qualifier][7] of the block. The
 content of the block then follows on the next line, indented by four spaces.
 
 _Example_:
@@ -83,7 +79,7 @@ _Result_:
     nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
     massa, nec semper lorem quam in massa.
 
-  [8]: #supported-types
+  [7]: #supported-types
 
 ### Changing the title
 
@@ -110,9 +106,9 @@ _Result_:
 
 ### Removing the title
 
-Similar to [changing the title][9], the icon and title can be omitted entirely
+Similar to [changing the title][8], the icon and title can be omitted entirely
 by adding an empty string directly after the type qualifier. Note that this 
-will not work for [collapsible blocks][10].
+will not work for [collapsible blocks][9].
 
 _Example_:
 
@@ -131,14 +127,14 @@ _Result_:
     nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
     massa, nec semper lorem quam in massa.
 
-  [9]: #changing-the-title
+  [8]: #changing-the-title
-  [10]: #collapsible-blocks
+  [9]: #collapsible-blocks
 
 ### Embedded content
 
 Admonitions can contain all kinds of text content, including headlines, lists,
 paragraphs and other blocks. While the parser from the standard Markdown library
-doesn't account for nested blocks, the [SuperFences][11] extension adds the 
+doesn't account for nested blocks, the [SuperFences][10] extension adds the
 ability to nest arbitrary content inside admonitions.
 
 _Example_:
@@ -182,11 +178,11 @@ _Result_:
     sem ut cursus. Nullam sit amet tincidunt ipsum, sit amet elementum turpis.
     Etiam ipsum quam, mattis in purus vitae, lacinia fermentum enim.
 
-  [11]: #superfences
+  [10]: #superfences
 
 ### Collapsible blocks
 
-The [Details][12] extension adds support for rendering collapsible admonition
+The [Details][11] extension adds support for rendering collapsible admonition
 blocks. This is useful for FAQs or content that is of secondary nature. A
 details block follows the syntax and semantics of admonition blocks, but must
 start with `???`.
@@ -227,14 +223,14 @@ _Result_:
     nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
     massa, nec semper lorem quam in massa.
 
-  [12]: #details
+  [11]: #details
 
 ### Supported types
 
 Following is a list of type qualifiers provided by Material for MkDocs, whereas
 the default type, and thus fallback for unknown type qualifiers, is `note`:
 
-`note`, `seealso`
+`note`{: #note }, `seealso`
 
 :   !!! note
 
@@ -242,7 +238,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-`abstract`, `summary`, `tldr`
+`abstract`{: #abstract }, `summary`, `tldr`
 
 :   !!! abstract
 
@@ -250,7 +246,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-`info`, `todo`
+`info`{: #info}, `todo`
 
 :   !!! info
 
@@ -258,7 +254,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-`tip`, `hint`, `important`
+`tip`{: #tip }, `hint`, `important`
 
 :   !!! tip
 
@@ -266,7 +262,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-`success`, `check`, `done`
+`success`{: #success }, `check`, `done`
 
 :   !!! success
 
@@ -274,7 +270,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-`question`, `help`, `faq`
+`question`{: #question }, `help`, `faq`
 
 :   !!! question
 
@@ -282,7 +278,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-`warning`, `caution`, `attention`
+`warning`{: #warning }, `caution`, `attention`
 
 :   !!! warning
 
@@ -290,7 +286,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-`failure`, `fail`, `missing`
+`failure`{: #failure }, `fail`, `missing`
 
 :   !!! failure
 
@@ -298,7 +294,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-`danger`, `error`
+`danger`{: #danger }, `error`
 
 :   !!! danger
 
@@ -306,7 +302,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-`bug`
+`bug`{: #bug }
 
 :   !!! bug
 
@@ -314,7 +310,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-`example`
+`example`{: #example }
 
 :   !!! example
 
@@ -322,7 +318,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-`quote`, `cite`
+`quote`{: #quote }, `cite`
 
 :   !!! quote
 

docs/reference/code-blocks.md

@@ -135,27 +135,11 @@ See the section on [inline code blocks][12] for usage information.
   [11]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
   [12]: #highlighting-inline-code-blocks
 
-### SuperFences
+### Keys
 
 [:octicons-file-code-24: Source][13] · [:octicons-workflow-24: Extension][14]
 
-The [SuperFences][14] extension, which is also part of [Python Markdown
+The [Keys][14] extension, which is part of [Python Markdown Extensions][5],
-Extensions][5], allows for the __nesting of code blocks inside other blocks__,
-and is therefore strongly recommended:
-
-``` yaml
-markdown_extensions:
-  - pymdownx.superfences
-```
-
-  [13]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_typeset.scss
-  [14]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
-
-### Keys
-
-[:octicons-file-code-24: Source][15] · [:octicons-workflow-24: Extension][16]
-
-The [Keys][16] extension, which is part of [Python Markdown Extensions][5],
 allows for inserting __keyboard keys__, e.g. ++ctrl+alt+delete++ , and
 can be enabled via `mkdocs.yml`:
 
@@ -164,8 +148,34 @@ markdown_extensions:
   - pymdownx.keys
 ```
 
-  [15]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_keys.scss
+  [13]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_keys.scss
-  [16]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/
+  [14]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/
+
+### SuperFences
+
+The [SuperFences][15] extension, which is also part of [Python Markdown
+Extensions][5], allows for the __nesting of code blocks inside other blocks__,
+and is therefore strongly recommended:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.superfences
+```
+
+  [15]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
+
+### Snippets
+
+The [Snippets][16] extension, which is also part of [Python Markdown
+Extensions][5], allows to __insert content from other files__ or other, regular
+content, and can be enabled via `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+  - pymdownx.snippets
+```
+
+  [16]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
 
 ## Usage
 
@@ -271,11 +281,11 @@ The `#!python range()` function is used to generate a sequence of numbers.
 
   [18]: #inlinehilite
 
-### Displaying keyboard keys
+### Adding keyboard keys
 
 When [Keys][19] is enabled, keyboard keys can be inserted with a simple syntax.
-See the [Python Markdown Extensions][16] documentation for a list of all
+Consult the [Python Markdown Extensions][16] documentation to learn about all
-available keys.
+available short key codes.
 
 _Example_:
 
@@ -288,3 +298,29 @@ _Result_:
 ++ctrl+alt+del++
 
   [19]: #keys
+
+### Adding external files
+
+When [Snippets][20] is enabled, content from other files can be inserted, which
+is especially useful to reference and embed the contents of source files
+directly into your project documentation.
+
+_Example_:
+
+```` markdown
+```
+--8<--​ ".browserslistrc"
+```
+````
+
+_Result_:
+
+```
+--8<-- ".browserslistrc"
+```
+
+Note that [Snippets][20] is not limited to code blocks, but can be used anywhere
+in a Markdown file to put repeating content into separate files, which is also
+explained in the [official documentation][16].
+
+  [20]: #snippets

docs/reference/content-tabs.md

@@ -28,19 +28,16 @@ markdown_extensions:
 
 ### SuperFences
 
-[:octicons-file-code-24: Source][4] · [:octicons-workflow-24: Extension][5]
+The [SuperFences][4] extension, which is also part of [Python Markdown
-
+Extensions][3], allows for the __nesting of code and content blocks inside
-The [SuperFences][5] extension, which is also part of [Python Markdown
+tabs__, and is therefore strongly recommended:
-Extensions][3], allows for the __nesting of code blocks inside tabs__, and is
-therefore strongly recommended:
 
 ``` yaml
 markdown_extensions:
   - pymdownx.superfences
 ```
 
-  [4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_typeset.scss
+  [4]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
-  [5]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
 
 ## Usage
 
@@ -138,9 +135,9 @@ _Result_:
 
 ### Embedded content
 
-Content tabs can contain arbitrary nested content, including further content
+When [SuperFences][5] is enabled, content tabs can contain arbitrary nested
-tabs, and can be nested in other blocks like [admonitions][6], [details][7] or
+content, including further content tabs, and can be nested in other blocks like
-blockquotes:
+[admonitions][6], [details][7] or blockquotes:
 
 _Example_:
 
@@ -216,5 +213,6 @@ _Result_:
         2. Donec vitae suscipit est
         3. Nulla tempor lobortis orci
 
+  [5]: #superfences
   [6]: admonitions.md
   [7]: admonitions.md#details

docs/reference/lists.md

@@ -15,7 +15,7 @@ are supported through extensions.
 
 [:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
 
-The [Definition List][1] extension, which is part of the standard Markdown
+The [Definition List][2] extension, which is part of the standard Markdown
 library, adds the ability to add definitions lists to a document and can be 
 enabled via `mkdocs.yml`:
 

docs/reference/meta-tags.md

@@ -10,7 +10,7 @@ template: overrides/main.html
 
 ### Metadata
 
-[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
+[:octicons-workflow-24: Extension][1]
 
 The [Metadata][1] extension, which is part of the standard Markdown
 library, adds the ability to add custom metadata to a document and can be 
@@ -22,7 +22,6 @@ markdown_extensions:
 ```
 
   [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
-  [2]: https://python-markdown.github.io/extensions/meta_data/
 
 ## Usage
 

docs/setup/adding-a-comment-system.md

@@ -15,9 +15,12 @@ integrated, too.
 
 ### Disqus
 
-First, ensure you've set [`site_url`][2] in `mkdocs.yml`. Then, to integrate
+[:octicons-file-code-24: Source][2] ·
+:octicons-milestone-24: Default: _none_
+
+First, ensure you've set [`site_url`][3] in `mkdocs.yml`. Then, to integrate
 Material for MkDocs with [Disqus][1], create an account and a site giving you a
-[shortname][3], and add it to `mkdocs.yml`:
+[shortname][4], and add it to `mkdocs.yml`:
 
 ``` yaml
 extra:
@@ -26,14 +29,18 @@ extra:
 
 This will insert a comment system on _every page, except the index page_.
 
-  [2]: https://www.mkdocs.org/user-guide/configuration/#site_url
+  [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/integrations/disqus.html
-  [3]: https://help.disqus.com/en/articles/1717111-what-s-a-shortname
+  [3]: https://www.mkdocs.org/user-guide/configuration/#site_url
+  [4]: https://help.disqus.com/en/articles/1717111-what-s-a-shortname
 
 ## Customization
 
 ### Selective integration
 
-If the [Metadata][4] extension is enabled, you can disable or enable Disqus for
+[:octicons-file-code-24: Source][2] ·
+:octicons-mortar-board-24: Difficulty: _easy_
+
+If the [Metadata][5] extension is enabled, you can disable or enable Disqus for
 specific pages by adding the following to the front matter of a page:
 
 === "Enable Disqus"
@@ -52,4 +59,4 @@ specific pages by adding the following to the front matter of a page:
     ---
     ```
 
-  [4]: ../reference/meta-tags.md#metadata
+  [5]: ../reference/meta-tags.md#metadata

docs/setup/adding-a-git-repository.md

@@ -40,11 +40,11 @@ repo_name: squidfunk/mkdocs-material
 ```
 
   [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/source.html
-  [3]: https://www.mkdocs.org/user-guide/configuration/#repo_url
+  [3]: https://www.mkdocs.org/user-guide/configuration/#repo_name
 
 ### Repository icon
 
-[:octicons-file-code-24: Source][1] · :octicons-milestone-24: Default:
+[:octicons-file-code-24: Source][2] · :octicons-milestone-24: Default:
 `fontawesome/brands/git-alt`
 
 While the default _repository icon_ is a generic git icon, it can be set to

docs/setup/changing-the-fonts.md

@@ -30,7 +30,7 @@ theme:
 
 The typeface will be loaded in 300, 400, _400i_ and __700__.
 
-  [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L120-L139
+  [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L116-L140
   [3]: https://fonts.google.com/specimen/Roboto
 
 ### Proportional font

docs/setup/changing-the-logo-and-icons.md

@@ -57,11 +57,11 @@ theme:
 
 ### Icons
 
-[:octicons-file-code-24: Source][5] · [:octicons-workflow-24: Extension][6]
+[:octicons-file-code-24: Source][3] · [:octicons-workflow-24: Extension][5]
 
-The [Emoji][6] extension, which is part of [Python Markdown Extensions][7],
+The [Emoji][5] extension, which is part of [Python Markdown Extensions][6],
 adds the ability to __integrate icons__ in the `*.svg` file format, which are
-inlined into the HTML when [building your site][8]:
+inlined into the HTML when [building your site][7]:
 
 ``` yaml
 markdown_extensions:
@@ -72,19 +72,18 @@ markdown_extensions:
 
 The following icon sets are bundled with Material for MkDocs:
 
-* :material-material-design: – [Material Design][9]
+* :material-material-design: – [Material Design][8]
-* :fontawesome-brands-font-awesome-flag: – [FontAwesome][10]
+* :fontawesome-brands-font-awesome-flag: – [FontAwesome][9]
-* :fontawesome-brands-github: – [Octicons][11]
+* :fontawesome-brands-github: – [Octicons][10]
 
 If you want to add [additional icons][1], read on.
 
-  [5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_emoji.scss
+  [5]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
-  [6]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
+  [6]: https://facelessuser.github.io/pymdown-extensions/
-  [7]: https://facelessuser.github.io/pymdown-extensions/
+  [7]: ../creating-your-site.md#building-your-site
-  [8]: ../creating-your-site.md#building-your-site
+  [8]: https://materialdesignicons.com/
-  [9]: https://materialdesignicons.com/
+  [9]: https://fontawesome.com/icons?d=gallery&m=free
-  [10]: https://fontawesome.com/icons?d=gallery&m=free
+  [10]: https://octicons.github.com/
-  [11]: https://octicons.github.com/
 
 ## Customization
 
@@ -93,10 +92,10 @@ If you want to add [additional icons][1], read on.
 [:octicons-file-code-24: Source][3] · 
 :octicons-mortar-board-24: Difficulty: _moderate_
 
-In order to add additional icons, [extend the theme][13] and create a folder
+In order to add additional icons, [extend the theme][11] and create a folder
-named `.icons` in the [`custom_dir`][14] you want to use for overrides. Next,
+named `.icons` in the [`custom_dir`][12] you want to use for overrides. Next,
 add your `*.svg` icons into a subfolder of the `.icons` folder. Let's say you 
-downloaded and unpacked the [Bootstrap][15] icon set, and want to add it to
+downloaded and unpacked the [Bootstrap][13] icon set, and want to add it to
 your project documentation. The structure of your project should look like this:
 
 ``` sh
@@ -125,6 +124,6 @@ markdown_extensions:
 You should now be able to use the :fontawesome-brands-bootstrap: Bootstrap
 icons.
 
-  [13]: ../customization.md#extending-the-theme
+  [11]: ../customization.md#extending-the-theme
-  [14]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
+  [12]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
-  [15]: https://icons.getbootstrap.com/
+  [13]: https://icons.getbootstrap.com/

docs/setup/setting-up-site-analytics.md

@@ -47,7 +47,7 @@ search tracking:
 
 ### Using other analytics services
 
-[:octicons-file-code-24: Source][2] · 
+[:octicons-file-code-24: Source][3] ·
 :octicons-mortar-board-24: Difficulty: _easy_
 
 In order to integrate another analytics service provider offering an
@@ -65,7 +65,7 @@ and [override the `analytics` block][6]:
 
 ### Using instant loading
 
-[:octicons-file-code-24: Source][2] · 
+[:octicons-file-code-24: Source][3] ·
 :octicons-mortar-board-24: Difficulty: _easy_
 
 If you're using [instant loading][7], you may use the `location$` observable,