Home

How to install and run mkdocs

The CS2030 website uses mkdocs. Here is how to run mkdocs on your own laptop. First, you need to install Python 3 (I did not manage to get it to work on Python 2).

Then run:

pip install mkdocs
pip install mkdocs-material
pip install pymdown-extensions

to install mkdocs, the material theme, and various markdown extensions.

Note that on some system, you may need to run pip3 instead of pip.

Warning: if you use Homebrew on mac, brew install mkdocs will install mkdocs for you, but it may choose to use Python 2 instead of Python 3, causing the emoji extension to fail. Use pip install mkdocs instead.

To run:

mkdocs serve

will generate the HTML files and you can then view it locally on your browser by pointing your browser to http://localhost:8000.

Running

mkdocs gh-deploy

will publish whatever changes you made locally for the world to see, even if you have not committed the changes. Please be very careful and use this only if you know what you are doing

Further Readings

• The mkdocs homepage
• The PyMDown extensions documentation