組態

所有可用組態設定指南。

簡介

預設專案設定使用名為 mkdocs.yml 的 YML 組態檔在專案目錄中設定。你可以使用 -f/--config-file 選項指定其他路徑（請參閱 mkdocs build --help）。

此組態檔至少必須包含 site_name。所有其他設定都是選用的。

專案資訊

site_name

這是 必填設定，應該字串用作專案文件的標題。例如

site_name: Marshmallow Generator

呈現主題時，此設定會作為 site_name 內容變數傳遞。

site_url

設定網站的標準網址。這會將 link 標籤加上 canonical 網址新增到每個 HTML 頁面的 head 區段。如果 MkDocs 網站的『根目錄』在網域的子目錄內，請務必在設定中包含該子目錄（https://example.com/foo/）。

此設定也會用於 mkdocs serve：伺服器會安裝到從網址路徑組成部分取出的路徑上，例如 some/page.md 會從 http://127.0.0.1:8000/foo/some/page/ 呈現，以模仿預期的遠端配置。

預設：null

repo_url

設定後，可以在每個頁面上提供連結到儲存庫（GitHub、Bitbucket、GitLab、...）。

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

預設：null

repo_name

設定後，可以在每個頁面上提供連結到儲存庫的名稱。

預設：若 repo_url 與這些網域相符，則為 'GitHub'、'Bitbucket' 或 'GitLab'，否則為 repo_url 的主機名稱。

edit_uri

直接檢視網頁時，從基礎 repo_url 到文件目錄的路徑，包含儲存庫主機（例如 GitHub、Bitbucket 等）、分支和文件目錄本身等特定資訊。MkDocs 會連結 repo_url 和 edit_uri，並附加頁面的輸入路徑。

如果已設定且主題支援此設定，會提供一個連到原始碼儲存庫中的頁面連結。這有助於查找和編輯頁面的原始碼。如果未設定 repo_url，則此選項將會被忽略。在某些主題中，設定此選項可能會使用編輯連結來取代儲存庫連結。其他主題可能會顯示兩個連結。

edit_uri 支援查詢字元（「?」）和片段字元（「#」）。對於使用查詢字元或片段字元存取檔案的儲存庫主機，可以如下設定 edit_uri。（請注意 URI 中的 ? 和 #...）

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

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

對於其他儲存庫主機，只需指定相對於文件目錄的相對路徑即可。

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

例如，有此組態時

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

表示命名為「foo/bar.md」的頁面，其編輯連結會導向
https://example.com/project/repo/blob/main/docs/foo/bar.md

edit_uri 實際上可以只是一個絕對 URL，而不必相對於 repo_url，因此這也可以達到相同的結果

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

如需更多彈性，請參閱以下 edit_uri_template。

預設值：如果是 GitHub 和 GitLab 儲存庫，為 edit/master/docs/；如果是 Bitbucket 儲存庫，為 src/default/docs/，如果 repo_url 與這些網域相符；否則為 null

edit_uri_template

edit_uri 的更彈性變形。

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

這兩個是等效的

（它們也互斥 -- 不必同時指定）。

從這裡開始，您可以變更路徑的定位或格式，如果預設的附加路徑行為不夠用的話。

• edit_uri_template 的內容是正常的 Python 格式字串，只提供下列欄位
• {path}，例如 foo/bar.md

{path_noext}，例如 foo/bar

• ，且轉換標誌 !q 可用於對欄位進行百分比編碼

預設：null

（例如 https://gitlab.com/-/ide/project/repo/edit/master/-/docs/foo/bar.md）

site_description

預設：null

site_author

設定作者名稱。這將在產生的 HTML 標題中新增一個 meta 標籤。

預設：null

copyright

設定版權資訊，以便主題納入說明文件中。

預設：null

remote_branch

設定遠端分支，當使用 gh-deploy 部署到 GitHub Pages 時提交至遠端分支。可以在 gh-deploy 中以命令列選項覆寫此選項。

預設：gh-pages

remote_name

設定遠端名稱，當使用 gh-deploy 部署到 GitHub Pages 時推送到遠端名稱。可以在 gh-deploy 中以命令列選項覆寫此選項。

