Build a documentation website using markdown.
You can see the slides of this repository at https://hogenttin.github.io/hogent-mkdocs/ . Play with it to see what it can do!
-
Install python .
-
(optional) Create a python environment. E.g. for Linux:
python -m venv venv source ./venv/bin/activate -
Install the dependencies:
pip install --requirement requirements.txt
Edit, add or delete your markdown files in the docs directory, and run mkdocs build to generate the website in the site folder. That's all to get started! 🚀
If you want to edit the sidebar, then just edit the nav entry in mkdocs.yml .
MkDocs allows you to start up a live preview, so you can instantly see how your content looks like whilst editing the markdown files.
mkdocs serveConfiguration
💡 You don't have to change these files or settings if you want to keep things simple. In that case, just ignore this section.
If you want another theme, you can change edit the theme entry in mkdocs.yml. You can find a lot of themes at https://github.com/mkdocs/catalog#-theming .
MkDocs options
You can add them to mkdocs.yml .
MkDocs plugins
You can add additional functionality using MkDocs plugins. These can be enabled by editing mkdocs.yml . E.g., the mkdocs-git-revision-date-localized-plugin plugin for showing the timestamp of the last edit is added in this repo as an example on how to do it.
Additional tools
💡 You don't need this if you want to keep things simple. In that case, just ignore this section. Otherwise, it's here if you want an example.
This repo automatically builds the website and pushes them to https://hogenttin.github.io/hogent-mkdocs/ whenever a commit is pushed to the main branch. This is done using using GitHub actions . You can find the workflow in the .github folder.