Cấu hình

Hướng dẫn tất cả các thiết lập cấu hình có sẵn.

---

Giới thiệu

Cài đặt dự án được cấu hình theo mặc định bằng cách sử dụng tệp cấu hình YAML trong thư mục dự án có tên mkdocs.yml. Bạn có thể chỉ định đường dẫn khác cho nó bằng cách sử dụng tùy chọn -f/ --config-file(xem mkdocs build --help).

Ít nhất, tệp cấu hình này phải chứa site_name. Tất cả các thiết lập khác là tùy chọn.

Thông tin dự án

tên_trang_web

Đây là thiết lập bắt buộc và phải là chuỗi được sử dụng làm tiêu đề chính cho tài liệu dự án. Ví dụ:

site_name: Marshmallow Generator

Khi hiển thị chủ đề, thiết lập này sẽ được truyền dưới dạng site_namebiến ngữ cảnh.

URL trang web

Đặt URL chuẩn của trang web. Điều này sẽ thêm một linkthẻ có canonicalURL vào headphần của mỗi trang HTML. Nếu 'gốc' của trang web MkDocs sẽ nằm trong một thư mục con của một tên miền, hãy đảm bảo đưa thư mục con đó vào cài đặt ( https://example.com/foo/).

Thiết lập này cũng được sử dụng cho mkdocs serve: máy chủ sẽ được gắn vào đường dẫn lấy từ thành phần đường dẫn của URL, ví dụ some/page.mdsẽ được phục vụ từ http://127.0.0.1:8000/foo/some/page/để mô phỏng bố cục từ xa dự kiến.

mặc định :null

url_kho_hàng

Khi được thiết lập, sẽ cung cấp liên kết đến kho lưu trữ của bạn (GitHub, Bitbucket, GitLab, ...) trên mỗi trang.

repo_url: https://github.com/example/repository/

mặc định :null

tên kho lưu trữ

Khi được thiết lập, cung cấp tên cho liên kết đến kho lưu trữ của bạn trên mỗi trang.

mặc định : 'GitHub'hoặc nếu khớp với các miền đó, nếu không thì tên máy 'Bitbucket'chủ từ .'GitLab'``repo_url``repo_url

chỉnh sửa_uri

Đường dẫn từ cơ sở repo_urlđến thư mục docs khi xem trực tiếp một trang, tính đến các thông số cụ thể của máy chủ lưu trữ (ví dụ GitHub, Bitbucket, v.v.), nhánh và chính thư mục docs. MkDocs nối repo_url và edit_uri, và thêm đường dẫn đầu vào của trang.

Khi được thiết lập và nếu chủ đề của bạn hỗ trợ, sẽ cung cấp liên kết trực tiếp đến trang trong kho lưu trữ nguồn của bạn. Điều này giúp bạn dễ dàng tìm và chỉnh sửa nguồn cho trang. Nếu repo_urlkhông được thiết lập, tùy chọn này sẽ bị bỏ qua. Trên một số chủ đề, việc thiết lập tùy chọn này có thể khiến liên kết chỉnh sửa được sử dụng thay cho liên kết kho lưu trữ. Các chủ đề khác có thể hiển thị cả hai liên kết.

Hỗ trợ các edit_uriký tự truy vấn ('?') và phân đoạn ('#'). Đối với các máy chủ lưu trữ sử dụng truy vấn hoặc phân đoạn để truy cập các tệp, edit_uricó thể được đặt như sau. (Lưu ý ?và #trong URI...)

# Query string example edit_uri: '?query=root/path/docs/'

# Hash fragment example edit_uri: '#root/path/docs/'

Đối với các máy chủ lưu trữ khác, chỉ cần chỉ định đường dẫn tương đối đến thư mục docs.

# Query string example edit_uri: root/path/docs/

Ví dụ, có cấu hình này:

repo_url: https://example.com/project/repo edit_uri: blob/main/docs/

có nghĩa là một trang có tên 'foo/bar.md' sẽ có liên kết chỉnh sửa dẫn đến:
https://example.com/project/repo/blob/main/docs/foo/bar.md

edit_urithực tế có thể chỉ là một URL tuyệt đối, không nhất thiết phải tương đối với repo_url, do đó điều này có thể đạt được kết quả tương tự:

edit_uri: https://example.com/project/repo/blob/main/docs/

Để linh hoạt hơn, hãy xem edit_uri_template bên dưới.

Ghi chú

Trên một số máy chủ đã biết (cụ thể là GitHub, Bitbucket và GitLab), the edit_uriđược lấy từ 'repo_url' và không cần phải thiết lập thủ công. Chỉ cần xác định a repo_urlsẽ tự động điền vào edit_uricài đặt cấu hình.

Ví dụ, đối với kho lưu trữ được lưu trữ trên GitHub hoặc GitLab, edit_uri sẽ tự động được đặt thành edit/master/docs/(Lưu ý editđường dẫn và masternhánh).

Đối với kho lưu trữ do Bitbucket lưu trữ, giá trị tương đương edit_urisẽ tự động được đặt thành src/default/docs/(lưu ý srcđường dẫn và default nhánh).

Để sử dụng URI khác với URI mặc định (ví dụ: nhánh khác), chỉ cần đặt edit_urithành chuỗi mong muốn của bạn. Nếu bạn không muốn bất kỳ "liên kết chỉnh sửa URL" nào được hiển thị trên các trang của mình, hãy đặt edit_urithành chuỗi trống để tắt cài đặt tự động.

Cảnh báo

Trên GitHub và GitLab, đường dẫn "edit" mặc định ( edit/master/docs/) mở trang trong trình chỉnh sửa trực tuyến. Chức năng này yêu cầu người dùng phải có và đã đăng nhập vào tài khoản GitHub/GitLab. Nếu không, người dùng sẽ được chuyển hướng đến trang đăng nhập/đăng ký. Ngoài ra, hãy sử dụng đường dẫn "blob" ( blob/master/docs/) để mở chế độ xem chỉ đọc, hỗ trợ truy cập ẩn danh.

mặc định : edit/master/docs/cho kho lưu trữ GitHub và GitLab hoặc src/default/docs/cho kho lưu trữ Bitbucket, nếu repo_urlkhớp với các tên miền đó, nếu khôngnull

sửa_mẫu_uri

Biến thể linh hoạt hơn của edit_uri . Hai biến thể này tương đương nhau:

edit_uri: 'blob/main/docs/' edit_uri_template: 'blob/main/docs/{path}'

(chúng cũng loại trừ lẫn nhau -- đừng chỉ rõ cả hai).

Bắt đầu từ đây, bạn có thể thay đổi vị trí hoặc định dạng của đường dẫn, trong trường hợp cách thêm đường dẫn mặc định không đủ.

Nội dung của edit_uri_templatelà các chuỗi định dạng Python thông thường , chỉ có các trường sau đây khả dụng:

• {path}, ví dụfoo/bar.md
• {path_noext}, ví dụfoo/bar

Và cờ chuyển đổi !qcó sẵn để mã hóa phần trăm trường:

• {path!q}, ví dụfoo%2Fbar.md

Cấu hình hữu ích được đề xuất:

• GitHub Wiki:
  (ví dụ https://github.com/project/repo/wiki/foo/bar/_edit)

  repo_url: 'https://github.com/project/repo/wiki' edit_uri_template: '{path_noext}/_edit'

• Trình soạn thảo BitBucket:
  (ví dụ https://bitbucket.org/project/repo/src/master/docs/foo/bar.md?mode=edit)

  repo_url: 'https://bitbucket.org/project/repo/' edit_uri_template: 'src/master/docs/{path}?mode=edit'

• Trình chỉnh sửa trang web tĩnh GitLab:
  (ví dụ https://gitlab.com/project/repo/-/sse/master/docs%2Ffoo%2bar.md)

  repo_url: 'https://gitlab.com/project/repo' edit_uri_template: '-/sse/master/docs%2F{path!q}'

• GitLab Web IDE:
  (ví dụ https://gitlab.com/-/ide/project/repo/edit/master/-/docs/foo/bar.md)

  edit_uri_template: 'https://gitlab.com/-/ide/project/repo/edit/master/-/docs/{path}'

mặc định :null

mô tả trang web

Đặt mô tả trang web. Thao tác này sẽ thêm thẻ meta vào tiêu đề HTML đã tạo.

mặc định :null

Đặt tên tác giả. Thao tác này sẽ thêm thẻ meta vào tiêu đề HTML đã tạo.

mặc định :null

bản quyền

Thiết lập thông tin bản quyền sẽ được đưa vào tài liệu theo chủ đề.

mặc định :null

nhánh_từ_xa

Đặt nhánh từ xa để cam kết khi sử dụng gh-deployđể triển khai tới GitHub Pages. Tùy chọn này có thể được ghi đè bằng tùy chọn dòng lệnh trong gh-deploy.

mặc định :gh-pages

tên_từ_xa

Đặt tên từ xa để đẩy tới khi sử dụng gh-deployđể triển khai tới GitHub Pages. Tùy chọn này có thể được ghi đè bằng tùy chọn dòng lệnh trong gh-deploy.

mặc định :origin

Bố cục tài liệu

dẫn đường

Thiết lập này được sử dụng để xác định định dạng và bố cục của điều hướng toàn cầu cho trang web. Cấu hình điều hướng tối thiểu có thể trông như thế này:

nav: - 'index.md' - 'about.md'

Tất cả các đường dẫn trong cấu hình điều hướng phải liên quan đến docs_dirtùy chọn cấu hình. Xem phần về cấu hình trang và điều hướng để biết thông tin chi tiết hơn, bao gồm cách tạo các phần phụ.

Các mục điều hướng cũng có thể bao gồm các liên kết đến các trang web bên ngoài. Trong khi tiêu đề là tùy chọn cho các liên kết nội bộ, chúng là bắt buộc đối với các liên kết bên ngoài. Một liên kết bên ngoài có thể là một URL đầy đủ hoặc một URL tương đối. Bất kỳ đường dẫn nào không tìm thấy trong các tệp đều được coi là một liên kết bên ngoài. Xem phần về Siêu dữ liệu về cách MkDocs xác định tiêu đề trang của một tài liệu.

nav: - Introduction: 'index.md' - 'about.md' - 'Issue Tracker': 'https://example.com/'

Trong ví dụ trên, hai mục đầu tiên trỏ đến các tệp cục bộ trong khi mục thứ ba trỏ đến một trang web bên ngoài.

Tuy nhiên, đôi khi trang web MkDocs được lưu trữ trong một thư mục con của trang web dự án và bạn có thể muốn liên kết đến các phần khác của cùng một trang web mà không bao gồm tên miền đầy đủ. Trong trường hợp đó, bạn có thể sử dụng URL tương đối phù hợp.

site_url: https://example.com/foo/ nav: - Home: '../' - 'User Guide': 'user-guide.md' - 'Bug Tracker': '/bugs/'

Trong ví dụ trên, hai kiểu liên kết ngoài khác nhau được sử dụng. Đầu tiên, lưu ý rằng the site_urlchỉ ra rằng trang web MkDocs được lưu trữ trong /foo/ thư mục con của tên miền. Do đó, Homemục điều hướng là một liên kết tương đối bước lên một cấp đến gốc máy chủ và thực sự trỏ đến https://example.com/. Bug TrackerMục này sử dụng đường dẫn tuyệt đối từ gốc máy chủ và thực sự trỏ đến https://example.com/bugs/. Tất nhiên, the User Guidetrỏ đến một trang MkDocs cục bộ.

mặc định : Theo mặc định navsẽ chứa danh sách lồng nhau được sắp xếp theo thứ tự chữ và số của tất cả các tệp Markdown được tìm thấy trong docs_dirvà các thư mục con của nó. Các tệp chỉ mục sẽ luôn được liệt kê đầu tiên trong một phần phụ.

loại trừ_tài_liệu

Mới trong phiên bản 1.5

Đã thay đổi trong phiên bản 1.6:

Cấu hình này không còn áp dụng chức năng "bản nháp" cho mkdocs serve. Nếu bạn có tài liệu bản nháp mà bạn muốn có trong "serve" chứ không phải "build", hãy thay thế exclude_docsbằng draft_docstùy chọn cấu hình mới.

Cấu hình này xác định các mẫu tệp (bên dưới docs_dir) sẽ không được đưa vào trang web đã xây dựng.

Ví dụ:

exclude_docs: | api-config.json # A file with this name anywhere. /requirements.txt # Top-level "docs/requirements.txt". *.py # Any file with this extension anywhere. !/foo/example.py # But keep this particular file.

Điều này tuân theo định dạng mẫu .gitignore .

Các giá trị mặc định sau đây luôn được thêm ngầm định vào trước - để loại trừ các tệp chấm (và thư mục) cũng như templatesthư mục cấp cao nhất:

exclude_docs: | .* /templates/

Vì vậy, để thực sự bắt đầu cấu hình này một cách mới mẻ, trước tiên bạn cần phải chỉ định phiên bản phủ định của các mục nhập này.

Nếu không, bạn có thể chỉ chọn một số tệp dấu chấm nhất định trở lại trang web:

exclude_docs: | !.assets # Don't exclude '.assets' although all other '.*' are excluded

bản nháp_tài_liệu

Mới trong phiên bản 1.6

Cấu hình này định nghĩa các mẫu tệp (bên dưới docs_dir) được coi là bản nháp. Các tệp nháp có sẵn trong quá trình này mkdocs servevà bao gồm dấu "DRAFT" nhưng sẽ không được bao gồm trong bản dựng. Để ngăn chặn hiệu ứng này và làm cho "serve" hoạt động giống như "build", bạn có thể chạy mkdocs serve --clean.

Ví dụ:

draft_docs: | drafts/ # A "drafts" directory anywhere. _unpublished.md # A md file ending in _unpublished.md !/foo_unpublished.md # But keep this particular file.

Điều này tuân theo định dạng mẫu .gitignore .

không_trong_điều_hướng

Mới trong phiên bản 1.5

Mới trong phiên bản 1.6:

Nếu navcấu hình không được chỉ định, các trang được chỉ định trong cấu hình này sẽ bị loại khỏi điều hướng suy ra.

Nếu bạn muốn đưa một số tài liệu vào trang web nhưng cố tình loại trừ chúng khỏi phần điều hướng, thông thường MkDocs sẽ cảnh báo về điều này.

Việc thêm các mẫu tệp như vậy (liên quan đến docs_dir) vào not_in_navcấu hình sẽ ngăn chặn các cảnh báo như vậy.

Ví dụ:

nav: - Foo: foo.md - Bar: bar.md not_in_nav: | /private.md

Giống như tùy chọn trước, tùy chọn này tuân theo định dạng mẫu .gitignore.

Ghi chú

Việc thêm một tập tin nhất định vào exclude_docssẽ có mức độ ưu tiên hơn và ngụ ý not_in_nav.

xác thực

Mới trong phiên bản 1.5

Cấu hình mức độ nghiêm ngặt của thông báo chẩn đoán của MkDocs khi xác thực liên kết tới tài liệu.

Đây là một cây cấu hình, và đối với mỗi cấu hình, giá trị có thể là một trong ba giá trị sau: warn, info, ignore. Điều này khiến thông báo ghi nhật ký có mức độ nghiêm trọng tương ứng được tạo ra. warnTất nhiên, mức này được dùng để sử dụng với mkdocs build --strict(nơi nó trở thành lỗi), mà bạn có thể sử dụng trong quá trình thử nghiệm liên tục.

Cấu hình này validation.links.absolute_linkscũng có giá trị đặc biệt relative_to_docsđể xác thực các liên kết tuyệt đối .

Mặc định của cấu hình này kể từ MkDocs 1.6:

validation: nav: omitted_files: info not_found: warn absolute_links: info links: not_found: warn anchors: info absolute_links: info unrecognized_links: info

(Lưu ý: bạn không nên sao chép toàn bộ ví dụ này vì nó chỉ sao chép các giá trị mặc định. Chỉ nên thiết lập các mục riêng lẻ có sự khác biệt.)

Mặc định của một số hành vi đã khác so với MkDocs 1.4 trở về trước - chúng đã bị bỏ qua trước đó.

Cấu hình MkDocs 1.6 để hoạt động giống như MkDocs 1.4 trở về trước (giảm tính nghiêm ngặt):

validation: absolute_links: ignore unrecognized_links: ignore anchors: ignore

Cài đặt được đề xuất cho hầu hết các trang web (mức độ nghiêm ngặt tối đa):

validation: omitted_files: warn absolute_links: warn # Or 'relative_to_docs' - new in MkDocs 1.6 unrecognized_links: warn anchors: warn # New in MkDocs 1.6

Lưu ý cách chúng ta bỏ qua các phím 'nav' và 'links' trong các ví dụ trên. Ở đây absolute_links:có nghĩa là thiết lập cả hai nav: absolute_links:và links: absolute_links:.

Danh sách đầy đủ các giá trị và ví dụ về thông báo nhật ký mà họ có thể ẩn hoặc làm nổi bật hơn:

• validation.nav.omitted_files

  • Các trang sau đây có trong thư mục docs nhưng không được bao gồm trong cấu hình "nav": ...

• validation.nav.not_found

  • Tham chiếu đến 'foo/bar.md' được bao gồm trong cấu hình 'nav', không có trong các tệp tài liệu.

  • Tham chiếu đến 'foo/bar.md' được bao gồm trong cấu hình 'nav', nhưng tệp này bị loại trừ khỏi trang web đã xây dựng.

• validation.nav.absolute_links

  • Đường dẫn tuyệt đối tới '/foo/bar.html' được bao gồm trong cấu hình 'nav', có lẽ trỏ tới một tài nguyên bên ngoài.

• validation.links.not_found

  • Tệp tài liệu 'example.md' chứa liên kết '../foo/bar.md', nhưng không tìm thấy mục tiêu trong số các tệp tài liệu.

  • Tệp tài liệu 'example.md' chứa liên kết đến 'foo/bar.md' bị loại trừ khỏi trang web đã xây dựng.

• validation.links.anchors

  • Tệp tài liệu 'example.md' chứa liên kết '../foo/bar.md#some-heading', nhưng tài liệu 'foo/bar.md' không chứa liên kết '#some-heading'.

  • Tệp tài liệu 'example.md' chứa liên kết '#some-heading', nhưng không có liên kết nào như vậy trên trang này.

• validation.links.absolute_links

  • Tệp tài liệu 'example.md' chứa liên kết tuyệt đối '/foo/bar.html', nó được giữ nguyên. Ý bạn là 'foo/bar.md' phải không?

• validation.links.unrecognized_links

  • Tệp tài liệu 'example.md' chứa liên kết tương đối không xác định '../foo/bar/', nó được giữ nguyên. Ý bạn là 'foo/bar.md' phải không?

  • Tệp tài liệu 'example.md' chứa liên kết tương đối không xác định 'mail@example.com', nó được giữ nguyên. Ý bạn là 'mailto:mail@example.com' phải không?

Xác thực các liên kết tuyệt đối

Mới trong phiên bản 1.6

Theo truyền thống, trong Markdown, MkDocs chỉ nhận dạng các liên kết tương đối dẫn đến một *.mdtài liệu vật lý khác (hoặc tệp phương tiện). Đây là một quy ước tốt để tuân theo vì sau đó các trang nguồn cũng có thể duyệt tự do mà không cần MkDocs, ví dụ như trên GitHub. Trong khi các liên kết tuyệt đối không được sửa đổi (khiến chúng thường không hoạt động như mong đợi) hoặc gần đây hơn là được cảnh báo. Nếu bạn không thích phải luôn sử dụng các liên kết tương đối, giờ đây bạn có thể chọn liên kết tuyệt đối và để chúng hoạt động chính xác.

Nếu bạn đặt cài đặt validation.links.absolute_linksthành giá trị mới relative_to_docs, tất cả các liên kết Markdown bắt đầu bằng /sẽ được hiểu là tương đối với docs_dirgốc. Sau đó, các liên kết sẽ được xác thực về tính chính xác theo tất cả các quy tắc khác đã hoạt động đối với các liên kết tương đối trong các phiên bản trước của MkDocs. Đối với đầu ra HTML, các liên kết này vẫn sẽ được chuyển thành tương đối để trang web vẫn hoạt động đáng tin cậy.

Vì vậy, bây giờ bất kỳ tài liệu nào (ví dụ "dir1/foo.md") đều có thể liên kết đến tài liệu "dir2/bar.md" dưới dạng [link](/dir2/bar.md), ngoài cách duy nhất đúng trước đây [link](../dir2/bar.md).

Tuy nhiên, bạn phải bật cài đặt. Mặc định vẫn là bỏ qua liên kết.

Cài đặt để nhận dạng liên kết tuyệt đối và xác thực chúng:

validation: links: absolute_links: relative_to_docs anchors: warn unrecognized_links: warn

Xây dựng thư mục

chủ đề

Thiết lập chủ đề và cấu hình chủ đề cụ thể của trang tài liệu của bạn. Có thể là chuỗi hoặc tập hợp các cặp khóa/giá trị.

Nếu là chuỗi, thì đó phải là tên chuỗi của một chủ đề đã cài đặt. Để biết danh sách các chủ đề khả dụng, hãy truy cập vào mục Chọn chủ đề của bạn .

Một tập hợp ví dụ về cặp khóa/giá trị có thể trông giống như thế này:

theme: name: mkdocs locale: en custom_dir: my_theme_customizations/ static_templates: - sitemap.html include_sidebar: false

Nếu là một tập hợp các cặp khóa/giá trị, các khóa lồng nhau sau đây có thể được xác định:

tên

Tên chuỗi của một chủ đề đã cài đặt. Để biết danh sách các chủ đề khả dụng, hãy truy cập Chọn chủ đề của bạn .

địa phương

Mã đại diện cho ngôn ngữ của trang web của bạn. Xem Bản địa hóa chủ đề của bạn để biết chi tiết.

thư mục tùy chỉnh

Một thư mục chứa chủ đề tùy chỉnh. Đây có thể là một thư mục tương đối, trong trường hợp đó nó được giải quyết tương đối với thư mục chứa tệp cấu hình của bạn hoặc nó có thể là một đường dẫn thư mục tuyệt đối từ gốc của hệ thống tệp cục bộ của bạn.

Xem mục Tùy chỉnh chủ đề để biết chi tiết nếu bạn muốn chỉnh sửa chủ đề hiện có.

Hãy xem Hướng dẫn dành cho nhà phát triển chủ đề nếu bạn muốn tự xây dựng chủ đề của riêng mình từ đầu.

mẫu_tĩnh

Danh sách các mẫu để hiển thị dưới dạng các trang tĩnh. Các mẫu phải nằm trong thư mục mẫu của chủ đề hoặc trong thư mục custom_dirđược xác định trong cấu hình chủ đề.

(từ khóa cụ thể theo chủ đề)

Bất kỳ từ khóa bổ sung nào được chủ đề hỗ trợ cũng có thể được xác định. Xem tài liệu về chủ đề bạn đang sử dụng để biết chi tiết.

mặc định :'mkdocs'

thư mục tài liệu

Thư mục chứa các tệp markdown nguồn tài liệu. Đây có thể là thư mục tương đối, trong trường hợp đó, nó được giải quyết tương đối với thư mục chứa tệp cấu hình của bạn hoặc có thể là đường dẫn thư mục tuyệt đối từ gốc hệ thống tệp cục bộ của bạn.

mặc định :'docs'

site_dir

Thư mục nơi HTML đầu ra và các tệp khác được tạo. Đây có thể là thư mục tương đối, trong trường hợp đó, nó được giải quyết tương đối với thư mục chứa tệp cấu hình của bạn hoặc có thể là đường dẫn thư mục tuyệt đối từ gốc của hệ thống tệp cục bộ của bạn.

mặc định :'site'

Ghi chú

Nếu bạn đang sử dụng kiểm soát mã nguồn, thông thường bạn sẽ muốn đảm bảo rằng các tệp đầu ra bản dựng của bạn không được cam kết vào kho lưu trữ và chỉ giữ các tệp nguồn dưới sự kiểm soát phiên bản. Ví dụ, nếu sử dụng, git bạn có thể thêm dòng sau vào .gitignoretệp của mình:

site/

Nếu bạn đang sử dụng một công cụ kiểm soát mã nguồn khác, bạn sẽ muốn kiểm tra tài liệu hướng dẫn về cách bỏ qua các thư mục cụ thể.

Thiết lập danh sách các tệp CSS (tương đối với docs_dir) sẽ được chủ đề đưa vào, thường là dưới dạng <link>thẻ.

Ví dụ:

extra_css: - css/extra.css - css/second_extra.css

mặc định : [](danh sách trống).

Thiết lập danh sách các tệp JavaScript trong docs_dirchủ đề của bạn dưới dạng <script>thẻ.

Đã thay đổi trong phiên bản 1.5:

Các phiên bản cũ hơn của MkDocs chỉ hỗ trợ một danh sách chuỗi đơn giản, nhưng hiện nay có sẵn một số khóa cấu hình bổ sung: type, async, defer.

Xem các ví dụ và kết quả chúng tạo ra:

extra_javascript: - some_plain_javascript.js # <script src="some_plain_javascript.js"></script> # New behavior in MkDocs 1.5: - implicitly_as_module.mjs # <script src="implicitly_as_module.mjs" type="module"></script> # Config keys only supported since MkDocs 1.5: - path: explicitly_as_module.mjs # <script src="explicitly_as_module.mjs" type="module"></script> type: module - path: deferred_plain.js # <script src="deferred_plain.js" defer></script> defer: true - path: scripts/async_module.mjs # <script src="scripts/async_module.mjs" type="module" async></script> type: module async: true

Vì vậy, mỗi mục có thể là:

• một chuỗi đơn giản, hoặc
• một ánh xạ có pathkhóa bắt buộc và 3 khóa tùy chọn type(chuỗi), async(boolean), defer(boolean).

Chỉ có biến thể chuỗi đơn giản mới phát hiện được .mjsphần mở rộng và thêm vào type="module", nếu không thì type: modulephải viết ra bất kể phần mở rộng.

mặc định : [](danh sách trống).

Ghi chú

*.jsvà *.csscác tập tin, giống như bất kỳ loại tập tin nào khác, luôn được sao chép từ docs_dirbản sao đã triển khai của trang web, bất kể chúng có được liên kết đến các trang thông qua cấu hình trên hay không.

Thiết lập danh sách các mẫu trong docs_dirMkDocs của bạn để xây dựng. Để biết thêm về cách viết mẫu cho MkDocs, hãy đọc tài liệu về chủ đề tùy chỉnh và đặc biệt là phần về các biến có sẵn cho mẫu. Xem ví dụ trong extra_css để biết cách sử dụng.

mặc định : [](danh sách trống).

Một tập hợp các cặp khóa-giá trị, trong đó các giá trị có thể là bất kỳ cấu trúc YAML hợp lệ nào, sẽ được chuyển đến mẫu. Điều này cho phép linh hoạt tuyệt vời khi tạo chủ đề tùy chỉnh.

Ví dụ, nếu bạn đang sử dụng một chủ đề hỗ trợ hiển thị phiên bản dự án, bạn có thể truyền nó vào chủ đề như thế này:

extra: version: 1.0

mặc định : Theo mặc định extrasẽ là ánh xạ khóa-giá trị trống.

Kiểm soát xem trước

Tải lại trực tiếp

đồng hồ

Xác định các thư mục bổ sung để theo dõi khi chạy mkdocs serve. Cấu hình là danh sách YAML.

watch: - directory_a - directory_b

Cho phép thiết lập giá trị mặc định tùy chỉnh mà không cần phải truyền giá trị đó qua tùy chọn -w/ --watch mỗi khi mkdocs servegọi lệnh.

Ghi chú

Đường dẫn được cung cấp thông qua tệp cấu hình có liên quan đến tệp cấu hình.

Các đường dẫn được cung cấp thông qua tham số -w/ --watchCLI thì không.

sử dụng_url_thư_mục

Thiết lập này kiểm soát cấu trúc thư mục của tài liệu được tạo và do đó kiểm soát định dạng URL được sử dụng để liên kết đến các trang.

Bảng sau đây minh họa sự khác biệt giữa cấu trúc thư mục và URL được sử dụng trên trang web khi thiết lập use_directory_urlsthành truehoặc false.

use_directory_urls: false

Thiết lập này là cần thiết khi tài liệu được lưu trữ trên các hệ thống không thể truy cập tệp X/index.htmlkhi được cung cấp URL X. Khi được đặt thành false, không có Xthư mục bổ sung nào được tạo và tệp chỉ được lưu trữ dưới dạng X.html. Các liên kết được tạo ra để trỏ trực tiếp đến tệp đích thay vì thư mục đích .

Tệp nguồn	Tập tin đã tạo	Định dạng URL
chỉ số.md	index.html	/index.html
hướng dẫn api.md	api-guide.html	/api-guide.html
về/giấy phép.md	về/giấy phép.html	/giới thiệu/giấy phép.html

Ví dụ, điều này cần được thiết lập falsekhi:

• mở các trang trực tiếp từ hệ thống tập tin
• xuất bản tài liệu lên trang web S3 tĩnh.

use_directory_urls: true

Phong cách mặc định use_directory_urls: truesẽ tạo ra các URL thân thiện hơn với người dùng và thường là những gì bạn muốn sử dụng.

Tệp nguồn	Tập tin đã tạo	Định dạng URL
chỉ số.md	/index.html	/
hướng dẫn api.md	/api-guide/index.html	/hướng dẫn-api/
về/giấy phép.md	/giấy phép/index.html	/giới thiệu/giấy phép

mặc định :true

nghiêm ngặt

Xác định cách xử lý cảnh báo. Đặt thành truedừng xử lý khi có cảnh báo. Đặt thành falsein cảnh báo và tiếp tục xử lý.

Tính năng này cũng có sẵn dưới dạng cờ dòng lệnh: --strict.

mặc định :false

địa chỉ dev

Xác định địa chỉ được sử dụng khi chạy mkdocs serve. Phải có định dạng IP:PORT.

Cho phép thiết lập giá trị mặc định tùy chỉnh mà không cần phải truyền giá trị đó qua --dev-addrtùy chọn mỗi khi mkdocs servelệnh được gọi.

mặc định :'127.0.0.1:8000'

Xem thêm: site_url .

Tùy chọn định dạng

phần mở rộng markdown

MkDocs sử dụng thư viện Python Markdown để dịch các tệp Markdown thành HTML. Python Markdown hỗ trợ nhiều tiện ích mở rộng tùy chỉnh cách định dạng trang. Thiết lập này cho phép bạn bật danh sách các tiện ích mở rộng ngoài các tiện ích mở rộng mà MkDocs sử dụng theo mặc định ( meta, toc, tables, và fenced_code).

Ví dụ, để kích hoạt tiện ích mở rộng kiểu chữ SmartyPants , hãy sử dụng:

markdown_extensions: - smarty

Một số tiện ích mở rộng 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 ghép ánh xạ khóa/giá trị ( option_name: option value) của bất kỳ tùy chọn nào mà tiện ích mở rộng nhất định hỗ trợ. Xem tài liệu về tiện ích mở rộng bạn đang sử dụng để xác định tùy chọn nào chúng hỗ trợ.

Ví dụ, để bật liên kết cố định trong tocphần mở rộng (đã bao gồm), hãy sử dụng:

markdown_extensions: - toc: permalink: true

Lưu ý rằng dấu hai chấm ( :) phải theo sau tên phần mở rộng ( toc) 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 định nghĩa nhiều tùy chọn cho một phần mở rộng duy nhất, mỗi tùy chọn phải được định nghĩa trên một dòng riêng biệt:

markdown_extensions: - toc: permalink: true separator: "_"

Thêm một mục bổ sung vào danh sách cho mỗi tiện ích mở rộng. Nếu bạn không có tùy chọn cấu hình nào để thiết lập cho một tiện ích mở rộng cụ thể, thì chỉ cần bỏ qua các tùy chọn cho tiện ích mở rộng đó:

markdown_extensions: - smarty - toc: permalink: true - sane_lists

Giá trị cấu hình động

Để cấu hình động các phần mở rộng, bạn có thể lấy giá trị cấu hình từ biến môi trường hoặc lấy đường dẫn đến tệp Markdown hiện đang được hiển thị hoặc toàn bộ trang MkDocs.

Trong các ví dụ trên, mỗi phần mở rộng là một mục danh sách (bắt đầu bằng a -). Thay vào đó, có thể sử dụng các cặp khóa/giá trị. Tuy nhiên, trong trường hợp đó, phải cung cấp một giá trị rỗng cho các phần mở rộng không có tùy chọn nào được xác định. Do đó, ví dụ cuối cùng ở trên cũng có thể được xác định như sau:

markdown_extensions: smarty: {} toc: permalink: true sane_lists: {}

Cú pháp thay thế này là bắt buộc nếu bạn muốn ghi đè một số tùy chọn thông qua kế thừa .

Thêm phần mở rộng

Tài liệu Python-Markdown cung cấp danh sách các tiện ích mở rộng có sẵn ngay khi cài đặt. Để biết danh sách các tùy chọn cấu hình có sẵn cho một tiện ích mở rộng nhất định, hãy xem tài liệu cho tiện ích mở rộng đó.

Bạn cũng có thể cài đặt và sử dụng nhiều tiện ích mở rộng của bên thứ ba ( wiki Python-Markdown , danh mục dự án MkDocs ). Tham khảo tài liệu do các tiện ích mở rộng đó cung cấp để biết hướng dẫn cài đặt và các tùy chọn cấu hình có sẵn.

mặc định : [](danh sách trống).

móc

Mới trong phiên bản 1.4

Danh sách các đường dẫn đến các tập lệnh Python (liên quan đến mkdocs.yml) được tải và sử dụng làm phiên bản plugin .

Ví dụ:

hooks: - my_hooks.py

Sau đó, tệp my_hooks.pycó thể chứa bất kỳ trình xử lý sự kiện plugin nào (không có self), ví dụ:

def on_page_markdown(markdown, **kwargs): return markdown.replace('a', 'z')

Ví dụ nâng cao:

Điều này tạo ra các cảnh báo dựa trên nội dung Markdown (và các cảnh báo này sẽ nghiêm trọng ở chế độ nghiêm ngặt ):

import logging, re import mkdocs.plugins log = logging.getLogger('mkdocs') @mkdocs.plugins.event_priority(-50) def on_page_markdown(markdown, page, **kwargs): path = page.file.src_uri for m in re.finditer(r'\bhttp://[^) ]+', markdown): log.warning(f"Documentation file '{path}' contains a non-HTTPS link: {m[0]}")

Điều này không mang lại bất kỳ khả năng mới nào so với plugin , nó chỉ đơn giản hóa việc sử dụng một lần vì không cần phải cài đặt như plugin.

Lưu ý rằng mkdocs servemô-đun hook sẽ không được tải lại sau mỗi lần dựng.

Bạn có thể đã thấy tính năng này trong plugin mkdocs-simple-hooks . Nếu sử dụng tên phương thức chuẩn, nó có thể được thay thế trực tiếp, ví dụ:

-plugins: - - mkdocs-simple-hooks: - hooks: - on_page_markdown: 'my_hooks:on_page_markdown' +hooks: + - my_hooks.py

Mới trong MkDocs 1.6

Nếu tệp hook có tệp foo.pyliền kề, nó có thể sử dụng cú pháp Python thông thường import foođể truy cập các hàm của tệp đó.

Trong các phiên bản cũ hơn của MkDocs, cần phải có giải pháp thay thế để thực hiện việc này - thêm đường dẫn đến sys.path.

các plugin

Danh sách các plugin (có cài đặt cấu hình tùy chọn) để sử dụng khi xây dựng trang web. Xem tài liệu Plugin để biết thông tin chi tiết.

mặc định : ['search'](plugin "tìm kiếm" có trong MkDocs).

Nếu pluginscài đặt cấu hình được xác định trong mkdocs.ymltệp cấu hình, thì mọi giá trị mặc định (chẳng hạn như search) sẽ bị bỏ qua và bạn cần phải bật lại rõ ràng các giá trị mặc định nếu bạn muốn tiếp tục sử dụng chúng:

plugins: - search - your_other_plugin

Để xác định các tùy chọn cho một plugin nhất định, hãy sử dụng một tập hợp các cặp khóa/giá trị lồng nhau:

plugins: - search - your_other_plugin: option1: value option2: other value

Để tắt hoàn toàn tất cả các plugin, bao gồm cả các plugin mặc định, hãy đặt plugins cài đặt thành danh sách trống:

plugins: []

enabledlựa chọn

Mới trong MkDocs 1.6

Mỗi plugin có các phím tùy chọn riêng. Tuy nhiên, MkDocs cũng đảm bảo rằng mỗi plugin có enabledtùy chọn boolean. Điều này có thể được sử dụng để bật có điều kiện một plugin cụ thể, như trong ví dụ sau:

plugins: - search - code-validator: enabled: !ENV [LINT, false]

Xem: Biến môi trường

Cú pháp thay thế

Trong các ví dụ trên, mỗi plugin là một mục danh sách (bắt đầu bằng a -). Thay vào đó, có thể sử dụng các cặp khóa/giá trị. Tuy nhiên, trong trường hợp đó, phải cung cấp một giá trị rỗng cho các plugin không có tùy chọn nào được xác định. Do đó, ví dụ cuối cùng ở trên cũng có thể được xác định như sau:

plugins: search: {} your_other_plugin: option1: value option2: other value

Cú pháp thay thế này là bắt buộc nếu bạn muốn ghi đè một số tùy chọn thông qua kế thừa .

Tìm kiếm

Một plugin tìm kiếm được cung cấp theo mặc định với MkDocs sử dụng lunr.js làm công cụ tìm kiếm. Các tùy chọn cấu hình sau đây có sẵn để thay đổi hành vi của plugin tìm kiếm:

bộ tách

Một biểu thức chính quy khớp với các ký tự được sử dụng làm dấu phân cách từ khi xây dựng chỉ mục. Theo mặc định, khoảng trắng và dấu gạch nối ( -) được sử dụng. Để thêm dấu chấm ( .) làm dấu phân cách từ, bạn có thể thực hiện như sau:

plugins: - search: separator: '[\s\-\.]+'

mặc định :'[\s\-]+'

min_search_length

Giá trị số nguyên xác định độ dài tối thiểu cho truy vấn tìm kiếm. Theo mặc định, các tìm kiếm có độ dài dưới 3 ký tự sẽ bị bỏ qua vì chất lượng kết quả tìm kiếm với các thuật ngữ tìm kiếm ngắn sẽ kém. Tuy nhiên, đối với một số trường hợp sử dụng (chẳng hạn như tài liệu về Hàng đợi tin nhắn có thể tạo ra các tìm kiếm cho 'MQ'), có thể nên đặt giới hạn ngắn hơn.

plugins: - search: min_search_length: 2

mặc định : 3

ngôn ngữ

Danh sách các ngôn ngữ sử dụng khi xây dựng chỉ mục tìm kiếm được xác định theo mã ngôn ngữ ISO 639-1 của chúng . Với Lunr Languages , các ngôn ngữ sau được hỗ trợ:

• ar: Tiếng Ả Rập
• da: Tiếng Đan Mạch
• nl: Hà Lan
• en: Tiếng Anh
• fi: Phần Lan
• fr: Tiếng Pháp
• de: Tiếng Đức
• hu: Tiếng Hungary
• it: Tiếng Ý
• ja: Tiếng Nhật
• no: Tiếng Na Uy
• pt: Tiếng Bồ Đào Nha
• ro: Tiếng Rumani
• ru: Tiếng Nga
• es: Tiếng Tây Ban Nha
• sv: Thụy Điển
• th: Thái Lan
• tr: Thổ Nhĩ Kỳ
• vi: Tiếng Việt

Bạn có thể đóng góp thêm ngôn ngữ khác .

Cảnh báo

Mặc dù tìm kiếm hỗ trợ sử dụng nhiều ngôn ngữ cùng nhau, tốt nhất là không nên thêm ngôn ngữ khác trừ khi bạn thực sự cần chúng. Mỗi ngôn ngữ bổ sung sẽ làm tăng đáng kể yêu cầu về băng thông và sử dụng nhiều tài nguyên trình duyệt hơn. Nhìn chung, tốt nhất là giữ mỗi phiên bản MkDocs ở một ngôn ngữ duy nhất.

Ghi chú

Lunr Languages hiện không hỗ trợ tiếng Trung hoặc các ngôn ngữ châu Á khác. Tuy nhiên, một số người dùng đã báo cáo kết quả khá tốt khi sử dụng tiếng Nhật.

mặc định : Giá trị theme.localenếu được đặt, nếu không thì [en].

prebuild_index

Tùy chọn tạo chỉ mục dựng sẵn của tất cả các trang, cung cấp một số cải tiến về hiệu suất cho các trang web lớn hơn. Trước khi bật, hãy xác nhận rằng chủ đề bạn đang sử dụng hỗ trợ rõ ràng việc sử dụng chỉ mục dựng sẵn (chủ đề dựng sẵn có hỗ trợ). Đặt thành truebật.

Cảnh báo

Tùy chọn này yêu cầu Node.js phải được cài đặt và lệnh nodephải nằm trên đường dẫn hệ thống. Nếu lệnh gọi đến nodekhông thành công vì bất kỳ lý do nào, cảnh báo sẽ được đưa ra và quá trình xây dựng tiếp tục mà không bị gián đoạn. Bạn có thể sử dụng --strict cờ khi xây dựng để gây ra lỗi như vậy thay vào đó.

Ghi chú

Trên các trang web nhỏ hơn, không nên sử dụng chỉ mục được xây dựng sẵn vì nó làm tăng đáng kể yêu cầu về băng thông mà không cải thiện đáng kể hoặc không cải thiện đáng kể cho người dùng của bạn. Tuy nhiên, đối với các trang web lớn hơn (hàng trăm trang), mức tăng băng thông tương đối nhỏ và người dùng của bạn sẽ nhận thấy sự cải thiện đáng kể về hiệu suất tìm kiếm.

mặc định :False

lập chỉ mục

Cấu hình chiến lược mà trình lập chỉ mục tìm kiếm sẽ sử dụng khi xây dựng chỉ mục cho các trang của bạn. Thuộc tính này đặc biệt hữu ích nếu dự án của bạn có quy mô lớn và chỉ mục chiếm một lượng lớn dung lượng đĩa.

plugins: - search: indexing: 'full'

Tùy chọn

Lựa chọn	Sự miêu tả
full	Lập chỉ mục tiêu đề, phần tiêu đề và toàn văn của mỗi trang.
sections	Lập chỉ mục tiêu đề và phần tiêu đề của mỗi trang.
titles	Chỉ lập chỉ mục tiêu đề của mỗi trang.

mặc định :full

Biến môi trường

Trong hầu hết các trường hợp, giá trị của tùy chọn cấu hình được đặt trực tiếp trong tệp cấu hình. Tuy nhiên, như một tùy chọn, giá trị của tùy chọn cấu hình có thể được đặt thành giá trị của biến môi trường bằng cách sử dụng !ENVthẻ. Ví dụ, để đặt giá trị của site_nametùy chọn thành giá trị của biến, SITE_NAMEtệp YAML có thể chứa nội dung sau:

site_name: !ENV SITE_NAME

Nếu biến môi trường không được định nghĩa, thì thiết lập cấu hình sẽ được gán một giá trị null(hoặc Nonetrong Python). Giá trị mặc định có thể được định nghĩa là giá trị cuối cùng trong danh sách. Giống như thế này:

site_name: !ENV [SITE_NAME, 'My default site name']

Nhiều biến dự phòng cũng có thể được sử dụng. Lưu ý rằng giá trị cuối cùng không phải là biến môi trường, nhưng phải là giá trị để sử dụng làm mặc định nếu không có biến môi trường nào được chỉ định được xác định.

site_name: !ENV [SITE_NAME, OTHER_NAME, 'My default site name']

Các kiểu đơn giản được định nghĩa trong một biến môi trường như string, bool, integer, float, datestamp và null được phân tích cú pháp như thể chúng được định nghĩa trực tiếp trong tệp YAML, nghĩa là giá trị sẽ được chuyển đổi thành kiểu thích hợp. Tuy nhiên, các kiểu phức tạp như danh sách và cặp khóa/giá trị không thể được định nghĩa trong một biến môi trường duy nhất.

Để biết thêm chi tiết, hãy xem dự án pyyaml_env_tag .

Đường dẫn liên quan đến tệp hoặc trang web hiện tại

Mới trong phiên bản 1.5

Một số tiện ích mở rộng Markdown có thể được hưởng lợi từ việc biết đường dẫn của tệp Markdown hiện đang được xử lý hoặc chỉ đường dẫn gốc của trang web hiện tại. Đối với điều đó, thẻ đặc biệt !relativecó thể được sử dụng trong hầu hết các ngữ cảnh trong tệp cấu hình, mặc dù các trường hợp sử dụng duy nhất được biết đến là trong markdown_extensions.

Ví dụ về các giá trị có thể là:

- !relative # Relative to the directory of the current Markdown file - !relative $docs_dir # Path of the docs_dir - !relative $config_dir # Path of the directory that contains the main mkdocs.yml - !relative $config_dir/some/child/dir # Some subdirectory of the root config directory

(Đây $docs_dirvà $config_dirhiện là những tiền tố đặc biệt duy nhất được công nhận.)

Ví dụ:

markdown_extensions: - pymdownx.snippets: base_path: !relative # Relative to the current Markdown file

Điều này cho phép tiện ích mở rộng pymdownx.snippets bao gồm các tệp liên quan đến tệp Markdown hiện tại, mà nếu không có thẻ này, tiện ích mở rộng này sẽ không thể biết được.

Ghi chú

Ngay cả đối với trường hợp mặc định, đường dẫn cơ sở của bất kỳ tiện ích mở rộng nào về mặt kỹ thuật là thư mục làm việc hiện tại mặc dù giả định là đó là thư mục của mkdocs.yml . Vì vậy, ngay cả khi bạn không muốn các đường dẫn là tương đối, để cải thiện hành vi mặc định, hãy luôn ưu tiên sử dụng thành ngữ này:

markdown_extensions: - pymdownx.snippets: base_path: !relative $config_dir # Relative to the root directory with mkdocs.yml

Kế thừa cấu hình

Nhìn chung, một tệp duy nhất sẽ lưu giữ toàn bộ cấu hình cho một trang web. Tuy nhiên, một số tổ chức có thể duy trì nhiều trang web mà tất cả đều chia sẻ một cấu hình chung trên khắp các trang web đó. Thay vì duy trì các cấu hình riêng biệt cho từng trang web, các tùy chọn cấu hình chung có thể được xác định trong một tệp cấu hình cha mà tệp cấu hình chính của mỗi trang web kế thừa.

Để xác định tệp cha cho tệp cấu hình, hãy đặt INHERITphím (toàn chữ in hoa) thành đường dẫn của tệp cha. Đường dẫn phải liên quan đến vị trí của tệp chính.

Để các tùy chọn cấu hình được hợp nhất với cấu hình cha, các tùy chọn đó phải được định nghĩa là cặp khóa/giá trị. Cụ thể, các tùy chọn markdown_extensions và plugins phải sử dụng cú pháp thay thế không sử dụng các mục danh sách (các dòng bắt đầu bằng -).

Ví dụ, giả sử cấu hình chung (cha) được định nghĩa trong base.yml:

theme: name: mkdocs locale: en highlightjs: true markdown_extensions: toc: permalink: true admonition: {}

Sau đó, đối với trang web "foo", tệp cấu hình chính sẽ được xác định tại foo/mkdocs.yml:

INHERIT: ../base.yml site_name: Foo Project site_url: https://example.com/foo

Khi chạy mkdocs build, tệp at foo/mkdocs.ymlsẽ được truyền vào dưới dạng tệp cấu hình. Sau đó, MkDocs sẽ phân tích tệp đó, truy xuất và phân tích tệp gốc base.ymlvà hợp nhất sâu hai tệp. Điều này sẽ dẫn đến việc MkDocs nhận được cấu hình đã hợp nhất sau:

site_name: Foo Project site_url: https://example.com/foo theme: name: mkdocs locale: en highlightjs: true markdown_extensions: toc: permalink: true admonition: {}

Hợp nhất sâu cho phép bạn thêm và/hoặc ghi đè nhiều giá trị khác nhau trong tệp cấu hình chính của bạn. Ví dụ, giả sử đối với một trang web, bạn muốn thêm hỗ trợ cho danh sách định nghĩa, sử dụng một ký hiệu khác cho liên kết cố định và xác định một dấu phân cách khác. Trong tệp cấu hình chính của trang web đó, bạn có thể thực hiện:

INHERIT: ../base.yml site_name: Bar Project site_url: https://example.com/bar markdown_extensions: def_list: {} toc: permalink:  separator: "_"

Trong trường hợp đó, cấu hình trên sẽ được hợp nhất sâu base.ymlvà tạo ra cấu hình sau:

site_name: Bar Project site_url: https://example.com/bar theme: name: mkdocs locale: en highlightjs: true markdown_extensions: def_list: {} toc: permalink:  separator: "_" admonition: {}

Lưu ý rằng admonitionphần mở rộng được giữ nguyên từ cấu hình gốc, def_listphần mở rộng đã được thêm vào, giá trị của toc.permalinkđã được thay thế và giá trị của toc.separatorđã được thêm vào.

Bạn có thể thay thế hoặc hợp nhất giá trị của bất kỳ khóa nào. Tuy nhiên, bất kỳ khóa nào không phải khóa luôn được thay thế. Do đó, bạn không thể thêm các mục vào danh sách. Bạn phải xác định lại toàn bộ danh sách.

Vì cấu hình nav được tạo thành từ các danh sách lồng nhau, điều này có nghĩa là bạn không thể hợp nhất các mục điều hướng. Tất nhiên, bạn có thể thay thế toàn bộ nav cấu hình bằng một cấu hình mới. Tuy nhiên, nhìn chung, toàn bộ điều hướng sẽ được xác định trong tệp cấu hình chính cho một dự án.

Cảnh báo

Xin nhắc lại, tất cả các tùy chọn cấu hình dựa trên đường dẫn phải liên quan đến tệp cấu hình chính và MkDocs không thay đổi các đường dẫn khi hợp nhất. Do đó, việc xác định các đường dẫn trong tệp cha được nhiều trang web khác nhau kế thừa có thể không hoạt động như mong đợi. Nói chung, tốt nhất là chỉ xác định các tùy chọn dựa trên đường dẫn trong tệp cấu hình chính.

Kế thừa cũng có thể được sử dụng như một cách nhanh chóng để ghi đè các khóa trên dòng lệnh - bằng cách sử dụng stdin làm tệp cấu hình. Ví dụ:

echo '{INHERIT: mkdocs.yml, site_name: "Renamed site"}' | mkdocs build -f -