預設：origin

說明文件配置

nav

此設定用來決定網站整體導覽的格式和配置。一個極簡化的導覽定義如下

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

導覽設定中的所有路徑必須是相對於 docs_dir 設定選項。請參閱 設定頁面和導覽 的部分，以取得更詳細的分析，包括如何建立子區段。

導覽項目也可以包含外部網站的連結。對於內部連結，標題是選用的，但對於外部連結則是必要的。外部連結可以是完整的 URL 或相對應的 URL。未在檔案中找到的路徑，一律假設為外部連結。請參閱 Meta-Data 的部分，了解 MkDocs 如何決定文件的頁面標題。

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

在上方的範例中，前兩個項目指向本機檔案，而第三個項目指向外部網站。

然而，有時候 MkDocs 網站會寄存在專案網站的子目錄中，而你可能想連結到同一網站的其它部分，又不想要包含完整的網域。在這種情況下，你可以使用適當的相對應 URL。

site_url: https://example.com/foo/

nav:
  - Home: '../'
  - 'User Guide': 'user-guide.md'
  - 'Bug Tracker': '/bugs/'

在上方的範例中，使用了兩種不同樣式的外部連結。首先，請注意 site_url 指出 MkDocs 網站寄存在網域的 /foo/ 子目錄中。因此，首頁 導覽項目是一個相對連結，向上移動一層到伺服器根目錄，實際上指向 https://example.com/。錯誤追蹤 項目使用從伺服器根目錄計算的絕對路徑，實際上指向 https://example.com/bugs/。當然，使用者指南 指向本機 MkDocs 頁面。

預設：預設 nav 會包含一個按字母和數字排序的巢狀清單，其中包含在 docs_dir 及其子目錄中找到的所有 Markdown 檔案。索引檔將總是被列在子區段的最前面。

exclude_docs

此設定定義不要納入建構網站中的檔案樣式（在 docs_dir 下）。

範例

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.

這遵循 .gitignore 樣式格式。

下列預設值會自動加設，以排除點文件（與目錄）以及頂層的 樣板 目錄

exclude_docs: |
  .*
  /templates/

因此，若要真正全新開始設定，您需要先指定這些項目的否定版本。

否則，您可以選擇僅將某些點文件加入 site

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

draft_docs

此設定定義應視為草稿的文件模式（在 docs_dir 中）。草稿文件可在 mkdocs serve 期間使用，並會標示為「DRAFT」，但不會包含在組建中。若要避免此結果，並讓「serve」與「build」的行為相同，您可以執行 mkdocs serve --clean。

範例

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

這遵循 .gitignore 樣式格式。

not_in_nav

若要將一些文件加入 site，卻有意將它們排除在瀏覽之外，MkDocs 通常會對此發出警告。

將此類文件的模式（相對於 docs_dir）加入 not_in_nav 設定中，便能避免此類警告。

範例

nav:
  - Foo: foo.md
  - Bar: bar.md

not_in_nav: |
  /private.md

與前一個選項相同，這遵循 .gitignore 模式格式。

validation

設定在驗證文件連結時，MkDocs 診斷訊息的嚴格度。

這是設定樹，而且在每個設定中，其值可以為下列三個值之一：warn、info、ignore。這會導致產生相應嚴重性的記錄訊息。當然，warn 等級用於搭配 mkdocs build --strict（在其中會變成錯誤）使用，您可以在持續測試中使用它。

validation.links.absolute_links 設定額外有特殊值 relative_to_docs，用於 驗證絕對連結。

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

某些行為的預設值已經不同於 MkDocs 1.4 及以下版本 - 它們在以前會被忽略。

validation:
  absolute_links: ignore
  unrecognized_links: ignore
  anchors: ignore

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

請注意在上述範例中，我們省略了 'nav' 和 'links' 鍵。在此 absolute_links: 表示同時設定 nav: absolute_links: 和 links: absolute_links:。

值和記錄訊息範例的完整清單（這些訊息可能是隱藏或突顯）

