Chạy MkDocs bằng Docker và đổi sang theme Read the Docs

Mục Lục

MkDocs là static site generator dùng Markdown và một file YAML để xây tài liệu dự án. Bài này chạy image polinux/mkdocs, lưu project ở ~/docker/mkdocs, sau đó dừng container để chỉnh mkdocs.yml sang theme readthedocs.¹

Video gốc i12bretro được embed trực tiếp; tôi giữ link video thay vì rehost tài sản.²

Cài Docker trên Linux

Đăng nhập thiết bị Linux, rồi chạy:

 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

Trên distro hiện đại, apt-key đã deprecated; kiểm tra Docker docs nếu repo hoặc package không còn phù hợp.¹

Chạy MkDocs

Tạo thư mục, đặt quyền và chạy 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

Mở http://DNSorIP:8000.
Kiểm tra MkDocs đã chạy.¹

Đổi theme Read the Docs

Quay lại terminal, dừng container và mở file cấu hình:

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

Thêm đúng dòng sau vào mkdocs.yml:

1
theme: readthedocs

Nhấn CTRL+O, Enter, CTRL+X để lưu và thoát.
Khởi động lại container:

1
2
# restart the container
docker start mkdocs

Quay lại trình duyệt và refresh trang.¹

Backup và giới hạn

Backup ~/docker/mkdocs trước khi thay đổi theme hoặc image. Image nguồn dùng latest, vì vậy nếu cần reproducible build, tôi sẽ pin version sau khi kiểm tra tag tương thích thay vì để cập nhật bất ngờ.¹

Nguồn và video

Tutorial gốc: i12bretro 0986
Video gốc: Run MkDocs - Read the Docs Alternative - in Docker

Nguồn

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