Installing MkDocs¶

MkDocs is a clean, simple, yet powerful, static site generator (SSG) that takes markdown text files and turns them into a nicely styled web site. There are many SSGs out there that are excellent too, but this is one that I've been experimenting with lately. It's great for documentation purposes, which is the primary use of this site--to document some of the projects and findings I dig into.

That said, you may want to look into other options. The following is an extensive compilation of static site generators, all worth considering: https://github.com/myles/awesome-static-generators.

If you decide to try out MkDocs, below is a basic set of steps you can use to install it on Windows or Ubuntu, along with the Material theme. Most of this is directly from https://alinex.gitlab.io/env/mkdocs/. Kudos for great info on that site! Once installed, I also suggest checking out the following:

The main MkDocs site of course: https://www.mkdocs.org/
The Material theme documentation: https://squidfunk.github.io/mkdocs-material/
Markdown cheatsheet for MkDocs: https://3os.org/markdownCheatSheet/welcome/
And worth mentioning again: https://alinex.gitlab.io/env/mkdocs/

Windows in WSL¶

I suggest installing in Ubuntu with Windows Services for Linux (WSL) as follows:

Note

This should work identically in a standard Ubuntu host/VM.

Install and update WSL:

sudo apt-get update -y && sudo apt-get upgrade -y

Install necessary packages:

sudo apt install build-essential python3-dev python3-pip python3-setuptools python3-wheel python3-cffi libcairo2 libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf2.0-0 libffi-dev shared-mime-info

Verify version (you will likely get an error here):
```
python --version
pip --version
```
If you get errors, add these aliases to ~/.bashrc:
```
alias python=python3
alias pip=pip3
```
Regardless of whether you got errors above, add the following to the end of ~/.bashrc:
```
PATH=$PATH:~/.local/bin
```
Now source .bashrc:
```
source ~/.bashrc
```

Now install the python packages:

pip install mkdocs
pip install mkdocs-material
pip install pygments
pip install pymdown-extensions
pip install markdown-blockdiag
pip install markdown-include
pip install mkdocs-pdf-export-plugin

That should get it done. Now you can run various MkDocs commands, such as building a new site with mkdocs new <sitename>. Then add and edit markdown files and view them live as HTML in your browser with the mkdocs serve command.