Install mkdocs, mike, mkdocs-material and pdf-export-plugin
python -m pip install -r requirements.txt
You might want to work in a Python virtualenv:
virtualenv --python=/usr/bin/python3 venv/ source venv/bin/activate python -m pip install -r requirements.txt
Important: Each file name needs to be the same as the first heading in each file.
View documentation locally
This command starts a local webserver at localhost:8000.
Add a new version
mike deploy <version> <alias> <-u> <-p>
<version> is the version number of the documentation (e.g. 1.0.0).
<alias> is an alias for this version. Currently, we use the alias
to set the version which is automatically shown when visiting the website.
If the version number (e.g. 1.0.0) already exists, you have to add
update) to the command.
Deploy to Github Pages
To push the content to Github, add
This will build the static files and push to the gh-pages branch on Github, so they will be served automatically at manual.bt-trx.com.
So a complete command might look like this:
mike deploy 1.0.0 latest -u -p
Currently, the mkdocs-pdf-export-plugin can't handle anchors, therefore it is necessary to temporarily alter links containing anchors i.e. from "(../foo#bar)" to "(../foo.md#bar)" to be able to generate a PDF file.
export ENABLE_PDF_EXPORT=1 mkdocs build