Giới thiệu MkDocs

MkDocs là một trình tạo trang web tĩnh dựa trên Python, cho phép chuyển đổi tài liệu định dạng Markdown thành các trang web tĩnh đẹp mắt. MkDocs cung cấp một cách đơn giản và linh hoạt để tạo tài liệu, hỗ trợ nhiều chủ đề và plugin.

Cài đặt MkDocs

Sử dụng lệnh pip để cài đặt MkDocs:

pip install mkdocs

Khởi tạo dự án

Sử dụng lệnh mkdocs new để khởi tạo dự án MkDocs. Lệnh này sẽ tạo ra một dự án với tệp cấu hình và cấu trúc thư mục:

$ python3 -m mkdocs new .
INFO     -  Writing config file: ./mkdocs.yml
INFO     -  Writing initial docs: ./docs/index.md

Sau khi thực thi, trong thư mục gốc dự án sẽ tạo ra thư mục docs và tệp cấu hình mkdocs.yml.

Viết tài liệu

Trong thư mục docs, chỉnh sửa tệp index.md và tạo các tài liệu định dạng Markdown khác.

Cấu hình mkdocs.yml

Trong tệp mkdocs.yml, cấu hình các thông tin như tên trang, mô tả, tác giả, URL, menu điều hướng, v.v.

• site_name: Tên trang
• site_url: Địa chỉ URL của trang
• site_author: Tác giả trang
• site_description: Mô tả trang
• copyright: Thông tin bản quyền
• repo_url: URL của kho chứa trang
• nav: Điều hướng trang
• theme: Chủ đề trang
• markdown_extensions: Mở rộng Markdown

Ví dụ cấu hình tham khảo:

site_name: Python-YApi
site_description: Python Client for YApi base on HTTP apis.
site_author: Nguyen Van A
site_url: http://localhost:8000
copyright: Copyright @ 2023 Nguyen Van A, All rights reserved.
repo_url: https://github.com/nguyena/python-yapi
theme: mkdocs  # chủ đề mặc định

nav:
  - Trang chủ: index.md
  - Hướng dẫn cài đặt: install.md
  - Hướng dẫn sử dụng: usage.md
  - Danh sách module:
      - Quản lý dự án: modules/project.md
      - Quản lý API: modules/interface.md
  - Thông tin tác giả: author.md

Tất cả các tham chiếu tệp đều tương đối so với thư mục docs, hỗ trợ menu và tham chiếu tệp trong thư mục con.

Xem trước trang web

Sử dụng lệnh mkdocs serve để xem trước trang web:

$ python3 -m mkdocs serve

Lệnh này sẽ khởi động một máy chủ địa phương, bạn có thể truy cập http://localhost:8000 trong trình duyệt để xem trang web.

Xuất trang web

Sử dụng lệnh mkdocs build để xuất trang web tĩnh:

$ python3 -m mkdocs build

Lệnh này sẽ tạo các tệp trang web tĩnh và lưu trong thư mục site.

Sử dụng các chủ đề khác

Chủ đề readthedocs

Chỉnh sửa mkdocs.yml và thêm cấu hình chủ đề:

theme: readthedocs

Chủ đề material

Cài đặt mkdocs-material:

pip install mkdocs-material

Chỉnh sửa mkdocs.yml:

theme: material

Thêm mở rộng Markdown

Các mở rộng phổ biến bao gồm toc, footnotes, tables, checklist, v.v. Mở rộng checklist yêu cầu cài đặt plugin bên thứ ba:

pip install markdown-checklist

Thêm cấu hình mở rộng Markdown trong mkdocs.yml:

markdown_extensions:
  - toc:
      permalink: True
  - footnotes
  - tables
  - markdown_checklist.extension

Điều này cho phép sử dụng [toc], - [ ] trong tài liệu.

MkDocs còn cung cấp nhiều tùy chọn cấu hình và plugin phong phú, có thể tùy chỉnh theo nhu cầu. Bạn có thể tham khảo tài liệu chính thức của MkDocs để biết thêm thông tin chi tiết và ví dụ sử dụng.