Tùy chỉnh chủ đề của bạn
Thay đổi chủ đề cho phù hợp với nhu cầu của bạn.
Nếu bạn muốn thực hiện một vài điều chỉnh cho một chủ đề hiện có, bạn không cần phải tạo chủ đề của riêng mình từ đầu. Đối với những điều chỉnh nhỏ chỉ yêu cầu một số CSS và/hoặc JavaScript, bạn có thể sử dụng docs_dir . Tuy nhiên, đối với các tùy chỉnh phức tạp hơn, bao gồm ghi đè các mẫu, bạn sẽ cần sử dụng cài đặt theme custom_dir .
Sử dụng docs_dir
Tùy chọn cấu hình extra_css và extra_javascript có thể được sử dụng để thực hiện các tinh chỉnh và tùy chỉnh cho các chủ đề hiện có. Để sử dụng các tùy chọn này, bạn chỉ cần đưa các tệp CSS hoặc JavaScript vào thư mục tài liệu của mình .
Ví dụ, để thay đổi màu của tiêu đề trong tài liệu của bạn, hãy tạo một tệp có tên (ví dụ) style.cssvà đặt tệp đó bên cạnh Markdown tài liệu. Trong tệp đó, hãy thêm mã CSS sau.
h1 { color: red; }
Sau đó bạn cần thêm nó vào mkdocs.yml:
extra_css: - style.css
Sau khi thực hiện những thay đổi này, chúng sẽ hiển thị khi bạn chạy mkdocs serve- nếu bạn đã chạy, bạn sẽ thấy những thay đổi về CSS được tự động chọn và tài liệu sẽ được cập nhật.
Ghi chú
Bất kỳ tệp CSS hoặc JavaScript bổ sung nào sẽ được thêm vào tài liệu HTML được tạo sau nội dung trang. Nếu bạn muốn đưa thư viện JavaScript vào, bạn có thể thành công hơn khi đưa thư viện vào bằng cách sử dụng chủ đề custom_dir .
Sử dụng chủ đề custom_dir
Tùy theme.custom_dirchọn cấu hình có thể được sử dụng để trỏ đến một thư mục các tệp ghi đè lên các tệp trong chủ đề gốc. Chủ đề gốc sẽ là chủ đề được xác định trong theme.nametùy chọn cấu hình. Bất kỳ tệp nào trong có custom_dircùng tên với tệp trong chủ đề gốc sẽ thay thế tệp có cùng tên trong chủ đề gốc. Bất kỳ tệp bổ sung nào trong custom_dirsẽ được thêm vào chủ đề gốc. Nội dung của custom_dirphải phản ánh cấu trúc thư mục của chủ đề gốc. Bạn có thể bao gồm các mẫu, tệp JavaScript, tệp CSS, hình ảnh, phông chữ hoặc bất kỳ phương tiện nào khác có trong chủ đề.
Ghi chú
Để làm được điều này, theme.namecài đặt phải được đặt thành một chủ đề đã cài đặt. Nếu namethay vào đó, cài đặt được đặt thành null(hoặc không được xác định), thì không có chủ đề nào để ghi đè và nội dung của chủ đề custom_dirphải là một chủ đề hoàn chỉnh, độc lập. Xem Hư ớng dẫn dành cho nhà phát triển chủ đề để biết thêm thông tin.
Ví dụ, chủ đề mkdocs ( duyệt nguồn ), chứa cấu trúc thư mục sau (một phần):
- css\ - fonts\ - img\ - favicon.ico - grid.png - js\ - 404.html - base.html - content.html - nav-sub.html - nav.html - toc.html
Để ghi đè bất kỳ tệp nào có trong chủ đề đó, hãy tạo một thư mục mới bên cạnh docs_dir:
mkdir custom_theme
Và sau đó trỏ mkdocs.ymltệp cấu hình của bạn tới thư mục mới:
theme: name: mkdocs custom_dir: custom_theme/
Để ghi đè trang lỗi 404 ("không tìm thấy tệp"), hãy thêm tệp mẫu mới có tên 404.htmlvào custom_themethư mục. Để biết thông tin về những gì có thể được đưa vào mẫu, hãy xem Hướng dẫn dành cho nhà phát triển chủ đề .
Để ghi đè lên biểu tượng yêu thích, bạn có thể thêm tệp biểu tượng mới tại custom_theme/img/favicon.ico.
Để đưa thư viện JavaScript vào, hãy sao chép thư viện vào custom_theme/js/ thư mục.
Cấu trúc thư mục của bạn bây giờ sẽ trông như thế này:
- docs/ - index.html - custom_theme/ - img/ - favicon.ico - js/ - somelib.js - 404.html - config.yml
Ghi chú
Bất kỳ tệp nào được bao gồm trong chủ đề gốc (được định nghĩa trong name) nhưng không được bao gồm trong custom_dirsẽ vẫn được sử dụng. custom_dirSẽ chỉ ghi đè/thay thế các tệp trong chủ đề gốc. Nếu bạn muốn xóa tệp hoặc xây dựng chủ đề từ đầu, thì bạn nên xem lại Hướng dẫn dành cho nhà phát triển chủ đề .
Ghi đè các khối mẫu
Các chủ đề tích hợp triển khai nhiều phần của chúng bên trong các khối mẫu có thể được ghi đè riêng lẻ trong main.htmlmẫu. Chỉ cần tạo một main.htmltệp mẫu trong tệp của bạn custom_dirvà xác định các khối thay thế trong tệp đó. Chỉ cần đảm bảo rằng phần main.htmlmở rộng base.html. Ví dụ: để thay đổi tiêu đề của chủ đề MkDocs, main.html mẫu thay thế của bạn sẽ chứa nội dung sau:
{% extends "base.html" %} {% block htmltitle %} <title>Custom title goes here</title> {% endblock %}
Trong ví dụ trên, htmltitlekhối được định nghĩa trong tệp tùy chỉnh của bạn main.htmlsẽ được sử dụng thay cho htmltitlekhối mặc định được định nghĩa trong chủ đề gốc. Bạn có thể định nghĩa lại bao nhiêu khối tùy thích, miễn là các khối đó được định nghĩa trong chủ đề gốc. Ví dụ: bạn có thể thay thế tập lệnh Google Analytics bằng một tập lệnh cho một dịch vụ khác hoặc thay thế tính năng tìm kiếm bằng tính năng của riêng bạn. Bạn sẽ cần tham khảo chủ đề gốc mà bạn đang sử dụng để xác định những khối nào có thể ghi đè. Các chủ đề MkDocs và ReadTheDocs cung cấp các khối sau:
site_meta: Chứa thẻ meta trong phần đầu tài liệu.htmltitle: Chứa tiêu đề trang trong phần đầu tài liệu.styles: Chứa các thẻ liên kết cho bảng định kiểu.libs: Bao gồm các thư viện JavaScript (jQuery, v.v.) có trong tiêu đề trang.scripts: Chứa các tập lệnh JavaScript sẽ được thực thi sau khi trang được tải.analytics: Chứa tập lệnh phân tích.extrahead: Một khối trống để<head>chèn thẻ tùy chỉnh/tập lệnh/v.v.site_name: Chứa tên trang web trên thanh điều hướng.site_nav: Chứa điều hướng trang web trong thanh điều hướng.search_button: Chứa hộp tìm kiếm trên thanh điều hướng.next_prev: Bao gồm các nút tiếp theo và trước đó trên thanh điều hướng.repo: Chứa liên kết kho lưu trữ trên thanh điều hướng.content: Chứa nội dung trang và mục lục của trang.footer: Chứa phần chân trang.
Bạn có thể cần xem các tệp mẫu nguồn để đảm bảo các sửa đổi của bạn sẽ hoạt động với cấu trúc của trang web. Xem Biến mẫu để biết danh sách các biến bạn có thể sử dụng trong các khối tùy chỉnh của mình. Để biết giải thích đầy đủ hơn về các khối, hãy tham khảo tài liệu Jinja .
Kết hợp custom_dir và Khối Mẫu
Việc thêm thư viện JavaScript vào custom_dirsẽ làm cho nó khả dụng, nhưng sẽ không bao gồm nó trong các trang được tạo bởi MkDocs. Do đó, cần phải thêm một liên kết đến thư viện từ HTML.
Bắt đầu với cấu trúc thư mục ở trên (đã cắt bớt):
- docs/ - custom_theme/ - js/ - somelib.js - config.yml
custom_theme/js/somelib.jsCần thêm liên kết đến tệp vào mẫu. Vì somelib.jslà thư viện JavaScript, về mặt logic, nó sẽ nằm trong libskhối. Tuy nhiên, một libskhối mới chỉ bao gồm tập lệnh mới sẽ thay thế khối được xác định trong mẫu cha và mọi liên kết đến thư viện trong mẫu cha sẽ bị xóa. Để tránh làm hỏng mẫu, có thể sử dụng siêu khối với lệnh gọi đến supertừ bên trong khối:
{% extends "base.html" %} {% block libs %} {{ super() }} <script src="{{ base_url }}/js/somelib.js"></script> {% endblock %}
Lưu ý rằng biến mẫu base_url được sử dụng để đ ảm bảo rằng liên kết luôn liên quan đến trang hiện tại.
Bây giờ các trang được tạo sẽ bao gồm các liên kết đến các thư viện mẫu được cung cấp cũng như thư viện có trong custom_dir. Điều tương tự cũng được yêu cầu đối với bất kỳ tệp CSS bổ sung nào có trong custom_dir.