Run MkDocs in Docker and switch to the Read the Docs theme

MkDocs is a static site generator that uses Markdown and one YAML configuration file to build project documentation. This guide runs the polinux/mkdocs image, stores the project under ~/docker/mkdocs, then stops the container to switch mkdocs.yml to the readthedocs theme.¹

Install Docker on Linux

Log into the Linux device and run:

# install prerequisites
sudo apt install apt-transport-https ca-certificates git curl software-properties-common gnupg-agent -y
# add docker gpg key
curl -fsSL https://download.docker.com/linux/$(awk -F'=' '/^ID=/{ print $NF }' /etc/os-release)/gpg | sudo apt-key add -
# add docker software repository
sudo add-apt-repository "deb [arch=$(dpkg --print-architecture)] https://download.docker.com/linux/$(awk -F'=' '/^ID=/{ print $NF }' /etc/os-release) $(lsb_release -cs) stable"
# install docker
sudo apt install docker-ce docker-compose containerd.io -y
# enable and start docker service
sudo systemctl enable docker && sudo systemctl start docker
# add the current user to the docker group
sudo usermod -aG docker $USER
# reauthenticate for the new group membership to take effect
su - $USER

On a current distribution, apt-key is deprecated; check the Docker documentation if the repository or package no longer matches.¹

Run MkDocs

Create the directory, set ownership, and start the container:

# create working directory
mkdir ~/docker/mkdocs
# set owner of working directories
sudo chown "$USER":"$USER" ~/docker -R
# allow the container to write to working directories
sudo chmod a+rwx -R ~/docker/mkdocs
# run mkdocs container
docker run -d --name=mkdocs -p 8000:8000 -v ~/docker/mkdocs/:/mkdocs --restart=unless-stopped polinux/mkdocs

Open http://DNSorIP:8000.
Verify that MkDocs is running.¹

Switch to the Read the Docs theme

Return to the terminal, stop the container, and open the configuration file:

# stop the container
docker stop mkdocs
# edit the mkdocs configuration file
sudo nano ~/docker/mkdocs/mkdocs.yml

Add this exact line to mkdocs.yml:

theme: readthedocs

Press CTRL+O, Enter, CTRL+X to save and exit.
Start the container again:

# restart the container
docker start mkdocs

Return to the browser and refresh the page.¹

Backup and limits

Back up ~/docker/mkdocs before changing the theme or image. The source uses the latest tag; for a reproducible deployment, pin a compatible tag after checking it rather than accepting unexpected updates.¹

Source and video

Original tutorial: i12bretro 0986
Original video: Run MkDocs - Read the Docs Alternative - in Docker

Sources

https://i12bretro.github.io/tutorials/0986.html — Run MkDocs - Read the Docs Alternative - in Docker (i12bretro) ↩︎ ↩︎ ↩︎ ↩︎ ↩︎