Skip to content

Mkdocs

MkDocs is a fast, and simple static site generator. It's mainly used for building project documentation. But also very usable for simple websites like this. Documentation source files are written in Markdown, like the one you're reading now.

Installation & Usage

When you follow the installation instructions on the mkdocs website, will quickly run into issues when using theme's. The easiest solution is to use the manual installation instructions and install it via pip.

  • Install command pip install mkdocs
  • Test if it works mkdocs --version

In the getting started page, you'll find the commands you need to start using mkdocs.

  • Create a new project mkdocs new my-project
  • Navigate to the dir cd my-project
  • Start the server to see changes on the fly in the browser mkdocs serve or mkdocs serve -a 0.0.0.0:8000
  • Side note: Don't use serve as a webserver. The proper was is to copy the files after building to the Apache folder
  • Build command mkdocs build and I always use mkdocs build --clean
  • Write your docs and place them in the /docs folder
  • Also adjust mkdocs.yml to include each file as a page in the nav: section

Theme's

On the mkdocs website there is a nice page about styling your docs. Use the build in themes or any third party theme you can find. I'm using material which can be found on GitHub. In general these are the steps to take:

  1. First we need to install the theme (I installed 'Material')
  2. Make sure it's installed properly mkdocs --version
  3. Adjust mkdocs.yml and Add theme: material

Auto sync to Apache & NAS

For this I use a cronjob and rsync, like this:

# m h  dom mon dow   command
30 * * * * rsync -ua --delete ~/blog/ /var/www/html/
31 * * * * rsync -us --delete ~/blog/ /home/pi/myNASfolder
# Make sure you mounted the NAS folder first, see the mount manual