Added documentation for back-to-top button

CHANGELOG

@@ -1,3 +1,7 @@
+mkdocs-material-7.0.5+insiders-2.3.0 (2021-03-13)
+
+  * Added support for back-to-top button
+
 mkdocs-material-7.0.5 (2021-03-07)
 
   * Added extracopyright block to allow for custom copyright info

docs/changelog/insiders.md

@@ -6,6 +6,10 @@ template: overrides/main.html
 
 ## Material for MkDocs Insiders
 
+### 2.3.0 <small>_ March 13, 2021</small>
+
+-  Added support for back-to-top button
+
 ### 2.2.1 <small>_ March 4, 2021</small>
 
 - Fixed #2382: Repository stats failing when no release tag is present

docs/insiders.md

@@ -112,17 +112,18 @@ The following features are currently exclusively available to sponsors:
 
 <div class="mdx-columns" markdown="1">
 
-- [x] [Code block annotations :material-new-box:][24]
+- [x] [Code block annotations :material-new-box:][25]
-- [x] [Anchor tracking :material-new-box:][23]
+- [x] [Anchor tracking :material-new-box:][24]
-- [x] [Section index pages][21]
+- [x] [Back-to-top button :material-new-box:][17]
+- [x] [Section index pages][22]
 - [x] [Latest release tag][15]
 - [x] [Color palette toggle][16]
-- [x] [Sticky navigation tabs][20]
+- [x] [Sticky navigation tabs][21]
-- [x] [Mermaid.js integration][25]
+- [x] [Mermaid.js integration][26]
-- [x] [Search suggestions][17]
+- [x] [Search suggestions][18]
-- [x] [Search highlighting][18]
+- [x] [Search highlighting][19]
-- [x] [Search sharing][19]
+- [x] [Search sharing][20]
-- [x] [Remove generator notice][22]
+- [x] [Remove generator notice][23]
 
 </div>
 
@@ -144,47 +145,48 @@ the public for general availability.
 
 - [x] [Latest release tag][15]
 - [x] [Color palette toggle][16]
-- [ ] Code block palette toggle
+- [x] [Back-to-top button][17]
 
   [15]: setup/adding-a-git-repository.md#latest-release
   [16]: setup/changing-the-colors.md#color-palette-toggle
+  [17]: setup/setting-up-navigation.md#back-to-top-button
 
 #### $ 2,500 – Biquinho Vermelho
 
-- [x] [Search suggestions][17]
+- [x] [Search suggestions][18]
-- [x] [Search highlighting][18]
+- [x] [Search highlighting][19]
-- [x] [Search sharing][19]
+- [x] [Search sharing][20]
 
-  [17]: setup/setting-up-site-search.md#search-suggestions
+  [18]: setup/setting-up-site-search.md#search-suggestions
-  [18]: setup/setting-up-site-search.md#search-highlighting
+  [19]: setup/setting-up-site-search.md#search-highlighting
-  [19]: setup/setting-up-site-search.md#search-sharing
+  [20]: setup/setting-up-site-search.md#search-sharing
 
 #### $ 3,000 – Caribbean Red
 
-- [x] [Sticky navigation tabs][20]
+- [x] [Sticky navigation tabs][21]
-- [x] [Section index pages][21]
+- [x] [Section index pages][22]
-- [x] [Remove generator notice][22]
+- [x] [Remove generator notice][23]
 
-  [20]: setup/setting-up-navigation.md#sticky-navigation-tabs
+  [21]: setup/setting-up-navigation.md#sticky-navigation-tabs
-  [21]: setup/setting-up-navigation.md#section-index-pages
+  [22]: setup/setting-up-navigation.md#section-index-pages
-  [22]: setup/setting-up-the-footer.md#remove-generator
+  [23]: setup/setting-up-the-footer.md#remove-generator
 
 #### $ 4,000 – Ghost Pepper
 
-- [x] [Anchor tracking][23]
+- [x] [Anchor tracking][24]
-- [x] [Code block annotations][24]
+- [x] [Code block annotations][25]
-- [ ] Back-to-top button
+- [ ] Non-latest version warning
 
-[23]: setup/setting-up-navigation.md#anchor-tracking
+[24]: setup/setting-up-navigation.md#anchor-tracking
-[24]: reference/code-blocks.md#adding-annotations
+[25]: reference/code-blocks.md#adding-annotations
 
 #### $ 5,000 – Aji Panca
 
-- [x] [Mermaid.js integration][25]
+- [x] [Mermaid.js integration][26]
 - [ ] List of last searches
 - [ ] Advanced routing for versioning
 
