Skip to content

Mkdocs

Introduction

What is it

Mkdocs is a documentation generator for projects, which converts markdown to html.

Why we use it

It creates documentation that's pleasing to read and easy to maintain.

Here's a list of features we use
Dead link checker

Github wiki doesn't check for broken links.

Search function

Github wiki is not searcheable.

Tabbed blocks

linux-specific content

mac-specific content

Site table of contents

See the contents of the site in the left sidebar.

Per-page table of contents

See the contents of the current page in the right sidebar.

Code and text annotations 
Click the plus sign --> # (1)!
  1. This is an explanation text
Expandable text blocks

That's what this box is!

Hackforla project template

Todo
  • how to extend to install other plugins in ci.yml and Dockerfile
  • multirepo plugin
  • optimize Dockerfile
  • [people depot] auto merge docs branch with gh-actions

Components

  1. Starter docs to guide the creation of new pages.
  2. Github workflow setup to auto-deploy the documentation.
  3. Docker setup to run mkdocs without having to install it locally

Usage

When we create a new project from the template, mkdocs should already be usable. The github workflow will run automatically and create a github pages site at http://hackforla.github.io/<project name>

  1. Click on Use this template
  2. "Create a new repository"
  3. Be sure to set these options:
    1. Select "Public" repo type, which allows gh-pages to work for non-paying repos.
    2. Check the "Include all branches" box, which copies the gh-pages branch which holds the generated html pages.

To add mkdocs to existing repos. You'll need to copy these files into your project

.github/workflows/ci.yml
docker-compose.mkdocs.yml

You'll also need to create a new mkdocs project

  1. Use the docker image to create the new project
docker-compose -f docker-compose.mkdocs.yml run mkdocs mkdocs new . # (1)!
  1. docker-compose run executes a command from a new docker image container. In this case, inside the mkdocs container, execute mkdocs new . (note the period for the current directory).

Working on docs locally

  1. Run the mkdocs server from the container

    docker-compose -f docker-compse.mkdocs.yml up

  2. Open a browser to http://localhost:8000/ to see the documentation locally

  3. Modify the files in the docs directory. The site will auto-update when the files are saved.

  4. Quit

    Ctrl+C to quit the local server and stop the container

Extension

If your project wants to try other plugins not in the hackforla image, here's a way to extend the image on your own before asking to add it to the hackforla image.

The hackforla image is built from hackforla/mkdocs-docker, where the mkdocs plugins are listed in pyproject.toml.

  1. In ci.yml, add the instruction to install the extnesion

    .github/workflows/ci.yml
          - run: pip install \
          mkdocs-material \
          mkdocs-awesome-pages-plugin \
          ...

  2. Add your own Dockerfile to install the plugin for local usage

    Dockerfile.mkdocs
    # base image
FROM fyliu/local-mkdocs:testing

# set work directory
WORKDIR /app

