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

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

Cài Docker trên Linux

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

# 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

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

1. Tạo thư mục, đặt quyền và chạy 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. Mở http://DNSorIP:8000.
3. Kiểm tra MkDocs đã chạy.¹

Đổi theme Read the Docs

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

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

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

theme: readthedocs

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

# restart the containerdocker start mkdocs

5. 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, mình 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

Footnotes

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