• validation.nav.omitted_files

  • 文件中存在下列頁面，但未包含在「nav」設定中：...

• validation.nav.not_found

  • 「nav」設定中包含對 'foo/bar.md' 的參照，但在文件檔案中找不到它。

  • 「nav」設定中包含對 'foo/bar.md' 的參照，但此檔案已排除在組建 site 之外。

• validation.nav.absolute_links

  • 「nav」設定中包含對 '/foo/bar.html' 的絕對路徑，這應指向外部資源。

• validation.links.not_found

  • Doc 檔案 'example.md' 包含連結 'foo/bar.md'，但在文件檔案中找不到目標。

  • Doc 檔案 'example.md' 包含連結 'foo/bar.md'，已排除在組建 site 之外。

• validation.links.anchors

  • 文件檔「example.md」包含連結「../foo/bar.md#some-heading」，但文件檔「foo/bar.md」不包含錨點「#some-heading」

  • 文件檔「example.md」包含連結「#some-heading」，但此頁面並未有此錨點

• validation.links.absolute_links

  • 文件檔「example.md」包含絕對連結「/foo/bar.html」，已保留不變。您是否意指「foo/bar.md」?

• validation.links.unrecognized_links

  • 文件檔「example.md」包含無法辨識的相對連結「../foo/bar/」，已保留不變。您是否意指「foo/bar.md」?

  • 文件檔「example.md」包含無法辨識的相對連結「mail@example.com」，已保留不變。您是否意指「mailto:mail@example.com」?

驗證絕對連結

根據過往在 Markdown 內，MkDocs 僅辨識引導至其他實體 *.md 文件（或媒體檔案）的相對連結。這是很好的範例，因為原始頁面在沒有 MkDocs 的情況下，例如在 GitHub 上，也可自由瀏覽。而絕對連結則保留不修改（導致經常無法如預期般運作）或最近則建議避免使用。如果您不喜歡總是必須使用相對連結，您現在可以選擇使用絕對連結，並讓它們正確運作。

如果您將設定值 validation.links.absolute_links 設定為新的值 relative_to_docs，那麼所有從 / 開頭的 Markdown 連結將被視為相對 docs_dir 根目錄。連結接著會依據先前 MkDocs 版本中對相對連結有效的其他所有規則進行正確性驗證。針對 HTML 輸出，這些連結仍會轉成相對連結，好讓網站繼續可靠地運作。

因此，現在任何文件（例如「dir1/foo.md」）都可以連結到文件「dir2/bar.md」，包括舊有的正確方式 [連結](../dir2/bar.md)，以及新的方式 [連結](/dir2/bar.md)。

不過，您必須啟用此設定。預設仍是略過連結。

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

建立目錄

主題

設定您的文件網站的主題和主題特定組態。可能為字串或一組金鑰/值對。

如果是字串，則它必須是要安裝的主題字串名稱。有關可用主題清單，請瀏覽 選擇您的主題。

金鑰/值對範例組如下所示

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

如果是一組金鑰/值對，可以定義下列巢狀金鑰

預設值：'mkdocs'

docs_dir

包含 Markdown 文件文件檔的目錄。這可以是相對目錄，如果是這樣，它將解析為包含設定檔目錄的相對路徑，或者是從本地檔案系統根目錄的絕對目錄路徑。

預設值：'docs'

site_dir

建立輸出 HTML 及其他檔案的目錄。這可以是相對目錄，如果是這樣，它將解析為包含設定檔目錄的相對路徑，或者是從本地檔案系統根目錄的絕對目錄路徑。

預設值：'site'

site/

extra_css

設定一組 CSS 檔案清單（相對於 docs_dir），由佈景主題包含，通常為 <link> 標籤。

範例

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

預設值：[]（一個空清單）。

extra_javascript

在您的 docs_dir 中設定一組 JavaScript 檔案清單，由佈景主題包含，作為 <script> 標籤。

請見範例及其產出

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

所以，每個項目可以是

• 一個單純字串，或
• 一個具有必要的 path 鍵和 3 個選用鍵 type (字串)、async (布林值)、defer (布林值) 的對應。

