diff --git a/docs/assets/screenshots/versioning.png b/docs/assets/screenshots/versioning.png new file mode 100644 index 000000000..37212b0f6 Binary files /dev/null and b/docs/assets/screenshots/versioning.png differ diff --git a/docs/creating-your-site.md b/docs/creating-your-site.md index 0496a4ec0..42d7369bf 100644 --- a/docs/creating-your-site.md +++ b/docs/creating-your-site.md @@ -71,11 +71,12 @@ icons and much more: * [Setting up navigation][7] * [Setting up site search][8] * [Setting up site analytics][9] -* [Setting up the header][10] -* [Setting up the footer][11] -* [Adding a git repository][12] -* [Adding a comment system][13] - +* [Setting up versioning][10] +* [Setting up the header][11] +* [Setting up the footer][12] +* [Adding a git repository][13] +* [Adding a comment system][14] + [2]: getting-started.md#installation [3]: setup/changing-the-colors.md @@ -85,11 +86,12 @@ icons and much more: [7]: setup/setting-up-navigation.md [8]: setup/setting-up-site-search.md [9]: setup/setting-up-site-analytics.md - [10]: setup/setting-up-the-header.md - [11]: setup/setting-up-the-footer.md - [12]: setup/adding-a-git-repository.md - [13]: setup/adding-a-comment-system.md - + [10]: setup/setting-up-versioning.md + [11]: setup/setting-up-the-header.md + [12]: setup/setting-up-the-footer.md + [13]: setup/adding-a-git-repository.md + [14]: setup/adding-a-comment-system.md + ## Previewing as you write diff --git a/docs/setup/setting-up-versioning.md b/docs/setup/setting-up-versioning.md new file mode 100644 index 000000000..a88d4b6b4 --- /dev/null +++ b/docs/setup/setting-up-versioning.md @@ -0,0 +1,97 @@ +--- +template: overrides/main.html +--- + +# 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][1]. When deploying a new version, older versions of your +documentation remain untouched. + + [1]: https://github.com/jimporter/mike + +## Configuration + +### Versioning + +[:octicons-file-code-24: Source][2] · +[:octicons-package-24: Utility][1] · +:octicons-beaker-24: Experimental · +[:octicons-heart-fill-24:{: .tx-heart } Insiders only][2]{: .tx-insiders } + +[mike][1] 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: + method: mike +``` + +This will render a version selector in the header next to the title of your +project: + +[![Versioning][3]][3] + +_Note that you don't need to run `mike install-extras` as noted in the +[official documentation][4], as [mike][1] is now natively integrated with +Material for MkDocs._ + +!!! quote "[Why use mike?][5]" + + 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 + `.` 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. + + [2]: ../insiders.md + [3]: ../assets/screenshots/versioning.png + [4]: https://github.com/jimporter/mike#usage + [5]: https://github.com/jimporter/mike#why-use-mike + +## Usage + +While this section outlines the basic workflow for publishing new versions, +it's best to check out the [official documentation][4] to make yourself familar +with [mike][1]. + +### Setting a default version + +When starting with [mike][1], 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 latest +``` + +When publishing a new version, [mike][1] 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_ + +### Publishing a new version + +If you want to publish a new version of your project documentation, choose a new +version identifier and update the alias set as the default version with: + +``` +mike deploy --push --update-aliases 0.2 latest +``` + +_docs.example.com_ :octicons-arrow-right-24: _docs.example.com/0.2_ + +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_ +- ... diff --git a/mkdocs.yml b/mkdocs.yml index 4a84083e9..21d5764b5 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -162,6 +162,7 @@ nav: - Setting up navigation: setup/setting-up-navigation.md - Setting up site search: setup/setting-up-site-search.md - Setting up site analytics: setup/setting-up-site-analytics.md + - Setting up versioning: setup/setting-up-versioning.md - Setting up the header: setup/setting-up-the-header.md - Setting up the footer: setup/setting-up-the-footer.md - Adding a git repository: setup/adding-a-git-repository.md