1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
|
# Setting up versioning
Material for MkDocs makes it easy to deploy multiple versions of your project
documentation by integrating with external utilities that add those capabilities
to MkDocs, i.e. [mike]. When deploying a new version, older versions of your
documentation remain untouched.
[mike]: https://github.com/jimporter/mike
## Configuration
### Versioning
<!-- md:version 7.0.0 -->
<!-- md:utility [mike] -->
<!-- md:demo example-versioning -->
[mike] makes it easy to deploy multiple versions of your project documentation.
It integrates natively with Material for MkDocs and can be enabled via
`mkdocs.yml`:
``` yaml
extra:
version:
provider: mike
```
This renders a version selector in the header:
<figure markdown>
[![Version selector preview]][Version selector preview]
<figcaption markdown>
Check out the versioning example to see it in action –
[mkdocs-material.github.io/example-versioning][version example]
</figcaption>
</figure>
!!! quote "[Why use mike?]"
mike is built around the idea that once you've generated your docs for a
particular version, you should never need to touch that version again. This
means you never have to worry about breaking changes in MkDocs, since your
old docs (built with an old version of MkDocs) are already generated and
sitting in your `gh-pages` branch.
While mike is flexible, it's optimized around putting your docs in a
`<major>.<minor>` directory, with optional aliases (e.g. `latest` or `dev`)
to particularly notable versions. This makes it easy to make permalinks to
whatever version of the documentation you want to direct people to.
[Version selector preview]: ../assets/screenshots/versioning.png
[version example]: https://mkdocs-material.github.io/example-versioning/
[Why use mike?]: https://github.com/jimporter/mike#why-use-mike
### Stay on the same page when switching versions
When the user chooses a version in the version selector, they usually want to go
to the page corresponding to the page they were previously viewing. Material for
MkDocs implements this behavior by default, but there are a few caveats:
- the [`site_url`][mkdocs.site_url] must be set correctly in `mkdocs.yml`.
See the ["Publishing a new version"](#publishing-a-new-version) section for
an example.
- the redirect happens via JavaScript and there is no way to know which page you
will be redirected to ahead of time.
### Version warning
<!-- md:version 8.0.0 -->
<!-- md:flag customization -->
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],
you can [override the `outdated` block][overriding blocks]:
``` html
{% extends "base.html" %}
{% block outdated %}
You're not viewing the latest version.
<a href="{{ '../' ~ base_url }}"> <!-- (1)! -->
<strong>Click here to go to latest.</strong>
</a>
{% endblock %}
```
1. Given this value for the `href` attribute, the link will always redirect to
the root of your site, which will then redirect to the latest version. This
ensures that older versions of your site do not depend on a specific alias,
e.g. `latest`, to allow for changing the alias later on without breaking
earlier versions.
This will render a version warning above the header:
[![Version warning preview]][Version warning preview]
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 lines
to `mkdocs.yml`:
``` yaml
extra:
version:
default: stable # (1)!
```
1. You can also define multiple aliases as the default version, e.g. `stable`
and `development`.
``` yaml
extra:
version:
default:
- stable
- development
```
Now every version that has the `stable` and `development` aliases will not
display the version warning.
Make sure one alias matches the [default version], as this is where users are
redirected to.
[theme extension]: ../customization.md#extending-the-theme
[overriding blocks]: ../customization.md#overriding-blocks
[Version warning preview]: ../assets/screenshots/version-warning.png
[default version]: #setting-a-default-version
### Version alias
<!-- md:version 9.5.23 -->
<!-- md:default `false` -->
If you're using aliases for versioning, and want to show the version alias
besides the version number, you can enable this feature by setting the `alias`
option to `true`:
``` yaml
extra:
version:
alias: true
```
## Usage
While this section outlines the basic workflow for publishing new versions,
it's best to check out [mike's documentation][mike] to make yourself familiar
with its mechanics.
### Publishing a new version
If you want to publish a new version of your project documentation, choose a
version identifier and update the alias set as the default version with:
```
mike deploy --push --update-aliases 0.1 latest
```
Note that every version will be deployed as a subdirectory of your `site_url`,
which you should set explicitly. For example, if your `mkdocs.yml` contains:
``` yaml
site_url: 'https://docs.example.com/' # Trailing slash is recommended
```
the documentation will be published to URLs such as:
- _docs.example.com/0.1/_
- _docs.example.com/0.2/_
- ...
### Setting a default version
When starting with [mike], a good idea is to set an alias as a default version,
e.g. `latest`, and when publishing a new version, always update the alias to
point to the latest version:
```
mike set-default --push latest
```
When publishing a new version, [mike] will create a redirect in the root of
your project documentation to the version associated with the alias:
_docs.example.com_ :octicons-arrow-right-24: _docs.example.com/0.1_
|
