mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-11-23 23:21:00 +01:00
Added documentation for back-to-top button
This commit is contained in:
squidfunk
parent
dbad649181
commit
3750f61015
@ -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
|
||||
|
||||
BIN
docs/assets/screenshots/back-to-top.png
Normal file
BIN
docs/assets/screenshots/back-to-top.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 173 KiB |
@ -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
|
||||
|
||||
@ -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] [Anchor tracking :material-new-box:][23]
|
||||
- [x] [Section index pages][21]
|
||||
- [x] [Code block annotations :material-new-box:][25]
|
||||
- [x] [Anchor tracking :material-new-box:][24]
|
||||
- [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] [Mermaid.js integration][25]
|
||||
- [x] [Search suggestions][17]
|
||||
- [x] [Search highlighting][18]
|
||||
- [x] [Search sharing][19]
|
||||
- [x] [Remove generator notice][22]
|
||||
- [x] [Sticky navigation tabs][21]
|
||||
- [x] [Mermaid.js integration][26]
|
||||
- [x] [Search suggestions][18]
|
||||
- [x] [Search highlighting][19]
|
||||
- [x] [Search sharing][20]
|
||||
- [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 highlighting][18]
|
||||
- [x] [Search sharing][19]
|
||||
- [x] [Search suggestions][18]
|
||||
- [x] [Search highlighting][19]
|
||||
- [x] [Search sharing][20]
|
||||
|
||||
[17]: 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-sharing
|
||||
[18]: setup/setting-up-site-search.md#search-suggestions
|
||||
[19]: setup/setting-up-site-search.md#search-highlighting
|
||||
[20]: setup/setting-up-site-search.md#search-sharing
|
||||
|
||||
#### $ 3,000 – Caribbean Red
|
||||
|
||||
- [x] [Sticky navigation tabs][20]
|
||||
- [x] [Section index pages][21]
|
||||
- [x] [Remove generator notice][22]
|
||||
- [x] [Sticky navigation tabs][21]
|
||||
- [x] [Section index pages][22]
|
||||
- [x] [Remove generator notice][23]
|
||||
|
||||
[20]: setup/setting-up-navigation.md#sticky-navigation-tabs
|
||||
[21]: setup/setting-up-navigation.md#section-index-pages
|
||||
[22]: setup/setting-up-the-footer.md#remove-generator
|
||||
[21]: setup/setting-up-navigation.md#sticky-navigation-tabs
|
||||
[22]: setup/setting-up-navigation.md#section-index-pages
|
||||
[23]: setup/setting-up-the-footer.md#remove-generator
|
||||
|
||||
#### $ 4,000 – Ghost Pepper
|
||||
|
||||
- [x] [Anchor tracking][23]
|
||||
- [x] [Code block annotations][24]
|
||||
- [ ] Back-to-top button
|
||||
- [x] [Anchor tracking][24]
|
||||
- [x] [Code block annotations][25]
|
||||
- [ ] Non-latest version warning
|
||||
|
||||
[23]: setup/setting-up-navigation.md#anchor-tracking
|
||||
[24]: reference/code-blocks.md#adding-annotations
|
||||
[24]: setup/setting-up-navigation.md#anchor-tracking
|
||||
[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]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository
|
||||
[29]: license.md
|
||||
[30]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository
|
||||
|
||||
@ -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
|
||||
[20]: https://python-markdown.github.io/extensions/toc/
|
||||
[21]: https://python-markdown.github.io/extensions/toc/#usage
|
||||
[22]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
|
||||
[21]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html
|
||||
[22]: https://python-markdown.github.io/extensions/toc/
|
||||
[23]: https://python-markdown.github.io/extensions/toc/#usage
|
||||
[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
|
||||
[24]: ../assets/screenshots/toc-integrate.png
|
||||
[25]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/layout/_nav.scss
|
||||
[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
|
||||
[26]: ../../reference/meta-tags/#metadata
|
||||
[27]: ../assets/screenshots/hide-navigation.png
|
||||
[28]: ../assets/screenshots/hide-toc.png
|
||||
[29]: ../assets/screenshots/hide-navigation-toc.png
|
||||
[27]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
|
||||
[28]: ../../reference/meta-tags/#metadata
|
||||
[29]: ../assets/screenshots/hide-navigation.png
|
||||
[30]: ../assets/screenshots/hide-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
|
||||
[31]: ../customization.md#additional-javascript
|
||||
[32]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts
|
||||
[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
|
||||
[33]: ../customization.md#additional-css
|
||||
[34]: https://github.com/squidfunk/mkdocs-material/blob/aeaa00a625abf952f355164de02c539b061e6127/src/assets/stylesheets/main/layout/_base.scss
|
||||
[35]: ../customization.md#additional-css
|
||||
|
||||
Loading…
Reference in New Issue
Block a user