MkDocs Getting Started

MKDocs is a documentation oriented static website builder using a single .yml config file. Documents are written in Markdown. Sounds great.


For full instructions see

For my MacOS:

  1. Virtual environment:
  2. Git initialised with a remote repo.
  3. With Basic .gitignore
pip install mkdocs
pip install mkdocs-build-plantuml-plugin
pip freeze > requirements.txt
git push

MkDocs is installed here with the plantUML plugin.

Create a Project#

mkdocs new <project-name>
cd <project-name>

Run the Server#

To run the built-in mkDocs server at

mkdocs serve

Create Menu Items#

All configuration is carried out in mkdocs.yml unless otherwise stated.

	- Home:
	- About:

Add a Theme#

There are many to choose from. I choose material. Full instructions can be found here.

pip install mkdocs-material

And in the config file:

theme: material

This appears to be a very complete theme with settings galore.

Add Favicon#

Create an assets/images/ folder inside your project folder. Include a favicon.ico file.

	favicion: /assets/images/favicon.ico

Build the Site#

To generate the static html site, run:

makedocs build


See MkDocs-Build-Plantuml-Plugin for full details.

The documentation is really clear, although I may return to record here my experiences in the future as the possibilities of fine-tuning a solution are complex.