diff --git a/CHANGELOG b/CHANGELOG index 51176cc9c..74181b2bd 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,3 +1,7 @@ +mkdocs-material-7.0.7+insiders-2.5.0 (2021-03-28) + + * Added support for version warning + mkdocs-material-7.0.7 (2021-03-28) * Updated Hungarian translations diff --git a/docs/assets/screenshots/version-warning.png b/docs/assets/screenshots/version-warning.png new file mode 100644 index 000000000..d7262c4d0 Binary files /dev/null and b/docs/assets/screenshots/version-warning.png differ diff --git a/docs/customization.md b/docs/customization.md index c81eb50e3..a54e8b8ef 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -193,6 +193,7 @@ Material for MkDocs provides the following template blocks: | `hero` | Wraps the hero teaser (if available) | | `htmltitle` | Wraps the `` tag | | `libs` | Wraps the JavaScript libraries (header) | +| `outdated` | Wraps the version warning | | `scripts` | Wraps the JavaScript application (footer) | | `source` | Wraps the linked source files | | `site_meta` | Wraps the meta tags in the document head | diff --git a/docs/insiders/changelog.md b/docs/insiders/changelog.md index 3e529aa8e..635960226 100644 --- a/docs/insiders/changelog.md +++ b/docs/insiders/changelog.md @@ -6,6 +6,10 @@ template: overrides/main.html ## Material for MkDocs Insiders +### 2.5.0 <small>_ March 28, 2021</small> + +- Added support for version warning + ### 2.4.0 <small>_ March 20, 2021</small> - Added support for custom admonition icons diff --git a/docs/insiders/index.md b/docs/insiders/index.md index c7dc99788..1e7f9811b 100644 --- a/docs/insiders/index.md +++ b/docs/insiders/index.md @@ -111,15 +111,16 @@ The following features are currently exclusively available to sponsors: <div class="mdx-columns" markdown="1"> -- [x] [Custom admonition icons :material-new-box:][27] +- [x] [Version warning :material-new-box:][26] +- [x] [Custom admonition icons :material-new-box:][28] - [x] [Code block annotations :material-new-box:][25] -- [x] [Back-to-top button :material-new-box:][17] +- [x] [Back-to-top button][17] - [x] [Anchor tracking ][24] - [x] [Section index pages][22] - [x] [Latest release tag][15] - [x] [Color palette toggle][16] - [x] [Sticky navigation tabs][21] -- [x] [Mermaid.js integration][26] +- [x] [Mermaid.js integration][27] - [x] [Search suggestions][18] - [x] [Search highlighting][19] - [x] [Search sharing][20] @@ -175,18 +176,19 @@ the public for general availability. - [x] [Anchor tracking][24] - [x] [Code block annotations][25] -- [ ] Non-latest version warning +- [x] [Version warning][26] [24]: ../setup/setting-up-navigation.md#anchor-tracking [25]: ../reference/code-blocks.md#adding-annotations +[26]: ../setup/setting-up-versioning#version-warning #### $ 5,000 – Aji Panca -- [x] [Mermaid.js integration][26] +- [x] [Mermaid.js integration][27] - [ ] List of last searches - [ ] Advanced routing for versioning - [26]: ../reference/diagrams.md + [27]: ../reference/diagrams.md #### $ 6,000 – Trinidad Scorpion @@ -202,19 +204,19 @@ the public for general availability. #### $ 8,000 - Scotch Bonnet -- [x] [Custom admonition icons][27] +- [x] [Custom admonition icons][28] - [ ] TBA - [ ] TBA - [27]: ../reference/admonitions.md#changing-the-icons + [28]: ../reference/admonitions.md#changing-the-icons #### Future -- [ ] [Material for MkDocs Live Edit][28] +- [ ] [Material for MkDocs Live Edit][29] - [ ] New layouts and styles - [ ] Code block palette toggle - [28]: https://twitter.com/squidfunk/status/1338252230265360391 + [29]: https://twitter.com/squidfunk/status/1338252230265360391 ### Goals completed @@ -260,10 +262,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][29] only in CI, as you don't want to expose +recommended to [install Insiders][30] only in CI, as you don't want to expose your `GH_TOKEN` to users. - [29]: ../publishing-your-site.md#github-pages + [30]: ../publishing-your-site.md#github-pages ### Terms @@ -272,7 +274,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][30]. However, we kindly ask you to respect the following +by the [MIT license][31]. However, we kindly ask you to respect the following guidelines: - Please __don't distribute the source code__ of Insiders. You may freely use @@ -283,7 +285,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][31]. + [GitHub deletes private forks][32]. - [30]: ../license.md - [31]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository + [31]: ../license.md + [32]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository diff --git a/docs/setup/setting-up-versioning.md b/docs/setup/setting-up-versioning.md index a7b80977c..2941474f5 100644 --- a/docs/setup/setting-up-versioning.md +++ b/docs/setup/setting-up-versioning.md @@ -66,6 +66,46 @@ Material for MkDocs._ [5]: https://github.com/jimporter/mike#why-use-mike [6]: https://github.com/jimporter/mike#usage +### Version warning + +[:octicons-file-code-24: Source][7] · +[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][7]{ .mdx-insiders } + +If you're using versioning, you might want to display a warning when the user +visits any other version than the latest version. Using [theme extension][8], +you can [define the `outdated` block][9]: + +``` html +{% block outdated %} + You're not viewing the latest version. + <a href="{{ config.site_url | url }}"> + Click here to go to latest. + </a> +{% endblock %} +``` + +This will render a version warning above the header: + +[![Version warning][10]][10] + +By default, the default version is identified by the `latest` alias. If you +wish to set another alias as the latest version, e.g. `stable`, add the +following to `mkdocs.yml`: + +``` yaml +extra: + version: + default: stable +``` + +Make sure that this matches the [default version][11]. + + [7]: ../insiders/index.md + [8]: ../customization.md#extending-the-theme + [9]: ../customization.md#overriding-blocks + [10]: ../assets/screenshots/version-warning.png + [11]: #setting-a-default-version + ## Usage While this section outlines the basic workflow for publishing new versions,