-  [25]: reference/diagrams.md
+  [26]: reference/diagrams.md
 
 #### $ 6,000 – Trinidad Scorpion
 
@@ -200,10 +202,11 @@ the public for general availability.
 
 #### Future
 
-- [ ] [Material for MkDocs Live Edit][26]
+- [ ] [Material for MkDocs Live Edit][27]
 - [ ] New layouts and styles
+- [ ] Code block palette toggle
 
-  [26]: https://twitter.com/squidfunk/status/1338252230265360391
+  [27]: https://twitter.com/squidfunk/status/1338252230265360391
 
 ### Goals completed
 
@@ -249,10 +252,10 @@ implemented behind feature flags; all configuration changes are
 backward-compatible. This means that your users will be able to build the
 documentation locally with Material for MkDocs and when they push their changes,
 it can be built with Insiders (e.g. as part of GitHub Actions). Thus, it's
-recommended to [install Insiders][27] only in CI, as you don't want to expose
+recommended to [install Insiders][28] only in CI, as you don't want to expose
 your `GH_TOKEN` to users.
 
-  [27]: publishing-your-site.md#github-pages
+  [28]: publishing-your-site.md#github-pages
 
 ### Terms
 
@@ -261,7 +264,7 @@ commercial project. Can we use Insiders under the same terms and conditions?_
 
 Yes. Whether you're an individual or a company, you may use _Material for MkDocs
 Insiders_ precisely under the same terms as Material for MkDocs, which are given
-by the [MIT license][28]. However, we kindly ask you to respect the following
+by the [MIT license][29]. However, we kindly ask you to respect the following
 guidelines:
 
 - Please __don't distribute the source code__ of Insiders. You may freely use
@@ -272,7 +275,7 @@ guidelines:
 - If you cancel your subscription, you're removed as a collaborator and will
   miss out on future updates of Insiders. However, you may __use the latest
   version__ that's available to you __as long as you like__. Just remember that
-  [GitHub deletes private forks][29].
+  [GitHub deletes private forks][30].
 
-  [28]: license.md
+  [29]: license.md
-  [29]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository
+  [30]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository

docs/setup/setting-up-navigation.md

@@ -230,11 +230,42 @@ Note that it doesn't rely on third-party plugins[^2]._
   [17]: #navitation-intergation
   [18]: https://github.com/oprypin/mkdocs-section-index
 
+### Back-to-top button
+
+[:octicons-file-code-24: Source][9] ·
+:octicons-unlock-24: Feature flag ·
+[:octicons-heart-fill-24:{: .mdx-heart } Insiders only][9]{: .mdx-insiders }
+
+A _back-to-top button_ can be shown when the user, after scrolling down, starts
+to scroll up again. It's rendered in the lower right corner of the viewport. Add
+the following lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+  features:
+    - navigation.top
+```
+
+<figure markdown="1">
+
+[![back-to-top button][19]][19]
+
+  <figcaption markdown="1">
+
+A demo is worth a thousand words — check it out at
+[squidfunk.github.io/mkdocs-material-insiders][20]
+
+  </figcaption>
+</figure>
+
+  [19]: ../assets/screenshots/back-to-top.png
+  [20]: https://squidfunk.github.io/mkdocs-material-insiders/setup/setting-up-navigation/#back-to-top-button
+
 ### Table of contents
 
-[:octicons-file-code-24: Source][19] · [:octicons-workflow-24: Extension][20]
+[:octicons-file-code-24: Source][21] · [:octicons-workflow-24: Extension][22]
 
-The [Table of contents][21] extension, which is part of the standard Markdown
+The [Table of contents][23] extension, which is part of the standard Markdown
 library, provides some options that are supported by Material for MkDocs to
 customize its appearance:
 
@@ -266,7 +297,7 @@ customize its appearance:
 :   :octicons-milestone-24: Default: `headerid.slugify` – This option allows for 
     customization of the slug function. For some languages, the default may not
     produce good and readable identifiers – consider using another slug function
-    like for example those from [Python Markdown Extensions][22]:
+    like for example those from [Python Markdown Extensions][24]:
 
     === "Unicode"
 
@@ -311,14 +342,14 @@ _Material for MkDocs doesn't provide official support for the other options of
 this extension, so they may be supported but can also yield weird results. Use
 them at your own risk._
 
-  [19]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html
+  [21]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html
-  [20]: https://python-markdown.github.io/extensions/toc/
+  [22]: https://python-markdown.github.io/extensions/toc/
-  [21]: https://python-markdown.github.io/extensions/toc/#usage
+  [23]: https://python-markdown.github.io/extensions/toc/#usage
-  [22]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
+  [24]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
 
 #### Navigation integration
 
-[:octicons-file-code-24: Source][23] ·
+[:octicons-file-code-24: Source][25] ·
 :octicons-unlock-24: Feature flag
 
 When _integration_ is enabled, the table of contents is rendered as part of
@@ -333,14 +364,14 @@ theme:
 
 === "Integrate table of contents"
 
-    [![Integrate table of contents][24]][24]
+    [![Integrate table of contents][26]][26]
 
 === "Separate table of contents"
 
     [![Separate table of contents][8]][8]
 
-  [23]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/layout/_nav.scss
+  [25]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/layout/_nav.scss
-  [24]: ../assets/screenshots/toc-integrate.png
+  [26]: ../assets/screenshots/toc-integrate.png
 
 The content section will now always stretch to the right side, resulting in
 more space for your content. This feature flag can be combined with all other
@@ -348,12 +379,12 @@ feature flags, e.g. [tabs][1] and [sections][2].
 
 ### Hide the sidebars
 
-[:octicons-file-code-24: Source][25] ·
+[:octicons-file-code-24: Source][27] ·
 :octicons-note-24: Metadata
 
 Sometimes it's desirable to hide the navigation and/or table of contents
 sidebar, especially when there's a single navigation item. This can be done for
-any page using the [Metadata][26] extension:
+any page using the [Metadata][28] extension:
 
 ``` yaml
 ---
