@@ -56,6 +56,20 @@ Check out the versioning example to see it in action –
5656 [version example] : https://squidfunk.github.io/mkdocs-material-example-versioning/
5757 [Why use mike?] : https://github.com/jimporter/mike#why-use-mike
5858
59+ # ## Stay on the same page when switching versions
60+
61+ When the user chooses a version in the version selector, they usually want to go
62+ to the page corresponding to the page they were previously viewing. Material for
63+ MkDocs implements this behavior by default, but there are a few caveats :
64+
65+ - the [`site_url`] must be set correctly in `mkdocs.yml`. See the ["Publishing a
66+ new version"](#publishing-a-new-version) section for an example.
67+ - you must be viewing the site at that URL (and not locally, for example).
68+ - the redirect happens via JavaScript and there is no way to know which page you
69+ will be redirected to ahead of time.
70+
71+ [`site_url`] : https://www.mkdocs.org/user-guide/configuration/#site_url
72+
5973# ## Version warning
6074
6175[:octicons-tag-24 : 8.0.0][Version warning support] ·
@@ -135,7 +149,13 @@ mike deploy --push --update-aliases 0.1 latest
135149` ` `
136150
137151Note that every version will be deployed as a subdirectory of your `site_url`,
138- e.g. :
152+ which you should set explicitly. For example, if your `mkdocs.yml` contains :
153+
154+ ` ` ` yaml
155+ site_url: 'https://docs.example.com/' # Trailing slash is recommended
156+ ` ` `
157+
158+ the documentation will be published to URLs such as :
139159
140160- _docs.example.com/0.1/_
141161- _docs.example.com/0.2/_
0 commit comments