Skip to main content

Plugin - MkDocs

Hướng dẫn cài đặt, sử dụng và tạo Plugin MkDocs

Cài đặt Plugin​

Trước khi có thể sử dụng plugin, plugin đó phải được cài đặt trên hệ thống. Nếu bạn đang sử dụng plugin đi kèm với MkDocs, thì plugin đó đã được cài đặt khi bạn cài đặt MkDocs. Tuy nhiên, để cài đặt plugin của bên thứ ba, bạn cần xác định tên gói phù hợp và cài đặt bằng cách sử dụng pip:

pip install mkdocs-foo-plugin

Cảnh báo

Cài đặt plugin 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.

Sau khi cài đặt thành công plugin, plugin đã sẵn sàng để sử dụng. Chỉ cần bật plugin trong tệp cấu hình. Kho lưu trữ Catalog có danh sách plugin được xếp hạng lớn mà bạn có thể cài đặt và sử dụng.

Sử dụng Plugin​

Tùy pluginschọn cấu hình phải chứa danh sách các plugin để sử dụng khi xây dựng trang web. Mỗi "plugin" phải là tên chuỗi được gán cho plugin (xem tài liệu hướng dẫn cho một plugin nhất định để xác định "tên" của plugin đó). Một plugin được liệt kê ở đây phải đã được cài đặt .

plugins: - search

Một số plugin có thể cung cấp tùy chọn cấu hình riêng. Nếu bạn muốn thiết lập bất kỳ tùy chọn cấu hình nào, thì bạn có thể lồng một ánh xạ khóa/giá trị ( option_name: option value) của bất kỳ tùy chọn nào mà plugin hỗ trợ. Lưu ý rằng dấu hai chấm ( :) phải theo sau tên plugin và sau đó trên một dòng mới, tên tùy chọn và giá trị phải được thụt lề và phân tách bằng dấu hai chấm. Nếu bạn muốn xác định nhiều tùy chọn cho một plugin duy nhất, thì mỗi tùy chọn phải được xác định trên một dòng riêng biệt.

plugins: - search: lang: en foo: bar

Để biết thông tin về các tùy chọn cấu hình có sẵn cho một plugin nhất định, hãy xem tài liệu của plugin đó.

Để biết danh sách các plugin mặc định và cách ghi đè chúng, hãy xem tài liệu cấu hình .

Phát triển Plugin​

Giống như MkDocs, plugin phải được viết bằng Python. Người ta thường mong đợi rằng mỗi plugin sẽ được phân phối như một mô-đun Python riêng biệt, mặc dù có thể định nghĩa nhiều plugin trong cùng một mô-đun. Tối thiểu, một Plugin MkDocs phải bao gồm một lớp con BasePlugin và một điểm vào trỏ đến lớp con đó.

Plugin cơ sở​

Một lớp con của mkdocs.plugins.BasePluginnên xác định hành vi của plugin. Lớp này thường bao gồm các hành động thực hiện trên các sự kiện cụ thể trong quá trình xây dựng cũng như một lược đồ cấu hình cho plugin.

Tất cả BasePlugincác lớp con đều chứa các thuộc tính sau:

sơ đồ cấu hình​

Một bộ các trường hợp xác thực cấu hình. Mỗi mục phải bao gồm một bộ hai mục trong đó mục đầu tiên là tên chuỗi của tùy chọn cấu hình và mục thứ hai là một trường hợp mkdocs.config.config_options.BaseConfigOptionhoặc bất kỳ lớp con nào của nó.

Ví dụ, sau đây config_schemeđịnh nghĩa ba tùy chọn cấu hình: foo, chấp nhận chuỗi; bar, chấp nhận số nguyên; và baz, chấp nhận giá trị boolean.

class MyPlugin(mkdocs.plugins.BasePlugin): config_scheme = ( ('foo', mkdocs.config.config_options.Type(str, default='a default value')), ('bar', mkdocs.config.config_options.Type(int, default=0)), ('baz', mkdocs.config.config_options.Type(bool, default=True)) )

Mới trong phiên bản 1.4

Phân lớp Configđể chỉ định lược đồ cấu hình​

Để có được lợi ích về an toàn kiểu, nếu bạn chỉ nhắm mục tiêu đến MkDocs 1.4+, hãy định nghĩa lược đồ cấu hình dưới dạng một lớp:

class MyPluginConfig(mkdocs.config.base.Config): foo = mkdocs.config.config_options.Type(str, default='a default value') bar = mkdocs.config.config_options.Type(int, default=0) baz = mkdocs.config.config_options.Type(bool, default=True) class MyPlugin(mkdocs.plugins.BasePlugin[MyPluginConfig]): ...
Ví dụ về định nghĩa cấu hình​

