Added guide for navigation configuration

docs/creating-your-site.md

@@ -34,7 +34,7 @@ This will create the following structure:
 └─ mkdocs.yml
 ```
 
-  [1]: ../getting-started.md
+  [1]: getting-started.md
 
 ## Configuration
 
@@ -66,7 +66,7 @@ icons and much more:
 * [Changing colors][3]
 * [Changing the fonts][4]
 * [Changing the language][5]
-* [Navigation structure][6]
+* [Navigation][6]
 * [Syntax highlighting][7]
 * [Adding a landing page][8]
 * [Adding an announcement bar][9]
@@ -75,18 +75,18 @@ icons and much more:
 * [Adding site analytics][12]
 * [Adding a comment system][13]
 
-  [2]: ../getting-started.md#installation
+  [2]: getting-started.md#installation
-  [3]: ../guides/changing-colors.md
+  [3]: guides/changing-colors.md
-  [4]: ../guides/changing-the-fonts.md
+  [4]: guides/changing-the-fonts.md
-  [5]: ../guides/changing-the-language.md
+  [5]: guides/changing-the-language.md
-  [6]: ../guides/navigation-structure.md
+  [6]: guides/navigation.md
-  [7]: ../guides/syntax-highlighting.md
+  [7]: guides/syntax-highlighting.md
-  [8]: ../guides/adding-a-landing-page.md
+  [8]: guides/adding-a-landing-page.md
-  [9]: ../guides/adding-an-announcement-bar.md
+  [9]: guides/adding-an-announcement-bar.md
-  [10]: ../guides/adding-icons-and-emojis.md
+  [10]: guides/adding-icons-and-emojis.md
-  [11]: ../guides/adding-footer-links.md
+  [11]: guides/adding-footer-links.md
-  [12]: ../guides/adding-site-analytics.md
+  [12]: guides/adding-site-analytics.md
-  [13]: ../guides/adding-a-comment-system.md
+  [13]: guides/adding-a-comment-system.md
 
 ## Previewing as you write
 
@@ -117,7 +117,7 @@ Point your browser to [localhost:8000][14] and you should see:
 [![Creating your site][15]][14]
 
   [14]: http://localhost:8000
-  [15]: ../assets/guides/creating-your-site.png
+  [15]: assets/guides/creating-your-site.png
 
 ## Building your site
 

docs/customization.md

@@ -135,7 +135,7 @@ theme. This can be done with any file.
 ### Overriding blocks
 
 Besides overriding partials, it's also possible to override (and extend) so
-called *blocks*, which are defined inside the templates and wrap specific
+called _blocks_, which are defined inside the templates and wrap specific
 features. To override a block, create a `main.html` inside the `overrides`
 directory and define the block, e.g.:
 
@@ -152,11 +152,11 @@ Material for MkDocs provides the following template blocks:
 | Block name   | Wrapped contents                                |
 | ------------ | ----------------------------------------------- |
 | `analytics`  | Wraps the Google Analytics integration          |
-| `announce`   | Wraps the Announcement bar                      |
+| `announce`   | Wraps the announcement bar                      |
 | `config`     | Wraps the JavaScript application config         |
 | `content`    | Wraps the main content                          |
-| `disqus`     | Wraps the disqus integration                    |
+| `disqus`     | Wraps the Disqus integration                    |
-| `extrahead`  | Empty block to define additional meta tags      |
+| `extrahead`  | Empty block to add custom meta tags             |
 | `fonts`      | Wraps the font definitions                      |
 | `footer`     | Wraps the footer with navigation and copyright  |
 | `header`     | Wraps the fixed header bar                      |
@@ -230,7 +230,7 @@ in front of you.
 
   [10]: http://localhost:8000
 
-### Build process
+### Building the theme
 
 When you're finished making your changes, you can build the theme by invoking:
 

docs/data-privacy.md

@@ -25,12 +25,12 @@ theme:
   font: false
 ```
 
