Bootstrap 4 theme for MkDocs

A vanilla Bootstrap 4 theme.

Screenshot

Quick start

First install the package:

$ pip install mkdocs-theme-bootstrap4

Then enable it:

theme:
    name: bootstrap4

Configuration

Place these additional options under the theme: section of your mkdocs.yml configuration to change the theme's behaviour.

# Show next/previous links between pages?
next_previous: true

Bootstrap features

Some Bootstrap components require the addition of additional CSS classes. To enable these, add the following plugins in mkdocs.yml:

plugins:
    - bootstrap4-blockquotes
    - bootstrap4-tables

Hacking

First, install the dependencies:

• Python 2, for some of our dependencies.
• Python 3, for the package build process.
• Yarn, for managing frontend dependencies.

Ensure that Python 2 is found on your path before Python 3, else you'll get errors from node-gyp later. If you're unable to do this, set the environment variable npm_config_python to a command that'll launch Python 2 (py -2 on Windows, python2 elsewhere).

On Windows:

• It's easiest to not put Python on your path and instead rely on the py CLI.
• You'll need the build tools necessary to install native dependencies: npm install -g --production windows-build-tools.

To get completion working in your editor, set up a virtual environment in the root of this repository and install MkDocs:

$ pip3 install --user --upgrade setuptools twine wheel
$ python3 -m venv venv
$ . venv/bin/activate
$ pip install -r requirements.txt

To install the plugin onto a local MkDocs site in editable form:

$ pip install --editable /path/to/mkdocs-theme-bootstrap4

Upgrading dependencies

To upgrade the dependencies, install pip-upgrader:

. venv/bin/activate
pip install -r requirements.dev.txt

Then proceed to update the dependencies:

pip-upgrade requirements.dev.txt

The node dependencies can be updated with Yarn:

yarn upgrade

Releasing

Build the distributable package:

$ python3 setup.py sdist bdist_wheel

Push it to the PyPI test instance:

$ python3 -m twine upload --repository-url https://test.pypi.org/legacy/ dist/*

Test it inside a virtual environment:

$ pip install --index-url https://test.pypi.org/simple/ --no-deps mkdocs-drawio-exporter

Let's go live:

$ python3 -m twine upload dist/*