Ví dụ

from mkdocs.config import base, config_options as c class _ValidationOptions(base.Config): enabled = c.Type(bool, default=True) verbose = c.Type(bool, default=False) skip_checks = c.ListOfItems(c.Choice(('foo', 'bar', 'baz')), default=[]) class MyPluginConfig(base.Config): definition_file = c.File(exists=True) # required checksum_file = c.Optional(c.File(exists=True)) # can be None but must exist if specified validation = c.SubConfig(_ValidationOptions)

Theo quan điểm của người dùng SubConfigthì nó tương tự như Type(dict), chỉ là nó vẫn giữ nguyên khả năng xác thực: bạn xác định tất cả các khóa hợp lệ và mỗi giá trị phải tuân theo điều gì.

Và ListOfItemstương tự như Type(list), nhưng một lần nữa, chúng ta định nghĩa ràng buộc mà mỗi giá trị phải tuân thủ.

Điều này chấp nhận cấu hình như sau:

my_plugin: definition_file: configs/test.ini # relative to mkdocs.yml validation: enabled: !ENV [CI, false] verbose: true skip_checks: - foo - baz

Ví dụ

import numbers from mkdocs.config import base, config_options as c class _Rectangle(base.Config): width = c.Type(numbers.Real) # required height = c.Type(numbers.Real) # required class MyPluginConfig(base.Config): add_rectangles = c.ListOfItems(c.SubConfig(_Rectangle)) # required

Trong ví dụ này, chúng ta định nghĩa một danh sách các mục phức tạp và điều đó được thực hiện bằng cách truyền một giá trị cụ thể SubConfigtới ListOfItems.

Điều này chấp nhận cấu hình như sau:

my_plugin: add_rectangles: - width: 5 height: 7 - width: 12 height: 2

Khi cấu hình của người dùng được tải, lược đồ trên sẽ được sử dụng để xác thực cấu hình và điền vào bất kỳ mặc định nào cho các thiết lập không được người dùng cung cấp. Các lớp xác thực có thể là bất kỳ lớp nào được cung cấp trong mkdocs.config.config_optionshoặc một lớp con của bên thứ ba được xác định trong plugin.

Bất kỳ thiết lập nào do người dùng cung cấp không được xác thực hoặc không được xác định trong config_schemesẽ gây ra lỗi mkdocs.config.base.ValidationError.

cấu hình​

Từ điển các tùy chọn cấu hình cho plugin, được phương load_configpháp điền vào sau khi xác thực cấu hình hoàn tất. Sử dụng thuộc tính này để truy cập các tùy chọn do người dùng cung cấp.

def on_pre_build(self, config, **kwargs): if self.config['baz']: # implement "baz" functionality here...

Mới trong phiên bản 1.4

Truy cập an toàn dựa trên thuộc tính​

Để có được lợi ích về an toàn kiểu, nếu bạn chỉ nhắm mục tiêu đến MkDocs 1.4+, hãy truy cập các tùy chọn dưới dạng thuộc tính:

def on_pre_build(self, config, **kwargs): if self.config.baz: print(self.config.bar ** 2) # OK, `int ** 2` is valid.

Tất cả BasePlugincác lớp con đều chứa các phương thức sau:

load_config(tùy chọn)​

Tải cấu hình từ một từ điển tùy chọn. Trả về một bộ gồm (errors, warnings). Phương pháp này được MkDocs gọi trong quá trình xác thực cấu hình và không cần phải được plugin gọi.

Tên sự kiện​

Các phương thức tùy chọn xác định hành vi cho các sự kiện cụ thể . Plugin phải xác định hành vi của nó trong các phương thức này. Thay thế <event_name>bằng tên thực tế của sự kiện. Ví dụ, sự pre_buildkiện sẽ được xác định trong on_pre_buildphương thức.

Hầu hết các sự kiện chấp nhận một đối số vị trí và nhiều đối số từ khóa khác nhau. Nhìn chung, đối số vị trí được mong đợi sẽ được sửa đổi (hoặc thay thế) bởi plugin và được trả về. Nếu không có gì được trả về (phương thức trả về None), thì đối tượng gốc, chưa sửa đổi sẽ được sử dụng. Đối số từ khóa chỉ được cung cấp để cung cấp ngữ cảnh và/hoặc cung cấp dữ liệu có thể được sử dụng để xác định cách đối số vị trí nên được sửa đổi. Thực hành tốt là chấp nhận đối số từ khóa dưới dạng **kwargs. Trong trường hợp các từ khóa bổ sung được cung cấp cho một sự kiện trong phiên bản MkDocs trong tương lai, sẽ không cần phải thay đổi plugin của bạn.