@@ -377,17 +408,17 @@ hide:
 
     [![Hide navigation and table of contents][29]][29]
 
-  [25]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
+  [27]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
-  [26]: ../../reference/meta-tags/#metadata
+  [28]: ../../reference/meta-tags/#metadata
-  [27]: ../assets/screenshots/hide-navigation.png
+  [29]: ../assets/screenshots/hide-navigation.png
-  [28]: ../assets/screenshots/hide-toc.png
+  [30]: ../assets/screenshots/hide-toc.png
-  [29]: ../assets/screenshots/hide-navigation-toc.png
+  [31]: ../assets/screenshots/hide-navigation-toc.png
 
 ## Customization
 
 ### Keyboard shortcuts
 
-[:octicons-file-code-24: Source][30] ·
+[:octicons-file-code-24: Source][32] ·
 :octicons-mortar-board-24: Difficulty: _easy_
 
 Material for MkDocs includes several keyboard shortcuts that make it possible
@@ -413,7 +444,7 @@ to navigate your project documentation via keyboard. There're two modes:
     * ++n++ , ++period++ : go to next page
 
 Let's say you want to bind some action to the ++x++ key. By using [additional
-JavaScript][31], you can subscribe to the `keyboard$` observable and attach
+JavaScript][33], you can subscribe to the `keyboard$` observable and attach
 your custom event listener:
 
 ``` js
@@ -429,12 +460,12 @@ The call to `#!js key.claim()` will essentially execute `#!js preventDefault()`
 on the underlying event, so the keypress will not propagate further and touch
 other event listeners.
 
-  [30]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts
+  [32]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts
-  [31]: ../customization.md#additional-javascript
+  [33]: ../customization.md#additional-javascript
 
 ### Content area width
 
-[:octicons-file-code-24: Source][32] ·
+[:octicons-file-code-24: Source][34] ·
 :octicons-mortar-board-24: Difficulty: _easy_
 
 The width of the content area is set so the length of each line doesn't exceed
@@ -443,7 +474,7 @@ is a reasonable default, as longer lines tend to be harder to read, it may be
 desirable to increase the overall width of the content area, or even make it
 stretch to the entire available space.
 
-This can easily be achieved with an [additional stylesheet][33] and a few lines
+This can easily be achieved with an [additional stylesheet][35] and a few lines
 of CSS:
 
 === "Increase width"
@@ -462,5 +493,5 @@ of CSS:
     }
     ```
 
-  [32]: https://github.com/squidfunk/mkdocs-material/blob/aeaa00a625abf952f355164de02c539b061e6127/src/assets/stylesheets/main/layout/_base.scss
+  [34]: https://github.com/squidfunk/mkdocs-material/blob/aeaa00a625abf952f355164de02c539b061e6127/src/assets/stylesheets/main/layout/_base.scss
-  [33]: ../customization.md#additional-css
+  [35]: ../customization.md#additional-css