MkDocs Getting Started

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

Installation#

For full instructions see https://www.mkdocs.org/getting-started/

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 127.0.0.1:8000

mkdocs serve

Create Menu Items#

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

nav:
	- Home: index.md
	- About: about.md

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.

theme:
	favicion: /assets/images/favicon.ico

Build the Site#

To generate the static html site, run:

makedocs build

PlantUML#

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.