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 prerequisitessudo apt install apt-transport-https ca-certificates git curl software-properties-common gnupg-agent -y# add docker gpg keycurl -fsSL https://download.docker.com/linux/$(awk -F'=' '/^ID=/{ print $NF }' /etc/os-release)/gpg | sudo apt-key add -# add docker software repositorysudo 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 dockersudo apt install docker-ce docker-compose containerd.io -y# enable and start docker servicesudo systemctl enable docker && sudo systemctl start docker# add the current user to the docker groupsudo usermod -aG docker $USER# reauthenticate for the new group membership to take effectsu - $USER

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

Run MkDocs

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

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

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

Switch to the Read the Docs theme

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

# stop the containerdocker stop mkdocs# edit the mkdocs configuration filesudo nano ~/docker/mkdocs/mkdocs.yml

2. Add this exact line to mkdocs.yml:

theme: readthedocs

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

# restart the containerdocker start mkdocs

5. 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

Footnotes

1. https://i12bretro.github.io/tutorials/0986.html — Run MkDocs - Read the Docs Alternative - in Docker (i12bretro) ↩ ↩² ↩³ ↩⁴ ↩⁵