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

Mục Lục

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

The original i12bretro video is embedded directly; the video link is preserved rather than rehosting assets.²

Install Docker on Linux

Log into the Linux device and run:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# 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:

1
2
3
4
5
6
7
8
# 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:

1
2
3
4
# stop the container
docker stop mkdocs
# edit the mkdocs configuration file
sudo nano ~/docker/mkdocs/mkdocs.yml

Add this exact line to mkdocs.yml:

1
theme: readthedocs

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

1
2
# 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) ↩︎ ↩︎ ↩︎ ↩︎ ↩︎
https://www.youtube.com/watch?v=Fnx8w_uqyuM — Run MkDocs - Read the Docs Alternative - in Docker (official video) ↩︎

AIoT.IO.VN