Chủ đề - MkDocs
Phát triển chủ đề
Hướng dẫn tạo và phân phối chủ đề tùy chỉnh.
Ghi chú
Nếu bạn đang tìm kiếm các chủ đề của bên thứ ba hiện có, chúng được liệt kê trong trang wiki cộng đồng và danh mục dự án MkDocs . Nếu bạn muốn chia sẻ một chủ đề bạn tạo, bạn nên liệt kê chủ đề đó ở đó.
Khi tạo một chủ đề mới, bạn có thể làm theo các bước trong hướng dẫn này để tạo một chủ đề từ đầu hoặc bạn có thể tải xuống dưới mkdocs-basic-themedạng chủ đề cơ bản nhưng đầy đủ với tất cả các mẫu cần thiết. Bạn có thể tìm thấy chủ đề cơ bản này trên GitHub . Nó chứa các bình luận chi tiết trong mã để mô tả các tính năng khác nhau và cách sử dụng của chúng.
Tạo chủ đề tùy chỉnh
Yêu cầu tối thiểu cho một chủ đề tùy chỉnh là tệp main.html mẫu Jinja2 được đặt trong một thư mục không phải là con của docs_dir . Trong mkdocs.yml, hãy đặt theme.custom_dir tùy chọn thành đường dẫn của thư mục chứa main.html. Đường dẫn phải tương đối với tệp cấu hình. Ví dụ, với bố cục dự án mẫu này:
mkdocs.yml docs/ index.md about.md custom_theme/ main.html ...
... bạn sẽ bao gồm các thiết lập sau mkdocs.ymlđể sử dụng thư mục chủ đề tùy chỉnh:
theme: name: null custom_dir: 'custom_theme/'
Ghi chú
Nhìn chung, khi xây dựng chủ đề tùy chỉnh của riêng bạn, thiết lập cấu hình theme.name sẽ đ ược đặt thành .null Tuy nhiên, nếu giá trị cấu hình theme.custom_dir được sử dụng kết hợp với một chủ đề hiện có, thì theme.custom_dir có thể được sử dụng để chỉ thay thế các phần cụ thể của một chủ đề tích hợp. Ví dụ, với bố cục ở trên và nếu bạn đặt name: "mkdocs"thì main.htmltệp trong theme.custom_dir sẽ thay thế tệp có cùng tên trong chủ đề nhưng nếu không thì chủ đề sẽ không thay đổi. Điều này hữu ích nếu bạn muốn thực hiện các điều chỉnh nhỏ cho một chủ đề hiện có.mkdocs``mkdocs
Để biết thông tin cụ thể hơn, hãy xem mục Tùy chỉnh chủ đề của bạn .
Cảnh báo
Cấu hình của chủ đề được xác định trong mkdocs_theme.ymltệp không được tải từ theme.custom_dir. Khi toàn bộ chủ đề tồn tại trong theme.custom_dir và theme.nameđược đặt thành null, thì toàn bộ cấu hình chủ đề phải được xác định trong tùy chọn cấu hình chủ đề trong mkdocs.ymltệp.
Tuy nhiên, khi một chủ đề được đóng gói để phân phối và tải bằng theme.nametùy chọn cấu hình thì mkdocs_theme.ymlcần có một tệp cho chủ đề đó.
Chủ đề cơ bản
Tệp đơn giản nhất main.htmllà tệp sau:
<!DOCTYPE html> <html> <head> <title>{% if page.title %}{{ page.title }} - {% endif %}{{ config.site_name }}</title> {%- for path in config.extra_css %} <link href="{{ path | url }}" rel="stylesheet"> {%- endfor %} </head> <body> {{ page.content }} {%- for script in config.extra_javascript %} {{ script | script_tag }} {%- endfor %} </body> </html>
Nội dung chính từ mỗi trang được chỉ định trong mkdocs.ymlđược chèn bằng {{ page.content }}thẻ. Các bảng định kiểu và tập lệnh có thể được đưa vào chủ đề này như với tệp HTML thông thường. Thanh điều hướng và mục lục cũng có thể được tạo và bao gồm tự động, thông qua các đối tượng navvà toc. Nếu bạn muốn viết chủ đề của riêng mình, bạn nên bắt đầu bằng một trong các chủ đề tích hợp và sửa đổi cho phù hợp.
Ghi chú
Vì MkDocs sử dụng Jinja làm công cụ mẫu của mình, bạn có thể truy cập vào tất cả sức mạnh của Jinja, bao gồm cả kế thừa mẫu . Bạn có thể nhận thấy rằng các chủ đề đi kèm với MkDocs sử dụng rộng rãi kế thừa mẫu và các khối, cho phép người dùng dễ dàng ghi đè các bit và phần nhỏ của mẫu từ chủ đề custom_dir . Do đó, các chủ đề tích hợp được triển khai trong một base.htmltệp, main.htmlmở rộng. Mặc dù không bắt buộc, nhưng các tác giả mẫu của bên thứ ba được khuyến khích làm theo một mẫu tương tự v à có thể muốn xác định các khối giống như được sử dụng trong các chủ đề tích hợp để đảm bảo tính nhất quán.
Lấy CSS và JavaScript từ cấu hình
MkDocs định nghĩa các cấu hình extra_css và extra_javascript cấp cao nhất . Đây là danh sách các tệp.
Chủ đề phải bao gồm HTML liên kết các mục từ các cấu hình này, nếu không các cấu hình sẽ không hoạt động. Bạn có thể xem cách được đề xuất để hiển thị cả hai trong ví dụ cơ sở ở trên .
Đã thay đổi trong phiên bản 1.5:
Các mục trong config.extra_javascriptdanh sách trước đây là các chuỗi đơn giản nhưng giờ đã trở thành các đối tượng có các trường sau: path, type, async, defer.
Trong phiên bản đó, MkDocs cũng có thêm script_tagbộ lọc .
Phong cách lỗi thời:
{%- for path in extra_javascript %} <script src="{{ path }}"></script> {%- endfor %}
Ví dụ kiểu cũ này thậm chí còn sử dụng extra_javascriptdanh sách cấp cao nhất đã lỗi thời. Vui lòng luôn sử dụng config.extra_javascriptthay thế.
Vì vậy, một cách tiếp cận hiện đại hơn một chút là như sau, nhưng nó vẫn lỗi thời vì nó bỏ qua các thuộc tính bổ sung của tập lệnh:
{%- for path in config.extra_javascript %} <script src="{{ path | url }}"></script> {%- endfor %}
? VÍ DỤ: Kiểu mới:
{%- for script in config.extra_javascript %} {{ script | script_tag }} {%- endfor %}
Nếu bạn muốn có thể chọn các tùy chỉnh mới trong khi vẫn giữ cho chủ đề của mình tương thích với các phiên bản cũ hơn của MkDocs, hãy sử dụng đoạn mã này:
Phong cách tương thích ngược:
{%- for script in config.extra_javascript %} {%- if script.path %} {# Detected MkDocs 1.5+ which has `script.path` and `script_tag` #} {{ script | script_tag }} {%- else %} {# Fallback - examine the file name directly #} <script src="{{ script | url }}"{% if script.endswith(".mjs") %} type="module"{% endif %}></script> {%- endif %} {%- endfor %}
Tập tin chủ đề
Có nhiều tệp mà một chủ đề xử lý đặc biệt theo một cách nào đó. Bất kỳ tệp nào khác chỉ được sao chép từ thư mục chủ đề đến cùng một đường dẫn trong site_dirkhi trang web được xây dựng. Ví dụ, tệp hình ảnh và CSS không có ý nghĩa đặc biệt và được sao chép nguyên trạng. Tuy nhiên, lưu ý rằng nếu người dùng cung cấp tệp có cùng đường dẫn trong docs_dir, thì tệp của người dùng sẽ thay thế tệp chủ đề.
Tệp mẫu
Bất kỳ tệp nào có .htmlphần mở rộng đều được coi là tệp mẫu và không được sao chép từ thư mục chủ đề hoặc bất kỳ thư mục con nào. Ngoài ra, bất kỳ tệp nào được liệt kê trong static_templates đều được coi là mẫu bất kể phần mở rộng tệp của chúng là gì.
Tệp Meta Chủ đề
Các tệp khác nhau cần thiết để đóng gói một chủ đề cũng bị bỏ qua. Cụ thể là mkdocs_theme.ymltệp cấu hình và bất kỳ tệp Python nào.
Tệp chấm
Tác giả chủ đề có thể buộc MkDocs bỏ qua các tệp bằng cách bắt đầu tên tệp ho ặc thư mục bằng dấu chấm. Bất kỳ tệp nào sau đây sẽ bị bỏ qua:
.ignored.txt .ignored/file.txt foo/.ignored.txt foo/.ignored/file.txt
Tập tin tài liệu
Tất cả các tệp tài liệu đều bị bỏ qua. Cụ thể là bất kỳ tệp Markdown nào (sử dụng bất kỳ phần mở rộng tệp nào được MKDocs hỗ trợ). Ngoài ra, bất kỳ tệp README nào có thể tồn tại trong thư mục chủ đề đều bị bỏ qua.
Biến mẫu
Mỗi mẫu trong một chủ đề được xây dựng với một ngữ cảnh mẫu. Đây là các biến có sẵn cho các chủ đề. Ngữ cảnh thay đổi tùy thuộc vào mẫu đang được xây dựng. Hiện tại, các mẫu được xây dựng với ngữ cảnh toàn cục hoặc với ngữ cảnh cụ thể của một trang. Ngữ cảnh toàn cục được sử dụng cho các trang HTML không đại diện cho một tài liệu Markdown riêng lẻ, ví dụ như trang 404.html hoặc search.html.
Bối cảnh toàn cầu
Các biến sau đây có sẵn trên toàn cầu trên bất kỳ mẫu nào.
cấu hình
Biến configlà một thể hiện của đối tượng cấu hình MkDocs được tạo từ mkdocs.ymltệp cấu hình. Mặc dù bạn có thể sử dụng bất kỳ tùy chọn cấu hình nào, một số tùy chọn thường được sử dụng bao gồm:
- config.site_name
- cấu hình.site_url
- cấu hình.site_author
- cấu hình site_description
- config.theme.locale (Xem thêm Cấu hình chủ đề bên dưới)
- cấu hình.extra_javascript
- cấu hình.extra_css
- cấu hình.repo_url
- cấu hình.repo_name
- cấu hình.bản quyền
dẫn đường
Biến navđược sử dụng để tạo điều hướng cho tài liệu. Đối navtượng là một đối tượng lặp lại của các đối tượng điều hướng được xác định bởi thiết lập cấu hình nav .
Ngoài khả năng lặp lại của các đối tượng điều hướng , navđối tượng còn chứa các thuộc tính sau:
homepage: Page | None
Đối tượng trang cho trang chủ của trang web.
pages: list[Page]
Danh sách phẳng của tất cả các đối tượng trang có trong phần điều hướng.
Danh sách này không nhất thiết là danh sách đầy đủ tất cả các trang của trang web vì nó không chứa các trang không được bao gồm trong điều hướng. Danh sách này khớp với danh sách và thứ tự các trang được sử dụng cho tất cả các liên kết "trang tiếp theo" và "trang trước". Đối với danh sách tất cả các trang, hãy sử dụng biến mẫu pages .
Ví dụ về Nav
Sau đây là một ví dụ sử dụng cơ bản, trong đó đưa ra điều hướng cấp một và cấp hai dưới dạng danh sách lồng nhau.
{% if nav|length > 1 %} <ul> {% for nav_item in nav %} {% if nav_item.children %} <li>{{ nav_item.title }} <ul> {% for nav_item in nav_item.children %} <li class="{% if nav_item.active %}current{% endif %}"> <a href="{{ nav_item.url|url }}">{{ nav_item.title }}</a> </li> {% endfor %} </ul> </li> {% else %} <li class="{% if nav_item.active %}current{% endif %}"> <a href="{{ nav_item.url|url }}">{{ nav_item.title }}</a> </li> {% endif %} {% endfor %} </ul> {% endif %}
url cơ sở
Cung base_urlcấp đường dẫn tương đối đến gốc của dự án MkDocs. Mặc dù có thể sử dụng trực tiếp bằng cách thêm vào URL tương đối cục bộ, nhưng tốt nhất là sử dụng bộ lọc mẫu url , thông minh hơn về cách áp dụng base_url.
mkdocs_phiên bản
Bao gồm phiên bản MkDocs hiện tại.
ngày xây dựng utc
Đối tượng datetime của Python biểu diễn ngày và giờ tài liệu được xây dựng theo UTC. Điều này hữu ích để hiển thị thời gian gần đây nhất tài liệu được cập nhật.
trang
Danh sách phẳng Filecác đối tượng cho tất cả các trang trong dự án. Danh sách này có thể chứa các trang không được bao gồm trong điều hướng toàn cục và có thể không khớp với thứ tự các trang trong điều hướng đó. Đối tượng trang cho mỗi trang Filecó thể được truy cập từ file.page.
trang
Trong các mẫu không được hiển thị từ tệp nguồn Markdown, page biến là None. Trong các mẫu được hiển thị t ừ tệp nguồn Markdown, pagebiến chứa một pageđối tượng. Các pageđối tượng tương tự được sử dụng làm page đối tượng điều hướng trong điều hướng toàn cục và trong biến mẫu trang .
Tất cả pagecác đối tượng đều chứa các thuộc tính sau:
title() -> str | None
Trả về tiêu đề cho trang hiện tại.
Trước khi gọi read_source(), giá trị này trống. Nó cũng có thể được cập nhật bằng render().
Kiểm tra theo thứ tự và sử dụng tiêu đề đầu tiên trả về tiêu đề hợp lệ:
- giá trị được cung cấp khi init (được truyền vào từ config)
- giá trị của siêu dữ liệu 'tiêu đề'
- nội dung của H1 đầu tiên trong nội dung Markdown
- chuyển đổi tên tập tin thành tiêu đề
content: str | None
Markdown được hiển thị dưới dạng HTML, đây là nội dung của tài liệu.
Có dân cư sau .render().
toc: TableOfContents
Một đối tượng có thể lặp lại biểu diễn Mục lục của một trang. Mỗi mục trong toclà một AnchorLink.
Ví dụ sau đây sẽ hiển thị hai cấp trên cùng của Mục lục cho một trang.
<ul> {% for toc_item in page.toc %} <li><a href="{{ toc_item.url }}">{{ toc_item.title }}</a></li> {% for toc_item in toc_item.children %} <li><a href="{{ toc_item.url }}">{{ toc_item.title }}</a></li> {% endfor %} {% endfor %} </ul>
meta: MutableMapping[str, Any]
Bản đồ siêu dữ liệu được bao gồm ở đầu trang đánh dấu.
Trong ví dụ này, chúng tôi định nghĩa một sourcethuộc tính phía trên tiêu đề trang:
source: generics.py mixins.py # Page title Content...
Mẫu có thể truy cập siêu dữ liệu này cho trang có meta.source biến. Sau đó, có thể sử dụng siêu dữ liệu này để liên kết đến các tệp nguồn liên quan đến trang tài liệu.
{% for filename in page.meta.source %} <a class="github" href="https://github.com/.../{{ filename }}"> <span class="label label-info">{{ filename }}</span> </a> {% endfor %}
url: str property
URL của trang liên quan đến MkDocs site_dir.
Người ta mong đợi rằng điều này sẽ được sử dụng với bộ lọc url để đảm bảo URL có liên quan đến trang hiện tại.
<a href="{{ page.url|url }}">{{ page.title }}</a>
file: File
Tài liệu Filemà trang web đang được kết xuất dựa theo.
abs_url: str | None
URL tuyệt đối của trang từ gốc máy chủ được xác định bởi giá trị được gán cho thiết lập cấu hình site_url . Giá trị bao gồm bất kỳ thư mục con nào được bao gồm trong site_url, nhưng không phải tên miền. base_url không nên được sử dụng với biến này.
Ví dụ, nếu site_url: https://example.com/, thì giá trị của page.abs_urlcho trang foo.mdsẽ là /foo/. Tuy nhiên, nếu site_url: https://example.com/bar/, thì giá trị của page.abs_urlcho trang foo.mdsẽ là /bar/foo/.
canonical_url: str | None
URL đầy đủ, chính tắc đến trang hiện tại được xác định bởi giá trị được gán cho thiết lập cấu hình site_url . Giá trị bao gồm tên miền và bất kỳ thư mục con nào có trong site_url. base_url không nên được sử dụng với biến này.
edit_url: str | None
URL đầy đủ đến trang nguồn trong kho lưu trữ nguồn. Thường được sử dụng để cung cấp liên kết để chỉnh sửa trang nguồn. base_url không nên được sử dụng với biến này.
is_homepage: bool property
Đánh giá Truecho trang chủ của trang web và Falsetất cả các trang khác.
Có thể sử dụng kết hợp với các thuộc tính khác của page đối tượng để thay đổi hành vi. Ví dụ, để hiển thị tiêu đề khác trên trang chủ:
{% if not page.is_homepage %}{{ page.title }} - {% endif %}{{ site_name }}
previous_page: Page | None
Đối tượng trang cho trang trước hoặc None. Giá trị sẽ là Nonenếu trang hiện tại là mục đầu tiên trong điều hướng trang web hoặc nếu trang hiện tại không được bao gồm trong điều hướng.
next_page: Page | None
Đối tượng trang cho trang tiếp theo hoặc None. Giá trị sẽ là Nonenếu trang hiện tại là mục cuối cùng trong điều hướng trang web hoặc nếu trang hiện tại không được bao gồm trong điều hướng.
parent: Section | None = None
Mục cha trực tiếp của mục trong phần điều hướng trang web, Nonenếu mục đó ở cấp cao nhất.
children: None = None
Các trang không chứa phần tử con và thuộc tính luôn luôn là None.
active: bool property writable
Khi True, biểu thị rằng đây là trang hiện đang được xem. Mặc định là False.
is_section: bool = False
Chỉ ra rằng đối tượng điều hướng là đối tượng "phần". Luôn luôn Falsedành cho đối tượng trang.
is_page: bool = True
Chỉ ra rằng đối tượng điều hướng là đối tượng "trang". Luôn luôn Truedành cho đối tượng trang.
is_link: bool = False
Chỉ ra rằng đối tượng điều hướng là đối tượng "liên kết". Luôn luôn Falsedành cho các đối tượng trang.
Liên kết neo
Một mục duy nhất trong mục lục.
title: str
Văn bản của mục dưới dạng HTML.
url: str property
Phần băm của URL trỏ tới mục.
level: int
Cấp độ bắt đầu từ số 0 của vật phẩm.
children: list[AnchorLink]
Một phần tử lặp lại của bất kỳ mục con nào.
Đối tượng điều hướng
Các đối tượng điều hướng có trong biến mẫu nav có thể là một trong các đối tượng section , đối tượng page và đối tượng link . Trong khi các đối tượng section có thể chứa các đối tượng điều hư ớng lồng nhau, các trang và liên kết thì không.
Đối tượng trang là đối tượng trang đầy đủ được sử dụng cho trang hiện tại với tất cả các thuộc tính giống nhau có sẵn. Đối tượng phần và liên kết chứa một tập hợp con các thuộc tính đó như được định nghĩa bên dưới:
Phần
Một sectionđối tượng điều hướng định nghĩa một phần được đặt tên trong phần điều hướng và chứa danh sách các đối tượng điều hướng con. Lưu ý rằng các phần không chứa URL và không phải là liên kết dưới bất kỳ hình thức nào. Tuy nhiên, theo mặc định, MkDocs sắp xếp các trang chỉ mục lên trên cùng và phần con đầu tiên có thể được sử dụng làm URL cho một phần nếu chủ đề chọn làm như vậy.
Các thuộc tính sau đây có sẵn trên sectioncác đối tượng:
title: str
Tiêu đề của phần.
parent: Section | None = None
Mục cha trực tiếp của mục trong phần điều hướng trang web, Nonenếu mục đó ở cấp cao nhất.
children: list[StructureItem]
Một đối tượng lặp lại của tất cả các đối tượng điều hướng con. Đối tượng con có thể bao gồm các phần, trang và liên kết lồng nhau.
active: bool property writable
Khi True, biểu thị rằng trang con của phần này là trang hiện tại và có thể được sử dụng để làm nổi bật phần này như là phần đang được xem. Mặc định là False.
is_section: bool = True
Chỉ ra rằng đối tượng điều hướng là đối tượng "phần". Luôn luôn Truedành cho đối tượng phần.
is_page: bool = False
Chỉ ra rằng đối tượng điều hướng là đối tượng "trang". Luôn luôn Falsedành cho đối tượng phần.
is_link: bool = False
Chỉ ra rằng đối tượng điều hướng là đối tượng "liên kết". Luôn luôn Falsedành cho các đối tượng phần.
Liên kết
Đối linktượng điều hướng chứa một liên kết không trỏ đến trang MkDocs nội bộ.
Các thuộc tính sau đây có sẵn trên linkcác đối tượng:
title: str
Tiêu đề của liên kết. Tiêu đề này thường được dùng làm nhãn của liên kết.
url: str
URL mà liên kết trỏ đến. URL phải luôn là URL tuyệt đối và không cần phải thêm base_urltiền tố.
parent: Section | None = None
Mục cha trực tiếp của mục trong phần điều hướng trang web, Nonenếu mục đó ở cấp cao nhất.
children: None = None
Liên kết không chứa phần tử con và thuộc tính luôn luôn là None.
active: bool = False
Liên kết ngoài không thể "hoạt động" và thuộc tính luôn luôn là False.
is_section: bool = False
Chỉ ra rằng đối tượng điều hướng là đối tượng "phần". Luôn luôn Falsedành cho đối tượng liên kết.
is_page: bool = False
Chỉ ra rằng đối tượng điều hướng là đối tượng "trang". Luôn luôn Falsedành cho đối tượng liên kết.
is_link: bool = True
Chỉ ra rằng đối tượng điều hướng là đối tượng "liên kết". Luôn luôn Truedành cho đối tượng liên kết.
Có thể truyền các biến bổ sung vào mẫu bằng extratùy chọn cấu hình. Đây là một tập hợp các cặp giá trị khóa có thể làm cho các mẫu tùy chỉnh linh hoạt hơn nhiều.
Ví dụ, điều này có thể được sử dụng để bao gồm phiên bản dự án của tất cả các trang và danh sách các liên kết liên quan đến dự án. Điều này có thể đạt được bằng extracấu hình sau:
extra: version: 0.13.0 links: - https://github.com/mkdocs - https://docs.readthedocs.org/en/latest/builds.html#mkdocs - https://www.mkdocs.org/
Và sau đó hiển thị bằng mã HTML này trong chủ đề tùy chỉnh.
{{ config.extra.version }} {% if config.extra.links %} <ul> {% for link in config.extra.links %} <li>{{ link }}</li> {% endfor %} </ul> {% endif %}
Bộ lọc mẫu
Ngoài các bộ lọc mặc định của Jinja , các bộ lọc tùy chỉnh sau đây có thể sử dụng trong các mẫu MkDocs:
địa chỉ
Chuẩn hóa URL. URL tuyệt đối được truyền qua mà không thay đổi. Nếu URL là tương đối và ngữ cảnh mẫu bao gồm một đối tượng trang, thì URL được trả về tương đối với đối tượng trang. Nếu không, URL được trả về với base_url được thêm vào trước.
<a href="{{ page.url|url }}">{{ page.title }}</a>
tojson
Chuyển đổi an toàn một đối tượng Python thành giá trị trong tập lệnh JavaScript.
<script> var mkdocs_page_name = {{ page.title|tojson|safe }}; </script>
thẻ script
Mới trong phiên bản 1.5
Chuyển đổi một mục từ extra_javascriptthành một <script>thẻ có tính đến tất cả các tùy chỉnh của cấu hình này và có hành vi tương đương |urlđược tích hợp sẵn.
Xem cách sử dụng nó trong ví dụ cơ bản ở trên
Tìm kiếm và chủ đề
Kể từ phiên bản MkDocs 0.17, hỗ trợ tìm kiếm phía máy khách đã được thêm vào MkDocs thông qua searchplugin. Một chủ đề cần cung cấp một số thứ để plugin hoạt động với chủ đề.
Mặc dù searchplugin được kích hoạt theo mặc định, người dùng có thể vô hiệu hóa plugin và các chủ đề nên tính đến điều này. Nên sử dụng các mẫu chủ đề để bao bọc đánh dấu tìm kiếm cụ thể bằng một kiểm tra cho plugin:
{% if 'search' in config.plugins %} search stuff here... {% endif %}
Ở chức năng cơ bản nhất, plugin tìm kiếm sẽ chỉ cung cấp một tệp chỉ mục không gì hơn là một tệp JSON chứa nội dung của tất cả các trang. Chủ đề sẽ cần triển khai chức năng tìm kiếm riêng của nó ở phía máy khách. Tuy nhiên, với một vài cài đặt và các mẫu cần thiết, plugin có thể cung cấp một công cụ tìm kiếm phía máy khách hoạt động hoàn chỉnh dựa trên lunr.js.
Cần thêm mã HTML sau vào chủ đề để JavaScript được cung cấp có thể tải đúng các tập lệnh tìm kiếm và tạo liên kết tương đối đến kết quả tìm kiếm từ trang hiện tại.
<script>var base_url = {{ base_url|tojson }};</script>
Với các thiết lập được cấu hình đúng, mã HTML sau trong mẫu sẽ thêm chức năng tìm kiếm đầy đủ vào chủ đề của bạn.
<h1 id="search">Search Results</h1> <form action="search.html"> <input name="q" id="mkdocs-search-query" type="text" > </form> <div id="mkdocs-search-results"> Sorry, page not found. </div>
JavaScript trong plugin hoạt động bằng cách tìm kiếm các ID cụ thể được sử dụng trong HTML ở trên. Đầu vào biểu mẫu để người dùng nhập truy vấn tìm kiếm phải được xác định bằng id="mkdocs-search-query"và div nơi kết quả sẽ được đặt phải được xác định bằng id="mkdocs-search-results".
Plugin hỗ trợ các tùy chọn sau được thiết lập trong tệp cấu hình của chủmkdocs_theme.yml đề :
bao gồm trang tìm kiếm
Xác định xem plugin tìm kiếm có mong đợi chủ đề cung cấp trang tìm kiếm chuyên dụng thông qua mẫu nằm tại search/search.html.
Khi include_search_pageđược đặt thành true, mẫu tìm kiếm sẽ được xây dựng và có sẵn tại search/search.html. Phương pháp này được sử dụng bởi readthedocs chủ đề.
Khi include_search_pageđược đặt thành falsehoặc không được xác định, chủ đề được mong đợi cung cấp một số cơ chế khác để hiển thị kết quả tìm kiếm. Ví dụ, chủ mkdocsđề hiển thị kết quả trên bất kỳ trang nào thông qua một hộp thoại.
chỉ_mục_tìm_kiếm
Xác định xem plugin tìm kiếm chỉ tạo ra một chỉ mục tìm kiếm hay một giải pháp tìm kiếm hoàn chỉnh.
Khi search_index_onlyđược đặt thành false, thì plugin tìm kiếm sẽ sửa đổi môi trường Jinja bằng cách thêm templatesthư mục riêng của nó (có mức độ ưu tiên thấp hơn chủ đề) và thêm các tập lệnh của nó vào extra_javascriptcài đặt cấu hình.
Khi search_index_onlyđược đặt thành truehoặc không được xác định, plugin tìm kiếm không thực hiện bất kỳ thay đổi nào đối với môi trường Jinja. Một giải pháp hoàn chỉnh sử dụng tệp chỉ mục được cung cấp là trách nhiệm của chủ đề.
Chỉ mục tìm kiếm được ghi vào tệp JSON tại search/search_index.jsonsite_dir . Đối tượng JSON có trong tệp có thể chứa tối đa ba đối tượng.
{ config: {...}, docs: [...], index: {...} }
Nếu có, configđối tượng chứa các cặp khóa/giá trị của tùy chọn cấu hình được xác định cho plugin trong mkdocs.ymltệp cấu hình của người dùng tại plugings.search. configĐối tượng này là mới trong MkDocs phiên bản 1.0 .
Đối docstượng chứa danh sách các đối tượng tài liệu. Mỗi đối tượng tài liệu bao gồm một location(URL), một title, và textcó thể được sử dụng để tạo chỉ mục tìm kiếm và/hoặc hiển thị kết quả tìm kiếm.
Nếu có, indexđối tượng chứa một chỉ mục dựng sẵn cung cấp cải tiến hiệu suất cho các trang web lớn hơn. Lưu ý rằng chỉ mục dựng sẵn chỉ được tạo nếu người dùng bật tùy chọn cấu hình prebuild_index một cách rõ ràng . Các chủ đề nên mong đợi chỉ mục không có sẵn, nhưng có thể chọn sử dụng chỉ mục khi chỉ mục khả dụng. indexĐối tượng này là mới trong MkDocs phiên bản 1.0 .
Chủ đề đóng gói
MkDocs sử dụng gói Python để phân phối chủ đề. Điều này đi kèm với một số yêu cầu.
Để xem ví dụ về gói chứa một chủ đề, hãy xem chủ đề MkDocs Bootstrap và để xem gói chứa nhiều chủ đề, hãy xem chủ đề MkDocs Bootswatch .
Ghi chú
Không nhất thiết phải đóng gói một chủ đề, vì toàn bộ chủ đề có thể được chứa trong custom_dir. Nếu bạn đã tạo một "chủ đề một lần", thì điều đó là đủ. Tuy nhiên, nếu bạn có ý định phân phối chủ đề của mình để người khác sử dụng, thì việc đóng gói chủ đề có một số lợi thế. Bằng cách đóng gói chủ đề của bạn, người dùng của bạn có thể dễ dàng cài đặt chủ đề hơn, họ có thể dựa vào cấu hình mặc định được xác định và sau đó họ có thể tận dụng custom_dir để điều chỉnh chủ đề của bạn sao cho phù hợp hơn với nhu cầu của họ.
Bố cục gói
Bố cục sau đây được khuyến nghị cho các chủ đề. Hai tệp ở thư mục cấp cao nhất được gọi là MANIFEST.invà setup.pybên cạnh thư mục chủ đề chứa một __init__.pytệp trống, một tệp cấu hình chủ đề ( mkdocs_theme.yml), và các tệp mẫu và phương tiện của bạn.
. |-- MANIFEST.in |-- theme_name | |-- __init__.py | |-- mkdocs_theme.yml | |-- main.html | |-- styles.css `-- setup.py
Tệp MANIFEST.inphải chứa các nội dung sau nhưng theme_name phải được cập nhật và bất kỳ phần mở rộng tệp bổ sung nào phải được thêm vào include.
recursive-include theme_name *.ico *.js *.css *.png *.html *.eot *.svg *.ttf *.woff recursive-exclude * __pycache__ recursive-exclude * *.py[co]
Cần setup.pybao gồm văn bản sau với những sửa đổi được mô tả bên dưới.
from setuptools import setup, find_packages VERSION = '0.0.1' setup( name="mkdocs-themename", version=VERSION, url='', license='', description='', author='', author_email='', packages=find_packages(), include_package_data=True, entry_points={ 'mkdocs.themes': [ 'themename = theme_name', ] }, zip_safe=False )
Điền URL, giấy phép, mô tả, tác giả và địa chỉ email của tác giả.
Tên phải tuân theo quy ước mkdocs-themename(như mkdocs-bootstrapvà mkdocs-bootswatch), bắt đầu bằng MkDocs, sử dụng dấu gạch nối để phân tách các từ và bao gồm tên ch ủ đề của bạn.
Hầu hết phần còn lại của tệp có thể để nguyên không chỉnh sửa. Phần cuối cùng chúng ta cần thay đổi là entry_points. Đây là cách MkDocs tìm chủ đề bạn đang đưa vào gói. Tên bên trái là tên mà người dùng sẽ sử dụng trong mkdocs.yml của họ và tên bên phải là thư mục chứa các tệp chủ đề của bạn.
Thư mục bạn đã tạo ở đầu phần này với tệp main.html phải chứa tất cả các tệp chủ đề khác. Yêu cầu tối thiểu là nó phải bao gồm một main.htmlcho chủ đề. Nó cũng phải bao gồm một __init__.pytệp phải trống, tệp này cho Python biết rằng thư mục là một gói.
Cấu hình chủ đề
Một chủ đề được đóng gói phải bao gồm một tệp cấu hình có tên mkdocs_theme.ymlđược đặt trong thư mục gốc của các tệp mẫu của bạn. Tệp này phải chứa các tùy chọn cấu hình mặc định cho chủ đề. Tuy nhiên, nếu chủ đề không cung cấp tùy chọn cấu hình, tệp này vẫn được yêu cầu và có thể để trống. Một chủ đề không được đóng gói không cần tệp mkdocs_theme.yml vì tệp đó không được tải từ theme.custom_dir.
Tác giả chủ đề có thể tự do định nghĩa bất kỳ tùy chọn tùy ý nào được coi là cần thiết và các tùy chọn đó sẽ được cung cấp trong các mẫu để kiểm soát hành vi. Ví dụ, một chủ đề có thể muốn tạo một thanh bên tùy chọn và bao gồm các mục sau trong tệp mkdocs_theme.yml:
show_sidebar: true
Sau đó, trong một mẫu, tùy chọn cấu hình đó có thể được tham chiếu:
{% if config.theme.show_sidebar %} <div id="sidebar">...</div> {% endif %}
Và người dùng có thể ghi đè giá trị mặc định trong mkdocs.ymltệp cấu hình của dự án:
theme: name: themename show_sidebar: false
Ngoài các tùy chọn tùy ý được xác định bởi chủ đề, MkDocs còn xác định một số tùy chọn đặc biệt giúp thay đổi hành vi của chủ đề:
địa phương
Tùy chọn này phản ánh tùy chọn cấu hình chủ đề có cùng tên. Nếu giá trị này không được định nghĩa trong mkdocs_theme.ymltệp và người dùng không đặt nó vào mkdocs.ymlthì mặc định sẽ là en(Tiếng Anh). Giá trị này được mong đợi sẽ khớp với ngôn ngữ được sử dụng trong văn bản do chủ đề cung cấp (chẳng hạn như liên kết "tiếp theo" và "trước") và nên được sử dụng làm giá trị của thuộc tính <html>thẻ lang. Xem Hỗ trợ bản địa hóa/dịch chủ đề để biết thêm thông tin.
Lưu ý rằng trong quá trình xác thực cấu hình, chuỗi được cung cấp sẽ được chuyển đổi thành một Localeđối tượng. Đối tượng chứa Locale.languagecác Locale.territorythuộc tính và sẽ giải quyết dưới dạng chuỗi từ bên trong một mẫu. Do đó, các thao tác sau sẽ hoạt động tốt:
<html lang="{ config.theme.locale }">
Nếu ngôn ngữ được đặt thành fr_CA(tiếng Pháp của Canada), thì mẫu ở trên sẽ hiển thị như sau:
<html lang="fr_CA">
Nếu bạn không muốn bao gồm thuộc tính lãnh thổ, hãy tham chiếu languagetrực tiếp thuộc tính đó:
<html lang="{ config.theme.locale.language }">
Điều đó sẽ hiển thị như sau:
<html lang="fr">
mẫu_tĩnh
Tùy chọn này phản ánh tùy chọn cấu hình chủ đề cùng tên và cho phép một số mặc định được thiết lập bởi chủ đề. Lưu ý rằng trong khi người dùng có thể thêm các mẫu vào danh sách này, người dùng không thể xóa các mẫu có trong cấu hình của chủ đề.
mở rộng
Xác định chủ đề cha mà chủ đề này kế thừa. Giá trị phải là tên chuỗi của chủ đề cha. Áp dụng các quy tắc kế thừa Jinja thông thường .
Các plugin cũng có thể xác định một số tùy chọn cho phép chủ đề thông báo cho plugin về bộ tùy chọn plugin mà nó mong đợi. Xem tài liệu cho bất kỳ plugin nào bạn có thể muốn hỗ trợ trong chủ đề của mình.
Phân phối chủ đề
Với những thay đổi trên, theme của bạn giờ đã sẵn sàng để cài đặt. Bạn có thể thực hiện việc này bằng pip, pip install .nếu bạn vẫn đang ở cùng thư mục với setup.py.
Hầu hết các gói Python, bao gồm MkDocs, được phân phối trên PyPI. Để thực hiện việc này, bạn nên chạy lệnh sau.
python setup.py register
Nếu bạn chưa thiết lập tài khoản, bạn sẽ được nhắc tạo một tài khoản.
Để biết hướng dẫn chi tiết hơn, hãy xem tài liệu đóng gói Python chính thức cho Dự án đóng gói và phân phối .
Chủ đề hỗ trợ Bản địa hóa/Dịch thuật
Trong khi các chủ đề tích hợp cung cấp hỗ trợ cho việc bản địa hóa/dịch các mẫu, các chủ đề tùy chỉnh và chủ đề của bên thứ ba có thể chọn không hỗ trợ. Bất kể thế nào, cài localeđặt themetùy chọn cấu hình luôn có sẵn và được các phần khác của hệ thống dựa vào. Do đó, chúng tôi khuyến nghị rằng tất cả các chủ đề của bên thứ ba sử dụng cùng một cài đặt để chỉ định ngôn ngữ bất kể hệ thống nào họ sử dụng để dịch. Theo cách đó, người dùng sẽ trải nghiệm hành vi nhất quán bất kể chủ đề nào họ có thể chọn.
Phương pháp quản lý bản dịch tùy thuộc vào nhà phát triển chủ đề. Tuy nhiên, nếu nhà phát triển chủ đề chọn sử dụng cùng cơ chế được sử dụng bởi các chủ đề tích hợp, các phần bên dưới sẽ phác thảo cách bật và sử dụng cùng lệnh được sử dụng bởi MkDocs.
Sử dụng lệnh Bản địa hóa/Dịch thuật
Cảnh báo
Vì pybabel không được cài đặt theo mặc định và hầu hết người dùng sẽ không cài đặt pybabel, nên các nhà phát triển chủ đề và/hoặc biên dịch viên nên đảm bảo đã cài đặt các phụ thuộc cần thiết (sử dụng pip install 'mkdocs[i18n]') để c ác lệnh có thể sử dụng được.
Các lệnh dịch phải được gọi từ gốc cây làm việc của chủ đề bạn.
Để biết tổng quan về quy trình làm việc mà MkDocs sử dụng để dịch các chủ đề tích hợp, hãy xem phần thích hợp của Hướng dẫn đóng góp và Hướng dẫn dịch thuật .
Ví dụ về chủ đề tùy chỉnh Quy trình bản địa hóa/dịch thuật
Ghi chú
Nếu chủ đề của bạn kế thừa từ một chủ đề hiện có đã cung cấp danh mục bản dịch, bản dịch của chủ đề đó sẽ được hợp nhất với bản dịch của chủ đề gốc trong quá trình xây dựng MkDocs.
Điều này có nghĩa là bạn chỉ cần tập trung vào các bản dịch được thêm vào. Tuy nhiên, bạn vẫn sẽ được hưởng lợi từ các bản dịch của chủ đề gốc. Đồng thời, bạn có thể ghi đè bất kỳ bản dịch nào của chủ đề gốc!
Giả sử bạn đang làm việc trên nhánh mkdocs-basic-theme của riêng mình và muốn thêm bản dịch vào đó.
Chỉnh sửa các mẫu bằng cách bao quanh văn bản trong nguồn HTML của bạn bằng {% trans %}và {% endtrans %}như sau:
--- a/basic_theme/base.html +++ b/basic_theme/base.html @@ -88,7 +88,7 @@ <body> - <h1>This is an example theme for MkDocs.</h1> + <h1>{% trans %}This is an example theme for MkDocs.{% endtrans %}</h1> <p> It is designed to be read by looking at the theme HTML which is heavily
Sau đó, bạn sẽ làm theo Hướng dẫn dịch như bình thường để thực hiện bản dịch.
Đóng gói bản dịch theo chủ đề của bạn
Trong khi tệp Portable Object Template ( pot) được tạo bởi extract_messageslệnh và các tệp Portable Object ( po) được tạo bởi lệnh init_catalogvà update_cataloghữu ích cho việc tạo và chỉnh sửa bản dịch, chúng không được MkDocs sử dụng trực tiếp và không cần phải được đưa vào bản phát hành đóng gói của một chủ đề. Khi MkDocs xây dựng một trang web có bản dịch, nó chỉ sử dụng các motệp nhị phân cho ngôn ngữ được chỉ định. Do đó, khi đóng gói một chủ đề , hãy đảm bảo đưa nó vào "wheels", bằng cách sử dụng MANIFEST.intệp hoặc cách khác.
Sau đó, trước khi xây dựng gói Python của bạn, bạn sẽ muốn đảm bảo rằng tệp nhị phân mocho mỗi ngôn ngữ được cập nhật bằng cách chạy compile_catalog lệnh cho mỗi ngôn ngữ. MkDocs mong đợi mocác tệp nhị phân được đặt tại locales/<locale>/LC_MESSAGES/messages.mo, lệnh này compile_catalog tự động thực hiện cho bạn. Xem Kiểm tra bản dịch chủ đề để biết chi tiết.
Ghi chú
Như đã nêu trong Hướng dẫn dịch thuật của chúng tôi , dự án MkDocs đã chọn đưa các tệp potvà povào kho lưu trữ mã của chúng tôi, nhưng không phải mocác tệp. Điều này yêu cầu chúng tôi phải luôn chạy compile_catalogtrước khi đóng gói bản phát hành mới bất kể có bất kỳ thay đổi nào được thực hiện đối với bản dịch hay không. Tuy nhiên, bạn có thể chọn một quy trình làm việc thay thế cho chủ đề của mình. Ít nhất, bạn cần đảm bảo rằng các tệp cập nhật mođược đưa vào đúng vị trí trong mỗi bản phát hành. Tuy nhiên, bạn có thể sử dụng một quy trình khác để tạo mocác tệp đó nếu bạn chọn làm như vậy.