Skip to content

mkdocs

These are notes on mkdocs from deploying a mkdocs site for my notes.

mkdocs is a Python-based tool used to build static websites, geared towards technical documentation.

Setting up MkDocs

These are setup notes for a MkDocs website.

  1. For local testing, use a virtual environment.

    sudo apt-get install -y python3.10-venv  # to get the venv module
sudo apt-get install -y python3.10-venv --fix-missing  # if install doesn't work

    • This is a Debian-based install. For RedHat-based distros, the venv module should be available as long as python3 is installed.
      sudo dnf install -y python3

  2. Once the Python venv module is installed, create the virtual environment and activate it by sourcing the venv/bin/activate script.

    cd ~/tech-notes
python3 -m venv venv
. venv/bin/activate

  3. Verify you're in the virtual environment.

    type python3
# /home/kolkhis/tech-notes/venv/bin/python3

  4. Install mkdocs and a theme for mkdocs.

    pip install mkdocs mkdocs-material

  5. Initialize the mkdocs project.

    mkdocs new .

    • This initializes a new mkdocs project in the current directory (.).
    • It creates a baseline mkdocs.yml file and a docs/ directory with an index.md file.

  6. Add any markdown files you want to serve via the docs site into the docs/ directory.

    cp -r *.md docs/

  7. Add all files to the mkdocs.yml file in the nav section to serve them.

    site_name: MyDocs
nav:

  - Home: index.md
  - Other Page: other-file.md

MkDocs Project Structure

In the root of the repo, you need a docs/ directory.
You also need a mkdocs.yml file in the repo root.

The directory structure of my notes directory is fine for mkdocs, but it all needs to be in the docs/ directory instead of the root.

Resources