-When Google Fonts are disabled, Material for MkDocs will default to **Helvetica
+When Google Fonts are disabled, Material for MkDocs will default to __Helvetica
-Neue** and **Monaco** with their corresponding fall backs, relying on system
+Neue__ and __Monaco__ with their corresponding fall backs, relying on system
 fonts. You can easily include your own, self-hosted webfont by [overriding][4]
 the `fonts` block.
 
-  [2]: ../guides/changing-the-fonts.md
+  [2]: guides/changing-the-fonts.md
   [3]: https://github.com/google/fonts/issues/1495
   [4]: customization.md#overriding-template-blocks
 

docs/extensions/permalinks.md

@@ -1,37 +0,0 @@
----
-template: overrides/main.html
----
-
-# Permalinks
-
-Permalinks are a feature of the [Table of Contents][1] extension, which is part
-of the standard Markdown library. The extension inserts an anchor at the end of
-each headline, which makes it possible to directly link to a specific section
-of the document.
-
-  [1]: https://python-markdown.github.io/extensions/toc/
-
-## Configuration
-
-Add the following lines to `mkdocs.yml`:
-
-``` yaml
-markdown_extensions:
-  - toc:
-      permalink: true
-```
-
-This will add a link containing the paragraph symbol `¶` at the end of each
-headline (exactly like on the page you're currently viewing), which Material
-for MkDocs will make appear on hover. In order to change the text of the
-permalink, a string can be passed, e.g.:
-
-``` yaml
-markdown_extensions:
-  - toc:
-      permalink: Link
-```
-
-## Usage
-
-When enabled, permalinks are inserted automatically.

docs/extensions/pymdown.md

@@ -57,7 +57,7 @@ extra_javascript:
 ```
 
 If you want to override the default MathJax configuration, you can do this by
-adding another JavaScript file **before** the MathJax runtime which contains
+adding another JavaScript file __before__ the MathJax runtime which contains
 the MathJax configuration, e.g.:
 
 ``` js
@@ -130,7 +130,7 @@ Lorem ipsum dolor sit amet: $p(x|y) = \frac{p(y|x)p(x)}{p(y)}$
 
 ### BetterEm
 
-[BetterEm][6] improves the handling of emphasis markup (**bold** and *italic*)
+[BetterEm][6] improves the handling of emphasis markup (__bold__ and _italic_)
 within Markdown by providing a more sophisticated parser for better detecting
 start and end tokens. Read the documentation for [usage notes][7].
 

docs/getting-started.md

@@ -14,7 +14,7 @@ In case you're running into problems, consult the [troubleshooting][4] section.
   [1]: https://www.mkdocs.org
   [2]: #with-pip
   [3]: #with-docker
-  [4]: getting-started/troubleshooting.md
+  [4]: troubleshooting.md
 
 ## Installation
 

docs/guides/changing-colors.md

@@ -6,7 +6,7 @@ template: overrides/main.html
 
 As any good Material Design implementation, Material for MkDocs supports
 Google's original [color palette][1], which can be easily configured through 
-`mkdocs.yml`. Furthermore, colors can be adjusted with a few lines of CSS to
+`mkdocs.yml`. Furthermore, colors can be customized with a few lines of CSS to
 fit your brand identity by using [CSS variables][2].
 
   [1]: http://www.materialui.co/colors
@@ -52,11 +52,11 @@ scheme:
 <script>
   var buttons = document.querySelectorAll("button[data-md-color-scheme]")
   buttons.forEach(function(button) {
-    var attr = "data-md-color-scheme"
     button.addEventListener("click", function() {
+      var attr = this.getAttribute("data-md-color-scheme")
+      document.body.setAttribute("data-md-color-scheme", attr)
       var name = document.querySelector("#__code_0 code span:nth-child(7)")
-      document.body.setAttribute(attr, this.getAttribute(attr))
+      name.textContent = attr
-      name.textContent = this.getAttribute(attr)
     })
   })
 </script>
@@ -130,11 +130,11 @@ color:
 <script>
   var buttons = document.querySelectorAll("button[data-md-color-primary]")
   buttons.forEach(function(button) {
-    var attr = "data-md-color-primary"
     button.addEventListener("click", function() {
+      var attr = this.getAttribute("data-md-color-primary")
+      document.body.setAttribute("data-md-color-primary", attr)
       var name = document.querySelector("#__code_2 code span:nth-child(7)")
-      document.body.setAttribute(attr, this.getAttribute(attr))
+      name.textContent = attr.replace("-", " ")
-      name.textContent = this.getAttribute(attr)
     })
   })
 </script>
@@ -192,17 +192,27 @@ color:
 <script>
   var buttons = document.querySelectorAll("button[data-md-color-accent]")
   buttons.forEach(function(button) {
-    var attr = "data-md-color-accent"
     button.addEventListener("click", function() {
+      var attr = this.getAttribute("data-md-color-accent")
+      document.body.setAttribute("data-md-color-accent", attr)
       var name = document.querySelector("#__code_3 code span:nth-child(7)")
-      document.body.setAttribute(attr, this.getAttribute(attr))
+      name.textContent = attr.replace("-", " ")
-      name.textContent = this.getAttribute(attr)
     })
   })
 </script>
 
   [5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/palette/_accent.scss
 
+---
+
+!!! warning "Accessibility – not all color combinations work well"
+
+    With __2__ (color schemes) __x 21__ (primary colors) __x 17__ (accent color)
+    = __714__ combinations, it's impossible to ensure that all configurations
+    provide a good user experience (e.g. _yellow on light background_), so make
+    sure that the color combination of your choosing provides enough contrast
+    and tweak CSS variables where necessary.
+
 ## Customization
 
 Material for MkDocs implements colors using [CSS variables][6] (custom
@@ -267,16 +277,7 @@ colors or neutral colors:
 ```
 
   [6]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
-  [7]: ../getting-started/customization.md#additional-stylesheets
+  [7]: ../customization.md#additional-stylesheets
   [8]: ../extensions/codehilite.md
   [9]: ../extensions/admonition.md
 
-## Caveats
-
-!!! warning "Accessibility – not all color combinations work well"
-
-    With __2__ (color schemes) __x 21__ (primary colors) __x 17__ (accent color)
-    = __714__ combinations, it's impossible to ensure that all configurations
-    provide a good user experience (e.g. _yellow on light background_), so make
-    sure that the color combination of your choosing provides enough contrast
-    and tweak CSS variables where necessary.

docs/guides/changing-the-fonts.md

@@ -27,7 +27,7 @@ theme:
     text: Roboto
 ```
 
-The typeface will be loaded in 300, 400, *400i* and **700**.
+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
   [3]: https://fonts.google.com/specimen/Roboto
@@ -93,6 +93,6 @@ The font can then be configured to be used as the regular or proportional font:
     }
     ```
 
-  [5]: ../getting-started/data-privacy.md
+  [5]: ../data-privacy.md
-  [6]: ../getting-started/customization.md#overriding-blocks
+  [6]: ../customization.md#overriding-blocks
-  [7]: ../getting-started/customization.md#additional-stylesheets
+  [7]: ../customization.md#additional-stylesheets

docs/guides/changing-the-language.md

@@ -5,9 +5,8 @@ template: overrides/main.html
 # Changing the language
 
 Material for MkDocs supports internationalization (i18n) and provides
-translation keys for all template variables and labels in 40+ languages.
+translations for template variables and labels in 40+ languages. Additionally,
-Additionally, search can be configured to use a language-specific stemmer
+search can be configured to use a language-specific stemmer (if available).
-(if available).
 
 ## Configuration
 
@@ -89,11 +88,25 @@ The following languages are supported:
 
   [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/language/en.html
 
-### Directionality
+### Site search
 
 [:octicons-file-code-24: Source][2] · :octicons-tools-24: Default: best match
 for `theme.language`, automatically set
 
+Some languages, like Arabic or Japanese, need dedicated stemmers for search to
+work properly. Material for MkDocs relies on [lunr-languages][3] to provide this 
+functionality. See the [search plugin documentation][4] for more information.
+
+  [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/main/index.ts#L49-L69
+  [3]: https://github.com/MihaiValentin/lunr-languages
+  [4]: ../plugins/search.md#language
+
+
+### Directionality
+
+[:octicons-file-code-24: Source][5] · :octicons-tools-24: Default: best match
+for `theme.language`, automatically set
+
 While many languages are read `ltr` (left-to-right), Material for MkDocs also
 supports `rtl` (right-to-left) directionality which is inferred from the
 selected language, but can also be set with:
@@ -127,17 +140,13 @@ directionality:
 <script>
   var buttons = document.querySelectorAll("button[data-md-dir]")
   buttons.forEach(function(button) {
-    var attr = "data-md-dir"
     button.addEventListener("click", function() {
+      var attr = this.getAttribute("data-md-dir")
+      document.body.dir = attr
       var name = document.querySelector("#__code_1 code span:nth-child(5)")
-      document.body.dir = this.getAttribute(attr)
+      name.textContent = attr
-      name.textContent = this.getAttribute(attr)
     })
   })
 </script>
 
-  [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L180
+  [5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L168
-
-### Search
-
-TBD

docs/guides/navigation.md

@@ -0,0 +1,183 @@
+---
+template: overrides/main.html
+---
+
+# Navigation
+
+A clear and concise navigation structure is an important aspect of good project 
+documentation. Material for MkDocs provides several options to configure the
+behavior of navigational elements, some of those through _feature flags_.
+
+## Configuration
+
+### Instant loading
+
+[:octicons-file-code-24: Source][1] · :octicons-beaker-24: Experimental · 
+:octicons-unlock-24: Feature flag
+
+When _instant loading_ is activated, clicks on all internal links will be
+intercepted and dispatched via [XHR][2] without fully reloading the page. It
+can be enabled from `mkdocs.yml` with:
+
+``` yaml
+theme:
+  features:
+    - instant
+```
+
+The resulting page is parsed and injected and all event handlers and components
+are automatically rebound. This means that __Material for MkDocs behaves like a
+Single Page Application__, which is especially useful for large documentation
+sites that come with a huge search index, as the search index will now remain
+intact in-between document switches.
+
+  [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/instant/index.ts
+  [2]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
+
+### Tabs navigation
+
+[:octicons-file-code-24: Source][3] · :octicons-unlock-24: Feature flag
+
+When _tabs_ are activated, top-level sections are rendered in a menu layer
+below the header on big screens (but not when the sidebar is hidden). It can be
+enabled from `mkdocs.yml` with:
+
+``` yaml
+theme:
+  features:
+    - tabs
+```
+
+Note that all __top-level pages__ (i.e. all top-level entries that directly
+refer to an `*.md` file) defined inside the `nav` entry of `mkdocs.yml` will be
+grouped under the first tab which will receive the title of the first page.
+
+This means that there will effectively be no collapsible subsections for the
+first tab, because each subsection is rendered as another tab. If you want more
+fine-grained control, _i.e. collapsible subsections for the first tab_, you can
+use __top-level sections__, so that the top-level is entirely made up of
+sections. This is illustrated in the following example:
+
+=== "Top-level pages"
+
+    ``` yaml
+    nav:
+      - Tab 1
+      - Page 1.1
+      - Tab 2:
+        - Page 2.1
+        - Page 2.2
+      - Page 1.2
+    ```
+
+=== "Top-level sections"
+
+    ``` yaml
+    nav:
+      - Tab 1:
+        - Page 1.1
+        - Page 1.2
+      - Tab 2:
+        - Page 2.1
+        - Page 2.2
+    ```
+
+Note that tabs are only shown for larger screens, so make sure that navigation
+is plausible on mobile devices. As another example, see the [`mkdocs.yml`][4]
+used to render these pages.
+
+[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/tabs.html
+[4]: https://github.com/squidfunk/mkdocs-material/blob/master/mkdocs.yml
+
+### Table of contents
+
+[:octicons-file-code-24: Source][5] · [:octicons-workflow-24: Extension][6]
+
+The [Table of Contents][7] extension, which is part of the standard Markdown
+library, provides some options that are supported by Material for MkDocs to
+customize its appearance.
+
+`permalink`
+
+:   This options adds an anchor link containing the paragraph symbol `¶` or
+    another custom symbol at the end of each headline, exactly like on the page
+    you're currently viewing, which Material for MkDocs will make appear on
+    hover:
+
+    === "¶"
+
+        ``` yaml
+        markdown_extensions:
+          - toc:
+              permalink: true
+        ```
+
+    === "⚓︎"
+
+        ``` yaml
+        markdown_extensions:
+          - toc:
+              permalink: ⚓︎
+        ```
+
+    === "Link"
+
+        ``` yaml
+        markdown_extensions:
+          - toc:
+              permalink: Link
+        ```
+
+`slugify`
+
+:   This option allows for customization of the slug function. For some
+    languages, the standard slug function may not produce good and readable
+    identifiers. Consider using another slug function like for example those
+    from [PyMdown Extensions][8]:
+
+    === "Unicode"
+
+        ``` yaml
+        markdown_extensions:
+          - toc:
+              slugify: pymdownx.slugs.uslugify
+        ```
+
+    === "Casing"
+
+        ``` yaml
+        markdown_extensions:
+          - toc:
+              slugify: pymdownx.slugs.uslugify_cased
+        ```
+
+`toc_depth`
+
+:   Define the range of levels to be included in the table of contents. This is
+    especially useful for project documentation with deeply structured headings
+    to decrease the length of the table of contents, or to remove the table of
+    contents altogether:
+
+    === "Hide levels 4-6"
+
+        ``` yaml
+        markdown_extensions:
+          - toc:
+              toc_depth: 3
+        ```
+
+    === "Hide table of contents"
+
+        ``` yaml
+        markdown_extensions:
+          - toc:
+              toc_depth: 0
+        ```
+
+_Material for MkDocs doesn't provide official support for the other options of
+this extension, so they may yield weird results. Use them at your own risk._
+
+  [5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html
+  [6]: https://python-markdown.github.io/extensions/toc/
+  [7]: https://python-markdown.github.io/extensions/toc/#usage
+  [8]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/

docs/releases/5.md

@@ -158,8 +158,8 @@ The templates have undergone a set of changes to make them future-proof. If
 you've used theme extension to override a block or template, make sure that it 
 matches the new structure:
 
-- If you've overridden a **block**, check `base.html` for potential changes
+- If you've overridden a __block__, check `base.html` for potential changes
-- If you've overridden a **template**, check the respective `*.html` file for
+- If you've overridden a __template__, check the respective `*.html` file for
   potential changes
 
 #### `base.html`

docs/troubleshooting.md

@@ -21,14 +21,14 @@ When you're running the pre-installed version of Python on macOS, `pip` tries
 to install packages in a folder for which your user might not have the adequate
 permissions. There are three possible solutions for this:
 
-1. **Installing in a virtual environment**: Virtual environments provide an easy
+1. __Installing in a virtual environment__: Virtual environments provide an easy
    way of encapsulation. 
 
-1. **Installing in user space**: Provide the `--user` flag to the install
+2. __Installing in user space__: Provide the `--user` flag to the install
    command and `pip` will install the package in a user-site location. Note
    that while this is not a global installation, it's still not
 
-2. **Switching to a homebrewed Python**: Upgrade your Python installation to a
+3. __Switching to a homebrewed Python__: Upgrade your Python installation to a
    self-contained solution by installing Python with Homebrew. This should
    eliminate a lot of problems you could be having with `pip`.
 

material/assets/manifest.json

@@ -5,8 +5,8 @@
   "assets/javascripts/vendor.js.map": "assets/javascripts/vendor.568ba93b.min.js.map",
   "assets/javascripts/worker/search.js": "assets/javascripts/worker/search.a68abb33.min.js",
   "assets/javascripts/worker/search.js.map": "assets/javascripts/worker/search.a68abb33.min.js.map",
-  "assets/stylesheets/main.css": "assets/stylesheets/main.ee9eac3c.min.css",
+  "assets/stylesheets/main.css": "assets/stylesheets/main.94fefe80.min.css",
-  "assets/stylesheets/main.css.map": "assets/stylesheets/main.ee9eac3c.min.css.map",
+  "assets/stylesheets/main.css.map": "assets/stylesheets/main.94fefe80.min.css.map",
   "assets/stylesheets/palette.css": "assets/stylesheets/palette.e185632b.min.css",
   "assets/stylesheets/palette.css.map": "assets/stylesheets/palette.e185632b.min.css.map"
 }

material/base.html

@@ -41,7 +41,7 @@
       {% endif %}
     {% endblock %}
     {% block styles %}
-      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.ee9eac3c.min.css' | url }}">
+      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.94fefe80.min.css' | url }}">
       {% if palette.scheme or palette.primary or palette.accent %}
         <link rel="stylesheet" href="{{ 'assets/stylesheets/palette.e185632b.min.css' | url }}">
       {% endif %}

mkdocs.yml

@@ -129,29 +129,28 @@ nav:
   - Home: index.md
   - Getting started:
     - Installation: getting-started.md
-    - Creating your site: getting-started/creating-your-site.md
+    - Creating your site: creating-your-site.md
-    - Publishing your site: getting-started/publishing-your-site.md
+    - Publishing your site: publishing-your-site.md
-    - Customization: getting-started/customization.md
+    - Customization: customization.md
-    - Troubleshooting: getting-started/troubleshooting.md
+    - Troubleshooting: troubleshooting.md
-    - Data privacy: getting-started/data-privacy.md
+    - Data privacy: data-privacy.md
   - Guides:
     - Changing colors: guides/changing-colors.md
     - Changing the fonts: guides/changing-the-fonts.md
     - Changing the language: guides/changing-the-language.md
-    - Navigation structure: guides/navigation-structure.md
+    - Navigation: guides/navigation.md
     - Syntax highlighting: guides/syntax-highlighting.md
     - Adding a landing page: guides/adding-a-landing-page.md
     - Adding an announcement bar: guides/adding-an-announcement-bar.md
     - Adding icons and emojis: guides/adding-icons-and-emojis.md
     - Adding footer links: guides/adding-footer-links.md
     - Adding site analytics: guides/adding-site-analytics.md
-    - Adding a comment systems: guides/adding-a-comment-system.md
+    - Adding a comment system: guides/adding-a-comment-system.md
   - Extensions:
     - Admonition: extensions/admonition.md
     - CodeHilite: extensions/codehilite.md
     - Footnotes: extensions/footnotes.md
     - Metadata: extensions/metadata.md
-    - Permalinks: extensions/permalinks.md
     - PyMdown: extensions/pymdown.md
   - Plugins:
     - Search: plugins/search.md

src/assets/stylesheets/base/_typeset.scss

@@ -383,6 +383,11 @@ kbd {
     }
   }
 
+  // Definition terms
+  dd + dt {
+    margin-top: 1.5em;
+  }
+
   // Limit width to container, scale height proportionally
   img,
   svg {

src/assets/stylesheets/extensions/pymdown/_tasklist.scss

@@ -26,8 +26,12 @@
 
 // Icon definitions
 :root {
-  --md-tasklist-icon: svg-load("@mdi/svg/svg/checkbox-blank-circle.svg");
+  --md-tasklist-icon: svg-load(
-  --md-tasklist-icon--checked: svg-load("@mdi/svg/svg/check-circle.svg");
+    "@primer/octicons/build/svg/check-circle-fill-24.svg"
+  );
+  --md-tasklist-icon--checked: svg-load(
+    "@primer/octicons/build/svg/check-circle-fill-24.svg"
+  );
 }
 
 // ----------------------------------------------------------------------------