# install system dependencies
RUN apt-get update \
  && apt-get --no-install-recommends install -y \
  git # mkdocs-multirepo-plugin requires this \
  && apt-get clean \
  && rm -rf /var/lib/apt/lists/*

# install dependencies
# (1)!
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# copy project
COPY . .
    1. Presumably, the extra plugins are specified in requirement.txt to be installed

  3. Modify the docker-compose file to use the new Dockerfile

    docker-compose.mkdocs.yml
    mkdocs:
    #image: fyliu/local-mkdocs:testing
    build:
    context: .
    dockerfile: Dockerfile.mkdocs
    container_name: mkdocs
How we set it up

Github workflow

We're using essentially the same workflow described here.

This builds and publishes the docs on push to the main branch.

.github/workflow/ci.yml
name: ci
on:
  push:
    branches:
      - main
jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write # (1)!
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
        with:
          python-version: 3.x
      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force
  1. Request repo commit permission inside the deploy job.

Docker image

There's a docker image that contains the standard mkdocs setup we use at Hack for LA. It contains all the plugins that projects are using. If your project requires other ones, Either request one to be added to the image or create your own dockerfile for installing them.

Temporarily, the image is in a personal dockerhub repo fyliu/local-mkdocs:testing until it can be moved under a hackforla account. The source repo for the image is here

Projects can use the image by creating a docker-compose.yml file like this

docker-compose.mkdocs.yml
version: "3.9"
services:
  mkdocs:
    image: fyliu/local-mkdocs:testing
    container_name: mkdocs # (1)!
    command: mkdocs serve -a "0.0.0.0:8000"
    ports:
      - "8000:8000" # (2)!
    volumes:
      - .:/app
  1. If the name conflicts with another container, we suggest customizing this with your project name, like mkdocs-engineering or mkdocs-website.
  2. If port 8000 is already in use, change this to something like 8001:8000 to expose it on port 8001.

Mkdocs docker image repo

How to use it

Docker

  1. Build the image

    docker-compose build

  2. Start the container

    docker-compose up

  3. Open a browser to http://localhost:8001/ to see the documentation locally

  4. Modify the files in the docs directory. The site will auto update when the files are saved.

  5. Quit

    Ctrl+C to quit the local server and stop the container

Local Install (pip)

python should be version 3

  1. Install mkdocs

    pip install -r requirements.txt

  2. Start the local server

    mkdocs serve -a localhost:8001

  3. Open a browser to http://localhost:8001/ to see the documentation locally

  4. Modify the files in the docs directory. The site will auto update when the files are saved.

  5. Quit

    Ctrl+C to quit mkdocs

Local Install (poetry)

python poetry must be installed in the local system

  1. Install mkdocs

    poetry install

  2. Start the local server

    poetry shell
mkdocs serve -a localhost:8001

  3. Open a browser to http://localhost:8001/ to see the documentation locally

  4. Modify the files in the docs directory. The site will auto update when the files are saved.

  5. Quit

    Ctrl+C to quit mkdocs

    exit  # (1)!
    1. to close poetry shell environment
How we set it up

Setup from scratch

Here's the recommended setup, from our experience setting it up.

Project directory

mkdir mkdocs-notes && cd $_
git init
git commit —allow-empty -m”Initial commit”

Poetry project

poetry init —name docs —description “Project Documentation” # (1)!
# use a modern stable python like version 3.11.1
# don’t define dependencies interactively
git commit -m”create project for documentation”
  1. We chose poetry because it performs multiple useful functions such as creating the virtual environment and dependency management. It will be easy to update to the latest versions of dependencies.

Mkdocs package

poetry shell # this goes into the poetry virtual environment
poetry add mkdocs —group docs
# group replaces dev dependencies
git add pyproject.toml poetry.lock
git ci -m”add mkdocs package”

Mkdocs project

mkdocs new . # creates mkdocs project in current directory
git add -A # add all untracked files
git ci -m”create mkdocs project”

Local dev server

mkdocs serve —dev-addr 0.0.0.0:8001 # (1)!
  1. Start the dev server locally on any address on port 8001. This is useful for development from a different local network computer, where the default localhost won’t work

Material theme

poetry add mkdocs-material
cat "theme: material" >> mkdocs.yml
git ci -a -m"setup material theme for mkdocs"

Multirepo (not yet working)

poetry add mkdocs-multirepo-plugin
# add the plugin in mkdocs.yml
# import the other repos in mkdocs.yml

Export requirements

We need to export the requirements whenever we add a new package, so that the docker setup and pip users can know to use it.

# (1)!
poetry export -f requirements.txt --without-hashes > requirements.txt --with docs
  1. This is also contained in a script export_requirements.sh in the scripts directory

Deployment to Github Pages

We closely followed this guide. This setup creates a gh-pages branch to store the latest docs. Make the necessary configurations in the Github repo settings as necessary under Pages.

Docker setup

We modified the dockerfile and docker-compose files from People Depot to install and serve mkdocs locally. The files are docker-compose.yml and Dockerfile.