Skip to content

Python venv cheat sheet for MKDocs

MKDocs is an easy-to-use python static site generator that makes writing and publishing to the web a breeze. But you firstly need a virtual python environment on your local machine, as long as it's not an immutable distro you will be fine. read about Nixos here

Installation

Make sure python is installed on your computer. It's best to first set up a python virtual environment, that will only contain the python packages that are specific to your particular project.

This allows us to separate the global python on your pc, and will make it easier to manage your machine and your projects going forward.

Venv can be used easily for this purpose, with the following command:

python3 -m venv blog
The placeholder "blog" denotes the path to the virtual environment that you want to create.

You now need to activate the environment with the following command:

On Linux:

source blog/bin/activate

On Windows:

blog\Scripts\activate.bat

Please ensure that the virtual environment is activated

For this command to work, make sure you are in the same directory where the virtual environment was installed. If sucessful, on the shell you will see a parenthesis on the left hand side with the name of the activated virtual environment. In this case you should see (blog) johnny@linux:~/$

Next you can continue to install the python libraries that you need for your project using pip.

pip install mkdocs

All subsequent python packages and libraries will be installed only to the virtual environment that you have created. This keeps your system clean and avoids conflicts with global python.

When you're finished developing your specific project, you can deactivate the virtual environment by simply typing:

deactivate 

Python uses a configuration file that lists all the packages used for a particular project called "requirements.txt"

While in the activated virtual environment, you can run the following command to create this file:

pip freeze > requirements.txt

This file can later be used to deploy specific python code dependencies to a production server or another computer.

For full documentation visit mkdocs.org

MKDocs commands

  • mkdocs new [dir-name] - create a new project
  • mkdocs serve - Start the live reloading docs server
  • mkdocs build - Build the documentation site
  • mkdocs -h - Print the help message and exit

Project layout

mkdocs.yml    # The configuration file.
docs/
    index.md  # The documentation homepage.
    ...       # Other makedown pages, images and other files