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 https://www.mkdocs.org/getting-started/
For my MacOS:
- Virtual environment:
- Git initialised with a remote repo.
- 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
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
Full instructions can be found here.
pip install mkdocs-material
And in the config file:
This appears to be a very complete theme with settings galore.
assets/images/ folder inside your project folder. Include a
theme: favicion: /assets/images/favicon.ico
Build the Site#
To generate the static html site, run:
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.