只有單純字串變數會偵測 .mjs 副檔名並新增 type="module"，否則無論副檔名為何都必須寫出 type: module。

預設值：[]（一個空清單）。

extra_templates

在您的 docs_dir 中設定一組範本清單，由 MkDocs 建置。要進一步了解撰寫 MkDocs 範本，請閱讀有關 自訂佈景主題 的說明文件，特別是可用範本變數的部分。請見 extra_css 中的範例以了解如何使用。

預設值：[]（一個空清單）。

extra

一組鍵值對，其中的值可以是任何有效的 YAML 建構，將會傳遞到範本。這在建立自訂佈景主題時提供了極大的彈性。

例如，如果您使用的佈景主題支援顯示專案版本，您可以像這樣傳遞給佈景主題

extra:
  version: 1.0

預設值：預設 extra 將是一個空的鍵值對映。

預覽控制

即時載入

監視

決定在執行 `mkdocs serve` 時要監視的額外目錄。設定為 YAML 清單。

watch:
  - directory_a
  - directory_b

允許設定自訂預設值，而無需每次呼叫 `mkdocs serve` 命令時，都透過 `-w` / `--watch` 選項傳遞。

use_directory_urls

此設定控制產生文件目錄結構，因此也控制連結至頁面的 URL 格式。

下表說明當將 `use_directory_urls` 設定為 `true` 或 `false` 時，站台使用的目錄結構和 URL 上的差異。

use_directory_urls: false

當無法在提供 URL `X` 時，存取檔案 `X/index.html` 的系統上 hosting 文件時，就需要此設定。設定為 `false` 時，不會建立額外的 `X` 目錄，且檔案會儲存為 `X.html`。建立的連結是指向目標**檔案**而非目標**目錄**。

例如，在以下情況時，需要設定為 `false`

• 直接從檔案系統開啟頁面
• 將文件發佈到靜態 S3 網站。

use_directory_urls: true

類型 `use_directory_urls: true` 的預設樣式，會建立較使用者友善的 URL，通常會是您想要使用的類型。

預設值：true

strict

決定警告處理方式。設定為 `true` 可在出現警告時，暫停處理。設定為 `false` 可印出警告並繼續處理。

也可透過命令列參數設定：--strict。

預設值：false

dev_addr

決定使用 `mkdocs serve` 時，所使用的位址。必須為 `IP:PORT` 格式。

允許設定自訂預設值，而無需每次呼叫 `mkdocs serve` 命令時，都透過 `--dev-addr` 選項傳遞。

預設值：'127.0.0.1:8000'

另請參閱：site_url。

格式設定選項

markdown_extensions

MkDocs 使用 Python Markdown 函式庫，將 Markdown 檔案轉換為 HTML。Python Markdown 支援多種 擴充套件，可自訂網頁格式。如此設定可讓您啟用 MkDocs 預設使用的擴充套件 (meta、toc、tables，以及 fenced_code) 以外的擴充套件清單。

例如，若要啟用 SmartyPants 排版擴充套件，請使用

markdown_extensions:
  - smarty

有些擴充套件提供它們自己的設定選項。如果您想設定任何設定選項，則可以彙集已給定擴充套件支援的任何選項，且設定為鍵 / 值對應 (設定名稱：設定值)。請參閱您所使用的擴充套件文件，以確定它支援哪些選項。

例如，若要在 (已包含的) `toc` 擴充套件中啟用永久連結，請使用

markdown_extensions:
  - toc:
      permalink: true

需注意，在副檔名 (toc) 後必須加上冒號 (:)，然後在換行後，選項名稱和值必須縮排並用冒號隔開。如果您想要針對單一副檔名定義多個選項，則每個選項都必須在不同的行中定義

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

針對每個副檔名在清單中新增一項。如果您沒有針對特定副檔名設定任何組態選項，則只需略過該副檔名的選項即可

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

在上述範例中，每個副檔名都是清單項目 (以 - 開頭)。您也可以使用 key/value 成對的方式。但是，在這種情況下，必須為未定義選項的副檔名提供一個空白值。因此，上面最後的範例也可以定義為如下

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