Ví dụ: sự kiện sau sẽ thêm static_template vào cấu hình chủ đề:

class MyPlugin(BasePlugin): def on_config(self, config, **kwargs): config['theme'].static_templates.add('my_template.html') return config

Mới trong phiên bản 1.4

Để có được lợi ích về an toàn kiểu, nếu bạn chỉ nhắm mục tiêu đến MkDocs 1.4+, hãy truy cập các tùy chọn cấu hình dưới dạng thuộc tính:

def on_config(self, config: MkDocsConfig): config.theme.static_templates.add('my_template.html') return config

Sự kiện​

Có ba loại sự kiện: Sự kiện toàn cầu , Sự kiện trang và Sự kiện mẫu .

Xem sơ đồ có mối quan hệ giữa tất cả các sự kiện plugin

  • Bản thân các sự kiện được hiển thị màu vàng cùng với các thông số của chúng.
  • Các mũi tên hiển thị luồng đối số và đầu ra của mỗi sự kiện. Đôi khi chúng bị bỏ qua.
  • Các sự kiện được sắp xếp theo trình tự thời gian từ trên xuống dưới.
  • Các đường chấm xuất hiện ở phần chia tách từ sự kiện toàn cầu sang sự kiện theo từng trang.
  • Nhấp vào tiêu đề sự kiện để chuyển đến phần mô tả.

Sự kiện một lần​

Sự kiện một lần chạy một lần cho mỗi mkdocslần gọi. Trường hợp duy nhất mà chúng khác biệt rõ rệt so với sự kiện toàn cục là mkdocs serve: sự kiện toàn cục, không giống như những sự kiện này, sẽ chạy nhiều lần -- một lần cho mỗi lần dựng .

khi khởi động​

Sự kiện này startupdiễn ra một lần ngay khi bắt đầu mkdocslời cầu nguyện.

Tính năng mới trong MkDocs 1.4.

Sự hiện diện của một on_startupphương thức (kể cả khi rỗng) sẽ di chuyển plugin sang hệ thống mới, nơi đối tượng plugin được lưu giữ trong nhiều bản dựng trong một mkdocs serve.

Lưu ý rằng để khởi tạo biến, __init__phương pháp này vẫn được ưu tiên. Để khởi tạo biến cho mỗi bản dựng (và bất cứ khi nào còn nghi ngờ), hãy sử dụng on_configsự kiện.

Các thông số:

  • command ( Literal['build', 'gh-deploy', 'serve']) –

    lệnh mà MkDocs được gọi, ví dụ "phục vụ" cho mkdocs serve.

  • dirty ( bool) –

    cờ đã được thông qua chưa --dirty.

khi tắt máy​

Sự kiện này shutdownchạy một lần vào cuối lệnh mkdocsgọi trước khi thoát.

Sự kiện này chỉ liên quan đến việc hỗ trợ mkdocs serve, nếu không trong một bản dựng duy nhất sẽ không thể phân biệt được với on_post_build.

Tính năng mới trong MkDocs 1.4.

Sự hiện diện của một on_shutdownphương thức (kể cả khi rỗng) sẽ di chuyển plugin sang hệ thống mới, nơi đối tượng plugin được lưu giữ trong nhiều bản dựng trong một mkdocs serve.

Lưu ý rằng on_post_buildphương pháp này vẫn được ưu tiên để dọn dẹp khi có thể vì nó có khả năng kích hoạt thực sự cao hơn nhiều. on_shutdownlà "nỗ lực tốt nhất" vì nó dựa vào việc phát hiện việc tắt MkDocs một cách bình thường.

đang phục vụ​

Sự kiện này servechỉ được gọi khi servelệnh được sử dụng trong quá trình phát triển. Nó chỉ chạy một lần, sau khi bản dựng đầu tiên hoàn tất. Nó được truyền qua phiên Serverbản có thể được sửa đổi trước khi được kích hoạt. Ví dụ, các tệp hoặc thư mục bổ sung có thể được thêm vào danh sách các tệp "đã theo dõi" để tự động tải lại.

