https://github.com/redislabs/mkdocs-versions-menu
An MkDocs plugin that generates a versions menu for the mkdocs-material theme.
https://github.com/redislabs/mkdocs-versions-menu
Last synced: 12 months ago
JSON representation
An MkDocs plugin that generates a versions menu for the mkdocs-material theme.
- Host: GitHub
- URL: https://github.com/redislabs/mkdocs-versions-menu
- Owner: RedisLabs
- License: mit
- Created: 2020-03-13T13:30:17.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-10-10T19:48:45.000Z (over 2 years ago)
- Last Synced: 2025-06-16T13:04:52.226Z (about 1 year ago)
- Language: Python
- Size: 20.5 KB
- Stars: 2
- Watchers: 5
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# mkdocs-versions-menu
This MkDocs plugin generates a versions menu from the branches of a git repository. It is intended to be used with the [mkdocs-material](https://github.com/squidfunk/mkdocs-material) theme.
It does the following when enabled in a docs repo:
* It injects the required [theme](mkdocs_versions_menu/theme) files, but allows customization if these are provided by the docs
* For the latest branch, it copies the docs to site/x.y
* For other branches, it moves the docs to site/x.y
* It generates supporting Javascript glue for tying it all together
Inspired by: https://github.com/containous/structor
## Requirements
* The [mkdocs-material](https://github.com/squidfunk/mkdocs-material) theme
* A git docs repository
## Setup
Install the plugin using pip:
`pip install git+https://github.com/RedisLabs/mkdocs-versions-menu.git`
Activate the plugin in `mkdocs.yml`:
```yaml
plugins:
- search
- versions-menu:
exclude-regexes:
- '(?!.*)'
include-regex: '([0-9]+)\.([0-9]+)'
require-release-tag: yes
release-tag-regex: v([0-9]+)\\.([0-9]+)\\.([0-9]+)'
master-branch: 'master'
master-text: 'Master'
css-path: 'css'
javascript-path: 'javascript'
```
> **Note:** If you have no `plugins` entry in your config file yet, you'll likely also want to add the `search` plugin. MkDocs enables it by default if there is no `plugins` entry set, but now you have to enable it explicitly.
More information about plugins in the [MkDocs documentation](https://www.mkdocs.org/user-guide/plugins/).
## Config
* `exclude-regexes` - a list of branch regexes to exclude (default: ['(?!.*)'], i.e. nothing)
* `include-regexes` - a string regex of branches to include, where `\$1` is the major version and `\$2` is the minor (default: '([0-9]+)\.([0-9]+)')
* `require-release-tag` - a boolean controlling whether included branches should have at least one tag (default: True)
* `release-tag-regex` - a string regex for release tags (default: 'v([0-9]+)\\.([0-9]+)\\.([0-9]+)')
* `master-branch` - a string name of the master branch, if set to '' then no master (default: 'master')
* `master-text` - a string text to display for master branch (defaults to capitalized form of `master-branch`)
* `css-path` - the site's css relative path (default: 'css')
* `javascript-path` - the site's Javascript relative path (default: 'javascript')
## Usage