如果您打算透過 繼承 覆寫某些選項，則需要這種替代語法。

預設值：[]（一個空清單）。

hooks

載入並用作 外掛 執行個體的 Python 腳本 (相對於 mkdocs.yml) 路徑清單。

例如

hooks:
  - my_hooks.py

然後檔案 my_hooks.py 可以包含任何 外掛事件處理常式 (沒有 self)，例如

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

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]}")

這並不會與 外掛 相比而啟用任何新能力，它只簡化了一次性使用，因為這些使用不需要像外掛那樣「安裝」。

請注意，對於 mkdocs serve，鉤子模組在每次建置時不會重新載入。

您可能在 mkdocs-simple-hooks 外掛 中看過這個功能。如果使用標準方法名稱，則可以直接替換，例如

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

plugins

在建置網站時使用的外掛清單 (包含選用的組態設定)。請參閱 外掛 文件取得完整的詳細資料。

預設值：['search'] (MkDocs 中包含的「搜尋」外掛)。

如果 mkdocs.yml 組態檔案中定義了 plugins 組態設定，則任何預設值 (例如 search) 都會被忽略，而且您需要明確重新啟用預設值，才能繼續使用它們

plugins:
  - search
  - your_other_plugin

若要針對給定的外掛定義選項，請使用巢狀的 key/value 成對

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

若要完全停用所有外掛，包括任何預設值，請將 plugins 設定設為空清單

plugins: []

enabled 選項

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

另類語法

在以上的範例中，每個外掛都是清單項目（從 - 開始）。做為另一種選擇，可以改用 key-value par。然而，在這種情況下對沒有定義選項的外掛必須提供空白值。因此，以上最後一個範例也可以定義如下

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

如果您打算透過 繼承 覆寫某些選項，則需要這種替代語法。

搜尋

搜尋外掛是 MkDocs 預設提供的，它是用 lunr.js 做為搜尋引擎。下列 config 選項可以用來改變搜尋外掛的行為

separator

一個正則表達式用來比對在建立索引時作為字詞分隔字元的字元。預設是用空白鍵和連字號 (-)。如果你想把點 (.) 加入作為字詞分隔字元，你可以這麼做

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

預設：'[\s\-]+'

min_search_length

一個整數值用來定義搜尋查詢的最小長度。預設會忽略小於 3 個字元的搜尋，因為用短搜尋字詞所得的搜尋結果品質較差。然而，對於某些使用情況（例如關於訊息佇列的文件，可能產生『MQ』的搜尋），設定一個較短的限制可能是比較好的。

plugins:
  - search:
      min_search_length: 2

預設: 3

lang

當使用 ISO 639-1 語言代碼來建立搜尋索引時，要使用的語言清單。在 Lunr Languages 裡，支援下列這些語言

• ar：阿拉伯語
• da：丹麥語
• nl：荷蘭語
• en：英語
• fi：芬蘭語
• fr：法語
• de：德語
• hu：匈牙利語
• it：義大利語
• ja：日語
• no：挪威語
• pt：葡萄牙語
• ro：羅馬尼亞語
• ru：俄語
• es：西班牙語
• sv：瑞典語
• th：泰語
• tr：土耳其語
• vi：越南語

你可以 提供其他語言。

預設：已設定的話是 theme.locale 的值，否則是 [en]。

prebuild_index

選擇性地針對所有網頁產生一個預先建置索引，這可以大幅提升較大型網站的效能。在啟用之前，請確認你所使用的佈景主題明確支援使用預先建置索引（內建佈景主題都支援）。設定為 true 以啟用。

預設：False

索引建立

設定搜尋索引建造者在為您的頁面建立索引時，將會使用哪些策略。此屬性在您的專案規模龐大、索引會佔用大量磁碟空間時，特別有用。

plugins:
  - search:
      indexing: 'full'

選項

預設：full

特殊 YAML 標記

環境變數

在大部分情況下，設定選項的值時會直接在設定檔裡設定。不過，您也可以使用 !ENV 標記，將設定選項的值設定為環境變數的值。例如，如果要將 site_name 選項的值設定為變數 SITE_NAME 的值，YAML 檔可以包含以下內容

