Skip to content

Commit fbf84de

Browse files
committed
setting-up-versioning.md: explain "stay on the same page" feature
While the feature is supposed to work out of the box, there are a few non-obvious conditions required for it to function.
1 parent 9259251 commit fbf84de

File tree

1 file changed

+21
-1
lines changed

1 file changed

+21
-1
lines changed

docs/setup/setting-up-versioning.md

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -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

137151
Note 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

Comments
 (0)