Skip to main content

Chọn chủ đề của bạn

Chọn và cấu hình chủ đề.

MkDocs bao gồm hai chủ đề tích hợp ( mkdocs và readthedocs ), như được ghi chép bên dưới. Tuy nhiên, nhiều chủ đề của bên thứ ba cũng có sẵn để lựa chọn.

Để chọn chủ đề, hãy thiết lập tùy chọn cấu hình chủ đề trong mkdocs.yml tệp cấu hình của bạn.

theme: name: readthedocs

mkdocs​

Giao diện mặc định, được xây dựng như một giao diện Bootstrap tùy chỉnh , hỗ trợ hầu hết mọi tính năng của MkDocs.

Chủ đề MkDocs ở chế độ sáng

Ngoài các tùy chọn cấu hình chủ đề mặc định , mkdocschủ đề này hỗ trợ các tùy chọn sau:

  • color_mode: Đặt chế độ màu mặc định cho chủ đề thành một trong các chế độ light, dark, hoặc auto. autoChế độ sẽ chuyển sang lighthoặc darkdựa trên cấu hình hệ thống của thiết bị người dùng. Mặc định: light.

  • user_color_mode_toggle: Bật menu chuyển đổi trong thanh điều hướng cho phép người dùng chọn chế độ ưa thích color_mode(sáng, tối, tự động) từ trong trình duyệt và lưu tùy chọn của họ cho các lần tải trang sau. Lựa chọn mặc định của menu chuyển đổi khi tải trang đầu tiên là giá trị được đặt thành color_mode. Mặc định: false.

    menu chuyển đổi chế độ màu

  • nav_style: Điều chỉnh kiểu trực quan của thanh điều hướng trên cùng. Đặt thành một trong primary, darkhoặc light. Mặc định: primary. Tùy chọn này độc lập với color_modetùy chọn và phải được xác định riêng.

  • highlightjs: Cho phép tô sáng mã nguồn trong các khối mã bằng thư viện JavaScript highlight.js . Mặc định: True.

  • hljs_style: Thư viện highlight.js cung cấp nhiều kiểu khác nhau (biến thể màu) để làm nổi bật mã nguồn trong các khối mã. Đặt thành tên của kiểu mong muốn khi ở lightchế độ. Mặc định: github.

  • hljs_style_dark: Đặt thành tên của kiểu highlight.js mong muốn khi ở darkchế độ này. Mặc định: github_dark.

  • hljs_languages: Theo mặc định, highlight.js chỉ hỗ trợ 23 ngôn ngữ phổ biến. Liệt kê các ngôn ngữ bổ sung tại đây để bao gồm hỗ trợ cho chúng.

    theme: name: mkdocs highlightjs: true hljs_languages: - yaml - rust

  • analytics: Xác định các tùy chọn cấu hình cho dịch vụ phân tích. Hiện tại, chỉ có Google Analytics v4 được hỗ trợ thông qua gtagtùy chọn này.

  • shortcuts: Xác định phím tắt.

    theme: name: mkdocs shortcuts: help: 191 # ? next: 78 # n previous: 80 # p search: 83 # s

    Tất cả các giá trị phải là mã phím số. Tốt nhất là sử dụng các phím có sẵn trên tất cả các bàn phím. Bạn có thể sử dụng https://keycode.info/ để xác định mã phím cho một phím nhất định.

    • help: Hiển thị hộp thoại trợ giúp liệt kê các phím tắt. Mặc định: 191(?)

    • next: Điều hướng đến trang "tiếp theo". Mặc định: 78(n)

    • previous: Điều hướng đến trang "trước". Mặc định: 80(p)

    • search: Hiển thị hộp tìm kiếm. Mặc định: 83(s)

  • navigation_depth: Độ sâu tối đa của cây điều hướng trong thanh bên. Mặc định: 2.

  • locale: Ngôn ngữ (ngôn ngữ/vị trí) được sử dụng để xây dựng chủ đề. Nếu ngôn ngữ của bạn chưa được hỗ trợ, nó sẽ trở về mặc định.

    Các địa phương sau đây được chủ đề này hỗ trợ:

    • en: Tiếng Anh (mặc định)
    • de: Tiếng Đức
    • es: Tiếng Tây Ban Nha
    • fa: Ba Tư
    • fr: Tiếng Pháp
    • id: Tiếng Indonesia
    • it: Tiếng Ý
    • ja: Tiếng Nhật
    • nb: Tiếng Na Uy Bokmål
    • nl: Hà Lan
    • nn: Tiếng Na Uy Nynorsk
    • pl: Đánh bóng
    • pt_BR: Tiếng Bồ Đào Nha (Brazil)
    • ru: Tiếng Nga
    • tr: Thổ Nhĩ Kỳ
    • uk: Tiếng Ukraina
    • zh_CN: Tiếng Trung (giản thể, Trung Quốc)
    • zh_TW: Tiếng Trung (Phồn thể, Đài Loan)

    Xem hướng dẫn về bản địa hóa chủ đề của bạn để biết thêm thông tin.