site_name: !ENV SITE_NAME

如果環境變數沒有定義，設定值將會被指定為 null（或 Python 中的 None）值。預設值可以定義為清單中的最後一個值。如下所示

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

也可以使用多個備援變數。請注意，最後一個值並非環境變數，而是如果指定的環境變數都沒有定義時，可以作為預設值使用的一個值。

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

在環境變數中定義的單純類型，例如字串、布林、整數、浮點數、日期戳記和 null，會被解析為直接在 YAML 檔中定義的這些類型，也就是說，值會被轉換為適當的類型。不過，複雜的類型，例如清單和鍵值配對，則無法在單一環境變數中定義。

更多詳細資料，請見 pyyaml_env_tag 專案。

相對於目前檔案或網站的途徑

某些 Markdown 延伸模組會希望知道目前正在處理的 Markdown 檔案的途徑，或當前網站的根目錄路徑，才能正常作用。因此，可以使用特殊標記 !relative 出現在設定檔中的大多數內容中，儘管唯一的已知使用案例是在 markdown_extensions 中。

可能值的範例為

- !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

（在此，$docs_dir 和 $config_dir 目前是目前唯一會被辨識出的特殊前置字元。）

範例

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

這允許 pymdownx.snippets 延伸模組包含相對於目前 Markdown 檔案的檔案，而如果不使用這個標籤，它就無法知道。

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

組態繼承

一般而言，單一檔案將保留網站的完整組態。然而，某些組織可能會維護多個網站，它們全部共用共通的組態。與其為每個網站維護個別的組態，可將共通的組態選項定義在父組態檔案中，每個網站的主要組態檔案繼承它。

如需定義組態的父檔案，將 INHERIT (全大寫) 鍵設定為父檔案路徑。路徑必須相對於主要檔案的位置。

如需將組態選項與父組態合併，必須將這些選項定義為鍵/值對。明確地來說，markdown_extensions 和 plugins 選項必須使用不使用清單項目（以 - 開頭的行）的替代語法。

例如，假設共通（父）組態在 base.yml 處定義

theme:
  name: mkdocs
  locale: en
  highlightjs: true

markdown_extensions:
  toc:
    permalink: true
  admonition: {}

那麼，對 "foo" 網站，主要組態檔案將在 foo/mkdocs.yml 處定義

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

當執行 mkdocs build 時，會將 foo/mkdocs.yml 處的檔案傳遞作為組態檔案。接著，MkDocs 將剖析該檔案，擷取和剖析父檔案 base.yml 並將兩者深入合併。這樣，將導致 MkDocs 接收下列已合併的組態

site_name: Foo Project
site_url: https://example.com/foo

theme:
  name: mkdocs
  locale: en
  highlightjs: true

markdown_extensions:
  toc:
    permalink: true
  admonition: {}

深入合併讓您能於您的主要組態檔案中新增和/或覆寫各種值。例如，假設您希望對一個網站新增定義清單支援、對永久連結使用不同的符號並定義不同的分隔符號。您可在該網站的主要組態檔案中執行

INHERIT: ../base.yml
site_name: Bar Project
site_url: https://example.com/bar

markdown_extensions:
  def_list: {}
  toc:
    permalink: 
    separator: "_"

在這種情況下，以上組態將與 base.yml 深入合併並產生以下組態

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: {}

請注意，admonition 擴充套件從父組態保留下來，新增了 def_list 擴充套件，取代了 toc.permalink 的值，且新增了 toc.separator 的值。

您可以取代或合併任何鍵的值。然而，任何非鍵始終會被取代。因此，您無法將項目附加至清單中。您必須重新定義整個清單。

由於 nav 組態由巢狀清單構成，這表示您無法合併導覽項目。當然，您可以使用新的組態取代整個 nav 組態。然而，通常預期整個導覽會定義在專案的主要組態檔案中。

繼承還可以當作一種於命令提示列中快速覆寫鍵的方法 - 使用 stdin 作為組態檔案。例如

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