diff --git a/CHANGELOG b/CHANGELOG index 806b19076..b5129cc6c 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,3 +1,7 @@ +mkdocs-material-7.1.1+insiders-2.6.0 (2021-04-11) + + * Stay on page when switching versions + mkdocs-material-7.1.1 (2021-04-10) * Fixed #2501: Nested definition lists compound bottom margin diff --git a/docs/insiders/changelog.md b/docs/insiders/changelog.md index 635960226..2bbc65234 100644 --- a/docs/insiders/changelog.md +++ b/docs/insiders/changelog.md @@ -6,6 +6,10 @@ template: overrides/main.html ## Material for MkDocs Insiders +### 2.6.0 _ April 11, 2021 + +- Stay on page when switching versions + ### 2.5.0 _ March 28, 2021 - Added support for version warning diff --git a/docs/insiders/index.md b/docs/insiders/index.md index 7a3c9e3ae..05b208b1d 100644 --- a/docs/insiders/index.md +++ b/docs/insiders/index.md @@ -111,9 +111,10 @@ The following features are currently exclusively available to sponsors:
+- [x] [Stay on page when switching versions :material-new-box:][28] - [x] [Version warning :material-new-box:][26] - [x] [Custom admonition icons :material-new-box:][28] -- [x] [Code block annotations :material-new-box:][25] +- [x] [Code block annotations][25] - [x] [Anchor tracking ][24] - [x] [Section index pages][22] - [x] [Sticky navigation tabs][21] @@ -172,16 +173,17 @@ the public for general availability. #### $ 5,000 – Aji Panca - [x] [Mermaid.js integration][27] +- [x] [Stay on page when switching versions][28] - [ ] List of last searches -- [ ] Advanced routing for versioning [27]: ../reference/diagrams.md + [28]: ../setup/setting-up-versioning#improved-navigation #### $ 6,000 – Trinidad Scorpion - [ ] Improved search result summaries - [ ] Table of contents shows which sections have search results -- [ ] Advanced routing for multi-language sites +- [ ] Stay on page when switching languages #### $ 7,000 – Royal Gold @@ -191,19 +193,19 @@ the public for general availability. #### $ 8,000 – Scotch Bonnet -- [x] [Custom admonition icons][28] +- [x] [Custom admonition icons][29] - [ ] TBA - [ ] TBA - [28]: ../reference/admonitions.md#changing-the-icons + [29]: ../reference/admonitions.md#changing-the-icons #### Future -- [ ] [Material for MkDocs Live Edit][29] +- [ ] [Material for MkDocs Live Edit][30] - [ ] New layouts and styles - [ ] Code block palette toggle - [29]: https://twitter.com/squidfunk/status/1338252230265360391 + [30]: https://twitter.com/squidfunk/status/1338252230265360391 ### Goals completed @@ -258,10 +260,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][30] only in CI, as you don't want to expose +recommended to [install Insiders][31] only in CI, as you don't want to expose your `GH_TOKEN` to users. - [30]: ../publishing-your-site.md#github-pages + [31]: ../publishing-your-site.md#github-pages ### Terms @@ -270,7 +272,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][31]. However, we kindly ask you to respect the following +by the [MIT license][32]. However, we kindly ask you to respect the following guidelines: - Please __don't distribute the source code__ of Insiders. You may freely use @@ -281,7 +283,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][32]. + [GitHub deletes private forks][33]. - [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 + [32]: ../license.md + [33]: 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 2941474f5..2624f9edc 100644 --- a/docs/setup/setting-up-versioning.md +++ b/docs/setup/setting-up-versioning.md @@ -106,6 +106,41 @@ Make sure that this matches the [default version][11]. [10]: ../assets/screenshots/version-warning.png [11]: #setting-a-default-version +### Stay on page + +[:octicons-file-code-24: Source][7] · +[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][7]{ .mdx-insiders } + +Insiders improves the user experience when switching between versions: if +version A and B contain a page with the same path name, the user will stay on +the current page: + +=== "New behavior" + + ``` + docs.example.com/0.1/ -> docs.example.com/0.2/ + docs.example.com/0.1/foo/ -> docs.example.com/0.2/foo/ + docs.example.com/0.1/bar/ -> docs.example.com/0.2/bar/ + ``` + +=== "Old behavior" + + ``` + docs.example.com/0.1/ -> docs.example.com/0.2/ + docs.example.com/0.1/foo/ -> docs.example.com/0.2/ + docs.example.com/0.1/bar/ -> docs.example.com/0.2/ + ``` + +
+
+ +A demo is worth a thousand words — check it out at +[squidfunk.github.io/mkdocs-material-example-versioning][4] + +
+
+ + ## Usage While this section outlines the basic workflow for publishing new versions, @@ -124,8 +159,8 @@ mike deploy --push --update-aliases 0.1 latest Note that every version will be deployed as a subdirectory of your `site_url`, e.g.: -- _docs.example.com/0.1_ -- _docs.example.com/0.2_ +- _docs.example.com/0.1/_ +- _docs.example.com/0.2/_ - ... ### Setting a default version