Các thông số:

  • server ( [LiveReloadServer](https://www.mkdocs.org/dev-guide/api/#mkdocs.livereload.LiveReloadServer "mkdocs.livereload.LiveReloadServer")) –

    livereload.Serverví dụ

  • config ( MkDocsConfig) –

    đối tượng cấu hình toàn cục

  • builder ( Callable) –

    một callable được chuyển đến mỗi cuộc gọi đếnserver.watch

Trả về:

  • [LiveReloadServer](https://www.mkdocs.org/dev-guide/api/#mkdocs.livereload.LiveReloadServer "mkdocs.livereload.LiveReloadServer") | None –

    livereload.Serverví dụ

Sự kiện toàn cầu​

Sự kiện toàn cầu được gọi một lần cho mỗi lần xây dựng ở đầu hoặc cuối quá trình xây dựng. Bất kỳ thay đổi nào được thực hiện trong các sự kiện này sẽ có tác động toàn cầu đến toàn bộ trang web.

trên_cấu_hình​

Sự kiện này configlà sự kiện đầu tiên được gọi khi xây dựng và được chạy ngay sau khi cấu hình người dùng được tải và xác thực. Bất kỳ thay đổi nào đối với cấu hình đều phải được thực hiện tại đây.

Các thông số:

  • config ( MkDocsConfig) –

    đối tượng cấu hình toàn cục

Trả về:

  • MkDocsConfig | None –

    đối tượng cấu hình toàn cục

đang_xây_dựng_trước​

Sự kiện này pre_buildkhông thay đổi bất kỳ biến nào. Sử dụng sự kiện này để gọi các tập lệnh dựng sẵn.

Các thông số:

  • config ( MkDocsConfig) –

    đối tượng cấu hình toàn cục

trên_tệp​

Sự fileskiện được gọi sau khi tập hợp tệp được điền từ docs_dir. Sử dụng sự kiện này để thêm, xóa hoặc thay đổi tệp trong tập hợp. Lưu ý rằng các đối tượng Trang vẫn chưa được liên kết với các đối tượng tệp trong tập hợp. Sử dụng Sự kiện Trang để thao tác dữ liệu cụ thể của trang.

Các thông số:

  • files ( [Files](https://www.mkdocs.org/dev-guide/api/#mkdocs.structure.files.Files "mkdocs.structure.files.Files")) –

    bộ sưu tập tập tin toàn cầu

  • config ( MkDocsConfig) –

    đối tượng cấu hình toàn cục

Trả về:

  • [Files](https://www.mkdocs.org/dev-guide/api/#mkdocs.structure.files.Files "mkdocs.structure.files.Files") | None –

    bộ sưu tập tập tin toàn cầu

trên_điều_hướng​

Sự kiện này navđược gọi sau khi điều hướng trang web được tạo và có thể được sử dụng để thay đổi điều hướng trang web.

Các thông số:

  • nav ( [Navigation](https://www.mkdocs.org/dev-guide/themes/#mkdocs.structure.nav.Navigation "mkdocs.structure.nav.Navigation")) –

    đối tượng điều hướng toàn cầu

  • config ( MkDocsConfig) –

    đối tượng cấu hình toàn cục

  • files ( [Files](https://www.mkdocs.org/dev-guide/api/#mkdocs.structure.files.Files "mkdocs.structure.files.Files")) –

    bộ sưu tập tập tin toàn cầu

Trả về:

  • [Navigation](https://www.mkdocs.org/dev-guide/themes/#mkdocs.structure.nav.Navigation "mkdocs.structure.nav.Navigation") | None –

    đối tượng điều hướng toàn cầu

trên_môi_trường​

Sự kiện này envđược gọi sau khi môi trường mẫu Jinja được tạo và có thể được sử dụng để thay đổi môi trường Jinja .

Các thông số:

  • env ( Environment) –

    môi trường Jinja toàn cầu

  • config ( MkDocsConfig) –

    đối tượng cấu hình toàn cục

  • files ( [Files](https://www.mkdocs.org/dev-guide/api/#mkdocs.structure.files.Files "mkdocs.structure.files.Files")) –

    bộ sưu tập tập tin toàn cầu

Trả về:

  • Environment | None –

    Môi trường Jinja toàn cầu

trên_bài_đăng_xây_dựng​

Sự kiện này post_buildkhông thay đổi bất kỳ biến nào. Sử dụng sự kiện này để gọi các tập lệnh sau khi xây dựng.

Các thông số:

  • config ( MkDocsConfig) –

    đối tượng cấu hình toàn cục

lỗi khi xây dựng​

Sự kiện này build_errorđược gọi sau khi MkDocs phát hiện ra bất kỳ loại ngoại lệ nào trong quá trình xây dựng. Sử dụng sự kiện này để dọn dẹp mọi thứ trước khi MkDocs kết thúc. Lưu ý rằng bất kỳ sự kiện nào khác được lên lịch chạy sau lỗi sẽ bị bỏ qua. Xem Xử lý lỗi để biết thêm chi tiết.

Các thông số:

  • error ( Exception) –

    ngoại lệ được nêu ra

Sự kiện mẫu​

Các sự kiện mẫu được gọi một lần cho mỗi mẫu không phải trang. Mỗi sự kiện mẫu sẽ được gọi cho mỗi mẫu được xác định trong thiết lập cấu hình extra_templates cũng như bất kỳ static_templates nào được xác định trong chủ đề. Tất cả các sự kiện mẫu được gọi sau sự kiện env và trước bất kỳ sự kiện trang nào .

trên_mẫu_trước​

Sự kiện này pre_templateđược gọi ngay sau khi mẫu chủ đề được tải và có thể được sử dụng để thay đổi mẫu.

Các thông số:

  • template ( Template) –

  • template_name ( str) –

    chuỗi tên tập tin của mẫu

  • config ( MkDocsConfig) –

    đối tượng cấu hình toàn cục

Trả về:

  • Template | None –
trên_mẫu_bối_cảnh​

Sự kiện này template_contextđược gọi ngay sau khi ngữ cảnh được tạo cho mẫu chủ đề và chỉ có thể được sử dụng để thay đổi ngữ cảnh cho mẫu cụ thể đó.

Các thông số:

  • context ( [TemplateContext](https://www.mkdocs.org/dev-guide/api/#mkdocs.utils.templates.TemplateContext "mkdocs.utils.templates.TemplateContext")) –

    dict của các biến ngữ cảnh mẫu

  • template_name ( str) –

    chuỗi tên tập tin của mẫu

  • config ( MkDocsConfig) –

    đối tượng cấu hình toàn cục

Trả về:

  • [TemplateContext](https://www.mkdocs.org/dev-guide/api/#mkdocs.utils.templates.TemplateContext "mkdocs.utils.templates.TemplateContext") | None –

    dict của các biến ngữ cảnh mẫu

mẫu_bài_đăng​

Sự post_templatekiện được gọi sau khi mẫu được hiển thị, nhưng trước khi nó được ghi vào đĩa và có thể được sử dụng để thay đổi đầu ra của mẫu. Nếu một chuỗi rỗng được trả về, mẫu sẽ bị bỏ qua và không có gì được ghi vào đĩa.

Các thông số:

  • output_content ( str) –

    đầu ra của mẫu được kết xuất dưới dạng chuỗi

  • template_name ( str) –

    chuỗi tên tập tin của mẫu

  • config ( MkDocsConfig) –

    đối tượng cấu hình toàn cục

Trả về:

  • str | None –

    đầu ra của mẫu được kết xuất dưới dạng chuỗi

Sự kiện trang​

Sự kiện trang được gọi một lần cho mỗi trang Markdown có trong trang web. Tất cả sự kiện trang được gọi sau sự kiện post_template và trước sự kiện post_build .

trên trang trước​

Sự kiện này pre_pageđược gọi trước khi bất kỳ hành động nào được thực hiện trên trang chủ đề và có thể được sử dụng để thay đổi Pagephiên bản.

Các thông số:

  • page ( [Page](https://www.mkdocs.org/dev-guide/themes/#mkdocs.structure.pages.Page "mkdocs.structure.pages.Page")) –

    mkdocs.structure.pages.Pageví dụ

  • config ( MkDocsConfig) –

    đối tượng cấu hình toàn cục

  • files ( [Files](https://www.mkdocs.org/dev-guide/api/#mkdocs.structure.files.Files "mkdocs.structure.files.Files")) –

    bộ sưu tập tập tin toàn cầu

Trả về:

  • [Page](https://www.mkdocs.org/dev-guide/themes/#mkdocs.structure.pages.Page "mkdocs.structure.pages.Page") | None –

    mkdocs.structure.pages.Pageví dụ

trên trang_đọc_nguồn​

Đã lỗi thời

Thay vì sự kiện này, hãy chọn một trong những lựa chọn thay thế sau:

  • Kể từ MkDocs 1.6, thay vào đó hãy đặt content_bytes/ content_stringcủa a Filebên trong on_files.
  • Thông thường (mặc dù không phải là giải pháp thay thế chính xác) on_page_markdowncó thể phục vụ cùng một mục đích.

Sự kiện này on_page_read_sourcecó thể thay thế cơ chế mặc định để đọc nội dung của nguồn trang từ hệ thống tập tin.

Các thông số:

  • page ( [Page](https://www.mkdocs.org/dev-guide/themes/#mkdocs.structure.pages.Page "mkdocs.structure.pages.Page")) –

    mkdocs.structure.pages.Pageví dụ

  • config ( MkDocsConfig) –

    đối tượng cấu hình toàn cục

Trả về:

  • str | None –

    Nguồn thô cho một trang dưới dạng chuỗi unicode. Nếu Noneđược trả về, việc tải mặc định từ một tệp sẽ được thực hiện.

trên_trang_đánh_dấu​

Sự page_markdownkiện được gọi sau khi markdown của trang được tải từ tệp và có thể được sử dụng để thay đổi văn bản nguồn Markdown. Siêu dữ liệu đã được loại bỏ và có sẵn tại page.metathời điểm này.

Các thông số:

  • markdown ( str) –

    Markdown văn bản nguồn của trang dưới dạng chuỗi

  • page ( [Page](https://www.mkdocs.org/dev-guide/themes/#mkdocs.structure.pages.Page "mkdocs.structure.pages.Page")) –

    mkdocs.structure.pages.Pageví dụ

  • config ( MkDocsConfig) –

    đối tượng cấu hình toàn cục

  • files ( [Files](https://www.mkdocs.org/dev-guide/api/#mkdocs.structure.files.Files "mkdocs.structure.files.Files")) –

    bộ sưu tập tập tin toàn cầu

Trả về:

  • str | None –

    Markdown văn bản nguồn của trang dưới dạng chuỗi

trên_trang_nội_dung​

Sự kiện này page_contentđược gọi sau khi văn bản Markdown được hiển thị thành HTML (nhưng trước khi được chuyển đến mẫu) và có thể được sử dụng để thay đổi nội dung HTML của trang.

Các thông số:

  • html ( str) –

    HTML được hiển thị từ nguồn Markdown dưới dạng chuỗi

  • page ( [Page](https://www.mkdocs.org/dev-guide/themes/#mkdocs.structure.pages.Page "mkdocs.structure.pages.Page")) –

    mkdocs.structure.pages.Pageví dụ

  • config ( MkDocsConfig) –

    đối tượng cấu hình toàn cục

  • files ( [Files](https://www.mkdocs.org/dev-guide/api/#mkdocs.structure.files.Files "mkdocs.structure.files.Files")) –

    bộ sưu tập tập tin toàn cầu

Trả về:

  • str | None –

    HTML được hiển thị từ nguồn Markdown dưới dạng chuỗi

trên_trang_bối_cảnh​

Sự kiện này page_contextđược gọi sau khi ngữ cảnh cho một trang được tạo và chỉ có thể được sử dụng để thay đổi ngữ cảnh cho trang cụ thể đó.

Các thông số:

  • context ( [TemplateContext](https://www.mkdocs.org/dev-guide/api/#mkdocs.utils.templates.TemplateContext "mkdocs.utils.templates.TemplateContext")) –

    dict của các biến ngữ cảnh mẫu

  • page ( [Page](https://www.mkdocs.org/dev-guide/themes/#mkdocs.structure.pages.Page "mkdocs.structure.pages.Page")) –

    mkdocs.structure.pages.Pageví dụ

  • config ( MkDocsConfig) –

    đối tượng cấu hình toàn cục

  • nav ( [Navigation](https://www.mkdocs.org/dev-guide/themes/#mkdocs.structure.nav.Navigation "mkdocs.structure.nav.Navigation")) –

    đối tượng điều hướng toàn cầu

Trả về:

  • [TemplateContext](https://www.mkdocs.org/dev-guide/api/#mkdocs.utils.templates.TemplateContext "mkdocs.utils.templates.TemplateContext") | None –

    dict của các biến ngữ cảnh mẫu

trên trang_bài_đăng​

Sự post_pagekiện được gọi sau khi mẫu được hiển thị, nhưng trước khi nó được ghi vào đĩa và có thể được sử dụng để thay đổi đầu ra của trang. Nếu một chuỗi rỗng được trả về, trang sẽ bị bỏ qua và không có gì được ghi vào đĩa.

Các thông số:

  • output ( str) –

    đầu ra của mẫu được kết xuất dưới dạng chuỗi

  • page ( [Page](https://www.mkdocs.org/dev-guide/themes/#mkdocs.structure.pages.Page "mkdocs.structure.pages.Page")) –

    mkdocs.structure.pages.Pageví dụ

  • config ( MkDocsConfig) –

    đối tượng cấu hình toàn cục

Trả về:

  • str | None –

    đầu ra của mẫu được kết xuất dưới dạng chuỗi

Ưu tiên sự kiện​

Đối với mỗi loại sự kiện, các phương thức plugin tương ứng được gọi theo thứ tự các plugin xuất hiện trong plugins cấu hình .

Kể từ MkDocs 1.4, các plugin có thể chọn đặt giá trị ưu tiên cho các sự kiện của chúng. Các sự kiện có mức ưu tiên cao hơn sẽ được gọi trước. Các sự kiện không có mức ưu tiên được chọn sẽ có giá trị mặc định là 0. Các sự kiện có cùng mức ưu tiên sẽ được sắp xếp theo thứ tự xuất hiện trong cấu hình.

mkdocs.plugins.event_priority(priority: float) -> Callable[[T], T]​

Một trình trang trí để thiết lập mức độ ưu tiên sự kiện cho phương thức xử lý sự kiện.

Giá trị ưu tiên được đề xuất: 100"đầu tiên", 50"sớm", 0"mặc định", -50"muộn", -100"cuối cùng". Khi các plugin khác nhau khám phá ra mối quan hệ chính xác hơn với nhau, các giá trị nên được điều chỉnh thêm.

Ví dụ sử dụng:

@plugins.event_priority(-100) # Wishing to run this after all other plugins' `on_files` events. def on_files(self, files, config, **kwargs): ...

Mới trong MkDocs 1.4. Shim được đề xuất để tương thích ngược:

try: from mkdocs.plugins import event_priority except ImportError: event_priority = lambda priority: lambda f: f # No-op fallback

Mới trong phiên bản 1.6

Ngoài ra, có thể phát sinh nhu cầu phải đăng ký trình xử lý cho cùng một sự kiện ở nhiều mức độ ưu tiên khác nhau.

CombinedEventlàm cho điều này có thể xảy ra.

mkdocs.plugins.CombinedEvent​

Các căn cứ:Generic[P, T]

Một mô tả cho phép xác định nhiều trình xử lý sự kiện và khai báo chúng dưới một tên sự kiện.

Ví dụ sử dụng:

@plugins.event_priority(100) def _on_page_markdown_1(self, markdown: str, **kwargs): ... @plugins.event_priority(-50) def _on_page_markdown_2(self, markdown: str, **kwargs): ... on_page_markdown = plugins.CombinedEvent(_on_page_markdown_1, _on_page_markdown_2)

Ghi chú

Tên của các phương thức phụ không thể bắt đầu bằng on_; thay vào đó, chúng có thể bắt đầu bằng _on_như trong ví dụ trên hoặc bất kỳ tên nào khác.

Xử lý lỗi​

MkDocs định nghĩa bốn loại lỗi:

mkdocs.exceptions.MkDocsException​

Các căn cứ:ClickException

Lớp cơ sở mà tất cả các ngoại lệ MkDocs kế thừa từ đó. Lớp này không nên được nâng lên trực tiếp. Một trong các lớp con nên được nâng lên thay thế.

mkdocs.exceptions.ConfigurationError​

Các căn cứ:[MkDocsException](https://www.mkdocs.org/dev-guide/plugins/#mkdocs.exceptions.MkDocsException "mkdocs.exceptions.MkDocsException")

Lỗi này được đưa ra bởi xác thực cấu hình khi gặp phải lỗi xác thực. Lỗi này sẽ được đưa ra bởi bất kỳ tùy chọn cấu hình nào được xác định trong config_scheme của plugin .

mkdocs.exceptions.BuildError​

Các căn cứ:[MkDocsException](https://www.mkdocs.org/dev-guide/plugins/#mkdocs.exceptions.MkDocsException "mkdocs.exceptions.MkDocsException")

Lỗi này có thể được MkDocs đưa ra trong quá trình xây dựng. Các plugin không nên đưa ra lỗi này.

mkdocs.exceptions.PluginError​

Các căn cứ:[BuildError](https://www.mkdocs.org/dev-guide/plugins/#mkdocs.exceptions.BuildError "mkdocs.exceptions.BuildError")

Một lớp con mkdocs.exceptions.BuildErrorcó thể được kích hoạt bằng các sự kiện plugin.

Các ngoại lệ không mong muốn và không được phát hiện sẽ làm gián đoạn quá trình xây dựng và tạo ra các dấu vết Python điển hình, hữu ích cho việc gỡ lỗi mã của bạn. Tuy nhiên, người dùng thường thấy các dấu vết quá tải và thường bỏ lỡ thông báo lỗi hữu ích. Do đó, MkDocs sẽ phát hiện bất kỳ lỗi nào được liệt kê ở trên, truy xuất thông báo lỗi và thoát ngay lập tức chỉ với thông báo hữu ích được hiển thị cho người dùng.

Do đó, bạn có thể muốn bắt bất kỳ ngoại lệ nào trong plugin của mình và đưa ra PluginError, truyền vào thông báo tùy chỉnh của riêng bạn, để quá trình xây dựng bị hủy bỏ với một thông báo hữu ích.

Sự kiện on_build_error sẽ được kích hoạt khi có bất kỳ ngoại lệ nào.

Ví dụ:

from mkdocs.exceptions import PluginError from mkdocs.plugins import BasePlugin class MyPlugin(BasePlugin): def on_post_page(self, output, page, config, **kwargs): try: # some code that could throw a KeyError ... except KeyError as error: raise PluginError(f"Failed to find the item by key: '{error}'") def on_build_error(self, error, **kwargs): # some code to clean things up ...

Đăng nhập vào plugin​

Để đảm bảo rằng thông báo nhật ký của plugin tuân thủ định dạng và cờ của MkDocs --verbose, --debugvui lòng ghi nhật ký vào trình ghi theo mkdocs.plugins.không gian tên.

Ví dụ

import logging log = logging.getLogger(f"mkdocs.plugins.{__name__}") log.warning("File '%s' not found. Breaks the build if --strict is passed", my_file_name) log.info("Shown normally") log.debug("Shown only with `--verbose`") if log.getEffectiveLevel() <= logging.DEBUG: log.debug("Very expensive calculation only for debugging: %s", get_my_diagnostics())

log.error()là một mức ghi nhật ký khác được phân biệt bằng giao diện, nhưng theo mọi cách khác, nó hoạt động giống như warning, nên việc sử dụng nó rất lạ. Nếu plugin của bạn gặp lỗi thực tế, tốt nhất là chỉ cần ngắt quá trình xây dựng bằng cách raise mkdocs.exceptions.PluginError(điều này cũng sẽ ghi lại thông báo ERROR).

Mới trong phiên bản 1.5

MkDocs hiện cung cấp một get_plugin_logger()hàm tiện ích trả về một trình ghi nhật ký như trên, cũng được thêm tiền tố là tên của plugin.

mkdocs.plugins.get_plugin_logger(name: str) -> PrefixedLogger​

Trả về trình ghi nhật ký cho các plugin.

Các thông số:

  • name ( str) –

    Tên sử dụng với logging.getLogger.

Trả về:

  • PrefixedLogger –

    Một trình ghi được cấu hình để hoạt động tốt trong MkDocs, thêm tiền tố cho mỗi tin nhắn bằng tên gói plugin.

Ví dụ

from mkdocs.plugins import get_plugin_logger log = get_plugin_logger(__name__) log.info("My plugin message")

Điểm vào​

Các plugin cần được đóng gói dưới dạng thư viện Python (phân phối trên PyPI tách biệt với MkDocs) và mỗi plugin phải đăng ký dưới dạng Plugin thông qua setuptools entry_points. Thêm nội dung sau vào setup.pytập lệnh của bạn:

entry_points={ 'mkdocs.plugins': [ 'pluginname = path.to.some_plugin:SomePluginClass', ] }

Sẽ pluginnamelà tên được người dùng sử dụng (trong tệp cấu hình) và path.to.some_plugin:SomePluginClasssẽ là plugin có thể nhập ( from path.to.some_plugin import SomePluginClass) trong đó SomePluginClasslà một lớp con của BasePlugin định nghĩa hành vi của plugin. Đương nhiên, nhiều lớp Plugin có thể tồn tại trong cùng một mô-đun. Chỉ cần định nghĩa từng lớp như một điểm vào riêng biệt.

entry_points={ 'mkdocs.plugins': [ 'featureA = path.to.my_plugins:PluginA', 'featureB = path.to.my_plugins:PluginB' ] }

Lưu ý rằng việc đăng ký plugin không kích hoạt plugin đó. Người dùng vẫn cần phải yêu cầu MkDocs sử dụng plugin đó thông qua config.

Xuất bản một Plugin​

Bạn nên xuất bản một gói trên PyPI , sau đó thêm nó vào Catalog để có thể khám phá. Các plugin được khuyến khích mạnh mẽ để có một tên plugin duy nhất (tên điểm vào) theo catalog.

5:11:02 AM