đọctàiliệu​

Bản sao của chủ đề mặc định được dịch vụ Read the Docs sử dụng , cung cấp cùng một bộ tính năng hạn chế như chủ đề gốc. Giống như chủ đề gốc, chỉ có hai cấp độ điều hướng được hỗ trợ.

ĐọcTheDocs

Ngoài các tùy chọn cấu hình chủ đề mặc định , readthedocs chủ đề này hỗ trợ các tùy chọn sau:

  • highlightjs: Cho phép tô sáng mã nguồn trong các khối mã bằng thư viện JavaScript highlight.js . Mặc định: True.

  • hljs_languages: Theo mặc định, highlight.js chỉ hỗ trợ 23 ngôn ngữ phổ biến. Liệt kê các ngôn ngữ bổ sung tại đây để bao gồm hỗ trợ cho chúng.

    theme: name: readthedocs highlightjs: true hljs_languages: - yaml - rust

  • analytics: Xác định các tùy chọn cấu hình cho dịch vụ phân tích.

  • include_homepage_in_sidebar: Liệt kê trang chủ trong menu thanh bên. Vì MkDocs yêu cầu trang chủ phải được liệt kê trong navtùy chọn cấu hình, nên thiết lập này cho phép bao gồm hoặc loại trừ trang chủ khỏi thanh bên. Lưu ý rằng tên/logo trang web luôn liên kết đến trang chủ. Mặc định: True.

  • prev_next_buttons_location: Một trong các bottomnút , top, both, hoặc none. Hiển thị các nút “Tiếp theo” và “Trước đó” tương ứng. Mặc định: bottom.

  • navigation_depth: Độ sâu tối đa của cây điều hướng trong thanh bên. Mặc định: 4.

  • collapse_navigation: Chỉ bao gồm tiêu đề phần trang trong thanh bên cho trang hiện tại. Mặc định: True.

  • titles_only: Chỉ bao gồm tiêu đề trang trong thanh bên, loại trừ tất cả tiêu đề phần cho tất cả các trang. Mặc định: False.

  • sticky_navigation: Nếu Đúng, sẽ khiến thanh bên cuộn theo nội dung trang chính khi bạn cuộn trang. Mặc định: True.

  • locale: Ngôn ngữ (ngôn ngữ/vị trí) được sử dụng để xây dựng chủ đề. Nếu ngôn ngữ của bạn chưa được hỗ trợ, nó sẽ trở về mặc định.

    Các địa phương sau đây được chủ đề này hỗ trợ:

    • en: Tiếng Anh (mặc định)
    • de: Tiếng Đức
    • es: Tiếng Tây Ban Nha
    • fa: Ba Tư
    • fr: Tiếng Pháp
    • id: Tiếng Indonesia
    • it: Tiếng Ý
    • ja: Tiếng Nhật
    • nl: Hà Lan
    • pl: Đánh bóng
    • pt_BR: Tiếng Bồ Đào Nha (Brazil)
    • ru: Tiếng Nga
    • tr: Thổ Nhĩ Kỳ
    • uk: Tiếng Ukraina
    • zh_CN: Tiếng Trung (giản thể, Trung Quốc)
    • zh_TW: Tiếng Trung (Phồn thể, Đài Loan)

    Xem hướng dẫn về bản địa hóa chủ đề của bạn để biết thêm thông tin.

  • logo: Để đặt logo vào dự án của bạn thay vì văn bản thuần túy site_name, hãy đặt biến này thành vị trí hình ảnh của bạn. Mặc định: null.

Chủ đề của bên thứ ba​

Danh sách các chủ đề của bên thứ ba có thể được tìm thấy tại trang wiki cộng đồng và danh mục được xếp hạng . Nếu bạn đã tạo chủ đề của riêng mình, vui lòng thêm chúng vào đó.

Cảnh báo

Cài đặt chủ đề MkDocs có nghĩa là cài đặt gói Python và thực thi bất kỳ mã nào mà tác giả đã đưa vào đó. Vì vậy, hãy thận trọng như thường lệ; không có nỗ lực nào để thử nghiệm.

5:11:02 AM