版本說明

升級

要將 MkDocs 升級到最新版本，請使用 pip

pip install -U mkdocs

您可以使用 mkdocs --version 來判斷您目前安裝的版本

$ mkdocs --version
mkdocs, version 1.5.0 from /path/to/mkdocs (Python 3.10)

維護團隊

MkDocs 團隊的現任和過去成員。

• @tomchristie
• @d0ugal
• @waylan
• @oprypin
• @ultrabug

版本 1.6.1 (2024-08-30)

已修復

• 修復當環境變數 SOURCE_DATE_EPOCH=0 設定時發生的建置錯誤。#3795
• 修復當 mkdocs_theme.yml 設定為空時發生的建置錯誤。#3700
• 支援 python -W 和 PYTHONWARNINGS，而不是覆蓋設定。#3809
• 透過移除 0.0.0.0 開發伺服器警告，支援在嚴格模式下使用 Docker 執行。#3784
• 從 sitemap.xml 中移除不必要的 changefreq。#3629
• 修復關閉選單下拉式選單時發生的 JavaScript 主控台錯誤。#3774
• 修復重複點擊時發生的 JavaScript 主控台錯誤。#3730
• 修復在下拉式選單選擇時可能會發生的 JavaScript 主控台錯誤。#3694

已新增

• 新增荷蘭語翻譯。#3804
• 新增和更新簡體中文的翻譯。#3684

版本 1.6.0 (2024-04-20)

本地預覽

• 當開啟超過 5 個分頁時，mkdocs serve 不再鎖定瀏覽器。這是透過在分頁變成非活動狀態時關閉輪詢連線來實現的。背景分頁也不會再自動重新載入 - 這會在分頁再次開啟時發生。背景：#3391

• 新增標記 serve --open 以在瀏覽器中開啟網站。
  第一次建置完成後，此標記會導致預設的作業系統網頁瀏覽器在本機網站的首頁開啟。
  背景：#3500

草稿

exclude_docs 設定被分成兩個獨立的概念。

exclude_docs 設定不再針對 mkdocs serve 有任何特殊行為 - 它現在始終將列出的文件從網站中完全排除。

如果您希望使用類似於 MkDocs 1.5 中 exclude_docs 鍵所使用的「草稿」功能，請切換到新的設定鍵 draft_docs。

請參閱文件。

其他變更

• 當「草稿」頁面有指向不存在檔案的連結時，降低警告等級。背景：#3449

更新頁面標題的推導

MkDocs 1.5 在從第一個標題推導頁面標題的行為上有所變更。不幸的是，這可能會導致在邊緣案例中出現未轉義的 HTML 標籤或實體。

現在標籤始終會從標題中完全清除。儘管 Page.title 預期會包含 HTML 實體，並直接傳遞給主題，情況依然如此。

影像（特別是某些延伸模組中的表情符號）僅透過其 alt 屬性的值保留在標題中。

背景：#3564、#3578

主題

• 內建主題現在也支援波蘭語（#3613）

「readthedocs」主題

• 修復：「readthedocs」主題現在可以正確處理深度巢狀的導覽設定（超過 2 層深），而不會混亂地展開所有區段並垂直跳動。（#3464）

• 修復：「readthedocs」主題現在即使不是 3 個已知的託管者之一，也會顯示儲存庫的連結（帶有通用標誌）。（#3435）

• 「readthedocs」主題現在在頁尾中也有「主題」一詞的翻譯，該詞錯誤地始終保留為英文。（#3613、#3625）

「mkdocs」主題

「mkdocs」主題已大幅更新為較新版本的 Bootstrap，這意味著樣式的稍微改進。顏色（最明顯的是警告）的對比度更好。

「mkdocs」主題現在支援深色模式 - 自動（根據作業系統/瀏覽器設定）和手動切換。這兩個選項預設都未啟用，需要明確設定。
請參閱文件中的 color_mode、user_color_mode_toggle。

extra_javascript:
  - https://code.jquery.com/jquery-3.7.1.min.js

背景：#3493、#3649

設定

所有外掛的新「enabled」設定

您可能已經看到某些外掛採用了具有設定 enabled: false（或通常透過環境變數控制）的慣例，以使外掛不執行任何操作。

現在每個外掛都有此設定。外掛仍然可以選擇自行實作此設定並決定其行為方式（並且除非它們放棄較舊版本的 MkDocs，否則它們現在仍然應該這樣做），但現在每個外掛都有備用設定。

請參閱文件。背景：#3395

驗證

驗證頁面之間的超連結

絕對連結

過去，在 Markdown 中，MkDocs 只會辨識指向另一個實際 *.md 文件（或媒體檔案）的相對連結。這是一個很好的慣例，因為這樣來源頁面也可以在沒有 MkDocs 的情況下自由瀏覽，例如在 GitHub 上。而絕對連結則保持不變（使其通常無法按預期工作，或者最近會發出警告）。

如果您不喜歡總是使用相對連結，現在您可以選擇使用絕對連結並讓它們正常工作。

如果您將設定 validation.links.absolute_links 設定為新的值 relative_to_docs，所有以 / 開頭的 Markdown 連結都會被理解為相對於 docs_dir 根目錄。接著，這些連結將會根據所有先前版本中已適用於相對連結的規則進行正確性驗證。對於 HTML 輸出，這些連結仍然會被轉換為相對連結，以確保網站能可靠地運作。

因此，現在任何文件（例如 "dir1/foo.md"）都可以連結到文件 "dir2/bar.md"，使用 [link](/dir2/bar.md) 的方式，除了先前唯一正確的方式 [link](../dir2/bar.md) 之外。

不過，您必須啟用此設定。預設情況下，仍然會直接跳過對這類連結的處理。

請參閱文件。相關背景：#3485

導覽中的絕對連結

nav: 設定中的絕對連結也一直被跳過。現在也可以使用 validation.nav.absolute_links 以相同方式驗證它們。儘管這樣做意義較小，因為這樣語法就只是與不帶前導斜線的語法重複了。

錨點

有一個新的設定選項，建議啟用以顯示警告。

validation:
  anchors: warn

以下是此選項可能產生的警告範例：

WARNING -  Doc file 'foo/example.md' contains a link '../bar.md#some-heading', but the doc 'foo/bar.md' does not contain an anchor '#some-heading'.

以下任何一種宣告錨點的方法都會被 MkDocs 偵測到：

## Heading producing an anchor

## Another heading {#custom-anchor-for-heading-using-attr-list}

<a id="raw-anchor"></a>

[](){#markdown-anchor-using-attr-list}

為了與此相容，插入錨點的插件和擴充功能需要開發為樹狀處理器，以插入 etree 元素作為其運作模式，而不是原始 HTML，因為原始 HTML 無法被偵測到。

如果您身為使用者遇到錯誤回報遺失的錨點，且沒有任何方法可以解決此問題，您可以選擇將此選項設定為 ignore 來停用這些訊息（它們預設情況下也是 INFO 等級）。

請參閱文件。相關背景：#3463

其他變更

• 當完全沒有指定 nav 設定時，not_in_nav 設定（最初在 1.5.0 版本中新增）會獲得一個額外的行為：not_in_nav 涵蓋的文件將不會是自動推斷導覽的一部分。相關背景：#3443

• 修正：用於 markdown_extensions 的 !relative YAML 標籤（最初在 1.5.0 版本中新增） - 它在許多典型使用案例中損壞了。

  請參閱文件。相關背景：#3466

• 組態驗證現在會在第一個錯誤時退出，以避免顯示奇怪的次要錯誤。相關背景：#3437

• MkDocs 過去會縮短「找不到檔案」等意外錯誤的錯誤訊息，但現在情況不再如此，將可以查看完整的錯誤訊息和堆疊追蹤（當然，除非錯誤有適當的處理常式）。相關背景：#3445

插件開發人員的升級

插件可以為相同的事件類型添加多個處理常式，並設定不同的優先順序

請參閱mkdocs.plugins.CombinedEvent，位於文件中。相關背景：#3448

啟用真正的產生檔案並擴展 File API

請參閱文件。

• 有一對新的屬性 File.content_string/content_bytes 成為獲取檔案內容的官方 API，並且 MkDocs 本身也使用它們。

  這取代了舊方法，以前必須手動讀取位於 File.abs_src_path 的檔案，儘管這仍然是這些新屬性在底層執行的主要動作。

• File 的內容可以由字串支援，不再需要是 abs_src_path 中真實存在的檔案。

  可以設定屬性 File.content_string 或 File.content_bytes，它們將優先於 abs_src_path。

  此外，不再保證 abs_src_path 一定存在，它可以是 None。MkDocs 本身在所有情況下仍然使用實體檔案，但最終會出現不填寫此屬性的插件。

• 有一個新的建構函式 File.generated()，插件應該使用它來取代 File() 建構函式。它更方便，因為不需要手動查找 docs_dir 和 use_directory_urls 等值。其簽名如下：

  f = File.generated(config: MkDocsConfig, src_uri: str, content: str | bytes)
  f = File.generated(config: MkDocsConfig, src_uri: str, abs_src_path: str)

  這樣一來，即使從掛鉤中添加虛擬檔案也變得非常容易。

  def on_files(files: Files, config: MkDocsConfig):
      files.append(File.generated(config, 'fake/path.md', content="Hello, world!"))

  對於大型內容，最好還是使用實體檔案，但不再需要透過提供假的未使用的 docs_dir 來操作路徑。

• 有一個新的屬性 File.generated_by，它是按照慣例產生的 - 對於產生的檔案，它應該設定為產生此檔案的插件名稱（plugins: 集合中的鍵）。當使用 File.generated() 建構函式時，此屬性會自動填入。

• 可以設定 File 的 edit_uri 屬性，例如從插件或掛鉤設定，使其與預設值（等於 src_uri）不同，這將會反映在文件的編輯連結中。這可能很有用，因為某些頁面不是由真實檔案支援，而是從其他來源檔案或腳本動態建立。因此，掛鉤可以將 edit_uri 相應地設定為該來源檔案或腳本。

• File 物件現在會將其原始的 src_dir、dest_dir、use_directory_urls 值儲存為屬性。

• File 的欄位是按需計算的，但會被快取。只有以上三個屬性是主要屬性，部分也包括 dest_uri。這樣一來，就可以例如覆寫 File 的 dest_uri，而 abs_dest_path 將會基於它來計算。不過，您需要先使用 del f.abs_dest_path 清除該屬性，因為這些值會被快取。

• File 實例現在是可雜湊的（可以用作 dict 的鍵）。除非是完全相同的 File 實例，否則不再能將兩個檔案視為「相等」。

其他變更

• Files 物件內部 File 物件的內部儲存方式已重新設計，因此任何選擇存取 Files._files 的插件都會收到棄用警告。

• 當自動推斷 nav 時，Files 集合中 File 物件的順序不再重要。它們會強制按照預設的字母順序排序。

相關背景：#3451, #3463

掛鉤和除錯

• 掛鉤檔案現在可以使用 import 語句導入相鄰的 *.py 檔案。以前只能透過 sys.path 的變通方法實現。請參閱文件中的新說明。相關背景：#3568

• 詳細的 -v 記錄會更詳細地顯示插件事件的順序 - 一個接一個地顯示每個調用的插件，而不僅僅是事件類型。相關背景：#3444

棄用

• 不再支援 Python 3.7，正式支援 Python 3.12。相關背景：#3429

• 主題組態檔案 mkdocs_theme.yml 不再執行 YAML 標籤。相關背景：#3465

• 插件事件 on_page_read_source 已被軟性棄用，因為總是有更好的替代方案（請參閱新的 File API 或僅使用 on_page_markdown，取決於所需的互動）。

  當多個插件/掛鉤應用此事件處理常式時，它們會互相覆蓋，因此現在在這種情況下會有警告。

  請參閱文件。相關背景：#3503

API 棄用

• 不再允許將 File.page 設定為 Page 或其子類別以外的類型。相關背景：#3443 - 遵循 1.5.3 版中的棄用和 #3381。

• Theme._vars 已棄用 - 請使用 theme['foo'] 取代 theme._vars['foo']

• utils：modified_time()、get_html_path()、get_url_path()、is_html_file()、is_template_file() 已移除。path_to_url() 已棄用。

• LiveReloadServer.watch() 不再接受自訂的回呼。

相關背景：#3429

其他

• sitemap.xml.gz 檔案的可重現性略有提高，不再每次建置時都變更，而是每天只變更一次（在日期變更時）。相關背景：#3460

其他小的改進；請參閱提交日誌。

1.5.3 版本 (2023-09-18)

• 修正 mkdocs serve 在快速導覽時有時會鎖定所有瀏覽器分頁的問題 (#3390)

• 為「search」插件新增許多新的支援語言 - 將 lunr-languages 更新至 1.12.0 (#3334)

• 錯誤修正（1.5.0 版本中的回歸）：在「readthedocs」主題中，巢狀頁面的「麵包屑導覽」樣式已損壞 (#3383)

• 內建主題現在也支援中文（繁體，台灣）語言 (#3154)

• 插件現在可以將 File.page 設定為它們自己的 Page 子類別。現在，如果將 File.page 設定為任何非 Page 嚴格子類別的物件，也會出現警告。 (#3367, #3381)

  請注意，僅僅實例化一個 Page 會自動設定檔案，因此需要小心，不要建立不需要的 Page。

其他小的改進；請參閱提交日誌。

版本 1.5.2 (2023-08-02)

• 錯誤修復（1.5.0 中的回歸）：恢復 --no-livereload 的功能。（#3320）

• 錯誤修復（1.5.0 中的回歸）：新的頁面標題偵測有時無法捨棄錨點連結 - 修復此問題。（#3325）

• 部分恢復 1.5 之前的 API：extra_javascript 項目將再次主要為字串，只有在使用了額外的 script 功能時才會是 ExtraScriptValue。

  外掛程式應該可以自由地將字串附加到 config.extra_javascript，但在讀取這些值時，它們仍然必須確保將其讀取為 str(value)，以防它是 ExtraScriptValue 項目。若要查詢像是 .type 的屬性，您需要先檢查 isinstance。靜態類型檢查會在此方面引導您。（#3324）

請參閱提交日誌。

版本 1.5.1 (2023-07-28)

• 錯誤修復（1.5.0 中的回歸）：使將 ExtraScriptValue 視為路徑成為可能。這讓一些外掛程式即使在重大變更後仍然可以運作。

• 錯誤修復（1.5.0 中的回歸）：防止具有 3 個衝突檔案（例如 index.html、index.md *和* README.md）的特殊設定發生錯誤。（#3314）

請參閱提交日誌。

版本 1.5.0 (2023-07-26)

新命令 mkdocs get-deps

此命令會猜測建構 MkDocs 網站所需的 Python 相依性。它只會印出需要安裝的 PyPI 套件。在終端機中，它可以直接與安裝命令結合，如下所示

pip install $(mkdocs get-deps)

其概念是，在執行此命令後，您可以直接接著執行 mkdocs build，而且幾乎總是「直接運作」，而無需思考要安裝哪些相依性。

它的運作方式是掃描 mkdocs.yml 中的 themes:、plugins:、markdown_extensions: 項目，並根據已知專案的大型清單（目錄，見下文）進行反向查找。

當然，您可以使用帶有此類命令的「虛擬環境」。另請注意，對於需要穩定性的環境（例如 CI），以這種方式直接安裝相依性並不是非常可靠的方法，因為它排除了相依性釘選。

此命令允許覆寫使用的組態檔（而不是目前目錄中的 mkdocs.yml）以及使用的專案目錄（而不是從預設位置下載）。請參閱mkdocs get-deps --help。

背景資訊：#3205

MkDocs 有一個官方的外掛程式目錄

請查看 https://github.com/mkdocs/catalog 並在那裡新增您所有的通用外掛程式、佈景主題和擴充功能，以便可以透過 mkdocs get-deps 查找它們。

這已從「best-of-mkdocs」重新命名，並進行了重大更新。除了 pip 安裝命令外，該頁面現在還顯示新增外掛程式所需的組態樣板。

擴展的連結驗證

已驗證 Markdown 中的連結

您可能知道，在 Markdown 中，MkDocs 實際上只會辨識導向另一個實體 *.md 文件（或媒體檔案）的相對連結。這是一個很好的慣例，因為這樣的話，原始頁面也可以在沒有 MkDocs 的情況下自由瀏覽，例如在 GitHub 上。MkDocs 知道在輸出中，它應該將這些 *.md 連結適當地轉換為 *.html，而且如果此類連結實際上沒有導向現有檔案，它也總是會告訴您。

但是，連結的檢查非常鬆散，並且有許多讓步。例如，以 / 開頭（「絕對」）的連結和*以* / 結尾的連結會保持原樣，並且不會顯示任何警告，這允許此類非常脆弱的連結潛入網站來源：連結碰巧現在可以運作，但沒有獲得任何驗證，以及在啟用 use_directory_urls 時令人困惑地需要額外一層 .. 的連結。

現在，除了驗證相對連結外，MkDocs 還會針對無法識別的連結類型（包括絕對連結）列印 INFO 訊息。它們看起來像這樣

INFO - Doc file 'example.md' contains an absolute link '/foo/bar/', it was left as is. Did you mean 'foo/bar.md'?

如果您不想要任何變更，甚至連 INFO 訊息也不要，並且希望恢復到 MkDocs 1.4 的靜默狀態，請將以下組態新增至 mkdocs.yml（不建議）

validation:
  absolute_links: ignore
  unrecognized_links: ignore

反之，如果您希望這些訊息列印 WARNING 訊息並導致 mkdocs build --strict 失敗，則建議將這些組態設定為 warn。

請參閱文件以取得實際建議的設定和更多詳細資訊。背景資訊：#3283

已驗證導覽列中的連結

現在，nav 組態中文件的連結也具有可設定的驗證，但預設值沒有變更。

歡迎您啟用對遺忘並從導覽列中排除的檔案進行驗證。範例

validation:
  nav:
    omitted_files: warn
    absolute_links: warn

這可以使以下訊息以 WARNING 層級顯示（相較於先前唯一的選項 INFO），因此會被 mkdocs --strict 捕獲

INFO - The following pages exist in the docs directory, but are not included in the "nav" configuration: ...

請參閱文件。背景資訊：#3283、#1755

將文件標記為故意「不在導覽列中」

有一個新的組態 not_in_nav。有了它，您可以將特定的檔案模式標記為免除上述 omitted_files 警告類型；它們將不再列印任何訊息。（作為必然結果，將此組態設定為 * 與完全忽略 omitted_files 相同。）

如果您通常喜歡這些關於從導覽列中遺忘的檔案的警告，但仍然有一些您明知從導覽列中排除並且只想建構和複製的頁面，這會很有用。

not_in_nav 組態是一組類似 gitignore 的模式。有關另一個此類組態的說明，請參閱下一節。

請參閱文件。背景資訊：#3224、#1888

排除的文件

有一個新的組態 exclude_docs，它告訴 MkDocs 忽略 docs_dir 下的某些檔案，並且*不*將它們作為建構的一部分複製到建構的 site。

過去，MkDocs 總是會忽略以點開頭的檔案名稱，僅此而已。現在這一切都是可設定的：您可以取消忽略這些檔案，和/或忽略更多模式的檔案。

exclude_docs 組態遵循 .gitignore 模式格式，並指定為多行 YAML 字串。例如

exclude_docs: |
  *.py               # Excludes e.g. docs/hooks/foo.py
  /requirements.txt  # Excludes docs/requirements.txt

連結驗證（如上所述）也受 exclude_docs 的影響。在 mkdocs serve 期間，訊息會說明互動方式，而在 mkdocs build 期間，排除的檔案等同於不存在。

作為另一個相關的變更，如果您需要在目錄中同時擁有 README.md 和 index.md 檔案，但只發布其中一個，您現在可以使用此功能來明確忽略其中一個，並避免警告。

請參閱文件。背景資訊：#3224

草稿

exclude_docs 組態還有另一個行為：所有排除的 Markdown 頁面仍然可以在 mkdocs serve 中預覽，只是在頂部帶有「草稿」標記。然後，它們當然會從 mkdocs build 或 gh-deploy 中排除。

如果您不希望 mkdocs serve 具有任何特殊行為，而是希望它執行完全正常的建構，請使用新的旗標 mkdocs serve --clean。

請參閱文件。背景資訊：#3224

mkdocs serve 不再在建構錯誤後退出

如果在網站重新建構期間發生錯誤（來自組態或外掛程式），mkdocs serve 過去會在列印堆疊追蹤後退出。現在它只會凍結伺服器，直到作者編輯檔案以修復問題，然後將繼續重新載入。

但是，在*第一次*建構時發生錯誤仍然會導致 mkdocs serve 退出，就像以前一樣。

背景資訊：#3255

頁面標題將從任何樣式的標題推斷而得

MkDocs 一直以來都能夠根據文件的第一行推斷頁面的標題（如果未在 nav 中指定），前提是該行具有以確切字元 # 開頭的 <h1> 標題。現在，任何樣式的 Markdown 標題都可被理解（#1886）。由於先前簡化的解析方式，也無法在第一個標題中使用 attr_list 屬性（#3136）。現在這個問題也已解決。

Markdown 擴充功能可以使用相對於目前文件的路徑

這是針對諸如 pymdownx.snippets 或 markdown_include.include 之類的擴充功能：您現在可以將它們的包含路徑指定為相對於目前渲染的 Markdown 文件，或相對於 docs_dir。任何其他擴充功能當然也可以利用新的 !relative YAML 標籤。

markdown_extensions:
  - pymdownx.snippets:
      base_path: !relative

請參閱文件。相關資訊：#2154, #3258

<script> 標籤可以指定 type="module" 和其他屬性

在 extra_javascript 中，如果您使用 .mjs 檔案副檔名或明確指定 type: module 金鑰，則腳本將會新增 type="module" 屬性。defer: true 和 async: true 金鑰也可用。

請參閱更新後的 extra_javascript文件。

首先，這僅在內建主題中支援，其他主題需要跟進，請參閱下文。

相關資訊：#3237

針對主題開發人員的變更（需要採取行動！）

使用結構 {% for script in extra_javascript %} 現在完全過時了，因為它不允許自訂 <script> 標籤的屬性。它會繼續運作，但會阻礙 MkDocs 的某些功能。

相反地，您現在需要使用 config.extra_javascript（一段時間以來一直是這種情況），並將其與新的 script_tag 篩選器搭配使用。

    {%- for script in config.extra_javascript %}
      {{ script | script_tag }}
    {%- endfor %}

請參閱文件。

針對外掛程式開發人員的升級

• 重大變更：config.extra_javascript 不再是字串的簡單列表，而是 ExtraScriptValue 項目的列表。因此，您不能再將列表值視為字串。如果您想保持與舊版本的相容性，只需始終將項目作為 str(item) 引用即可。如果您願意，仍然可以將純字串附加到列表中。請參閱上面關於 <script> 標籤的資訊。相關資訊：#3237

• File 有一個新的屬性 inclusion。其值是從 exclude_docs 和 not_in_nav 設定計算得出的，並實作了它們的行為。外掛程式可以讀取或寫入此值。預設情況下，新的 File 實例會遵循設定中的規定，但外掛程式可以選擇針對每個檔案明確地做出此決策。

• 建立 File 時，現在可以直接設定 dest_uri，而不必在建立後更新它（以及其他相關的屬性）。相關資訊

• 新增了一個新的設定選項 - DictOfItems。與 ListOfItems 類似，它會驗證所有具有相同類型的設定選項的對應。金鑰是任意的，但始終是字串。相關資訊：#3242

• 新增了一個新的函數 get_plugin_logger。為了選擇加入外掛程式記錄訊息的標準化方式，請使用以下慣用法

  log = mkdocs.plugins.get_plugin_logger(__name__)
  ...
  log.info("Hello, world")

  相關資訊：#3245

• 可以使用指定的特定設定類型來方便地對 SubConfig 設定選項進行子類別化。例如：class ExtraScript(SubConfig[ExtraScriptValue]):。若要查看這有何用處，請在程式碼中搜尋此類別。相關資訊

• 錯誤修正：SubConfig 有一個錯誤，其中路徑（來自 FilesystemObject 選項）並未按預期相對於主要設定檔，因為 config_file_path 並未正確繼承給它。現在已修正此問題。相關資訊：#3265

• Config 成員現在有一種方法可以避免與 Python 的保留字衝突。這是透過從每個成員的名稱中刪除尾隨底線來實現的。

  新增一個 async 布林選項的範例，使用者可以將其設定為 async: true，並以程式設計方式讀取為 config.async_

  class ExampleConfig(Config):
      async_ = Type(bool, default=False)

  先前，使用新式架構無法使用保留名稱建立設定金鑰。相關資訊

• Theme 正確宣告了其屬性，並獲得了新的屬性 theme.locale、theme.custom_dir。

• 一些類型註解變得更精確。例如

  • context 參數獲得了類型 TemplateContext (TypedDict)。相關資訊
  • 類別 Page、Section、Link 現在具有一個通用的基底類別 StructureItem。相關資訊
  • 某些方法停止接受 Config，而僅接受最初預期的 MkDocsConfig。相關資訊
  • config.mdx_configs 獲得了正確的類型。相關資訊：#3229

主題更新

• 內建主題主要停止依賴 <script defer>。這可能會影響 extra_javascript 的某些用法，主要是消除了對「頁面是否已完全載入」進行自訂處理的需求。相關資訊：#3237

• 「mkdocs」主題現在具有 > 區塊引號的樣式，先前它們完全沒有區別。相關資訊：#3291

• 「readthedocs」主題已根據上游更新至 v1.2.0，並改進了 <kbd> 和麵包屑導覽的樣式。相關資訊：#3058

• 這兩個內建主題的 highlight.js 版本都已更新至 11.8.0，而 jQuery 也已更新至 3.6.0。

錯誤修正

導覽中的相對路徑可以遍歷到根目錄之上

1.2 版中的回歸 - 導覽中的相對路徑無法再遍歷到網站的根目錄之上，並被截斷為根目錄。儘管不鼓勵這種遍歷並會產生警告，但這是一種有文件記錄的行為。現在已還原此行為。

相關資訊：#2752, #3010

MkDocs 可以從標準輸入接受設定

這可以用於即時設定覆寫。請參閱設定繼承底部的更新章節。

使用此功能的命令是 mkdocs build -f -。在先前的版本中，執行此操作會導致錯誤。

相關資訊

新的命令列旗標

• mkdocs --no-color build 會停用顏色輸出和換行。也可以透過環境變數 NO_COLOR=true 使用此選項。相關資訊：#3282
• mkdocs build --no-strict 會將 strict 設定覆寫為 false。相關資訊：#3254
• mkdocs build -f -（直接在上面描述）。
• mkdocs serve --clean（如上所述）。
• mkdocs serve --dirty 是 mkdocs serve --dirtyreload 的新名稱。

棄用

• extra_javascript 進行了變更，在極少數情況下可能會破壞外掛程式，並且需要主題開發人員的注意。請參閱上面的相關條目。

• Python-Markdown 已從 <3.4 中取消固定。已知該版本會移除功能。如果您受到這些移除的影響，仍然可以選擇自行固定版本：Markdown <3.4。相關資訊：#3222, #2892

• mkdocs.utils.warning_filter 現在會顯示有關已被棄用的警告。自 MkDocs 1.2 以來它沒有任何作用。請考慮改用 get_plugin_logger 或僅在 mkdocs.plugins.* 下記錄。相關資訊：#3008

• 存取 Theme 的 _vars 屬性已被棄用 - 只需直接存取金鑰即可。

• 存取 Config 的 user_configs 屬性已棄用。請注意：請使用新的屬性 config.theme.custom_dir，而非 config.user_configs[*]['theme']['custom_dir']。

其他小改進；請參閱提交日誌。

版本 1.4.3 (2023-05-02)

• 錯誤修正：對於 hooks 功能，如果使用一些進階的 Python 功能（例如 dataclasses），模組不再載入失敗 (#3193)

• 錯誤修正：如果頁面沒有已填入的 URL，則不會建立 None 的網站地圖項目 - 這會影響到從導覽中排除某些檔案的網站 (07a297b)

• "readthedocs" 主題

  • 無障礙功能：為首頁標誌 (#3129) 和搜尋輸入框 (#3046) 新增 aria 標籤
  • "readthedocs" 主題現在支援 hljs_style: 設定，與 "mkdocs" 主題相同 (#3199)

• 翻譯

  • 內建主題現在也支援印尼語 (#3154)
  • 修正 zh_CN 翻譯 (#3125)
  • tr_TR 翻譯改為 tr - 使用方式應該不受影響 (#3195)

請參閱提交日誌。

版本 1.4.2 (2022-11-01)

• 正式支援 Python 3.11 (#3020)

  提示

  單純升級到 Python 3.11 可以縮短網站 10-15% 的建置時間。

• 支援同一個外掛程式的多個實例 (#3027)

  如果在外掛程式的 plugins: 設定下多次指定同一個外掛程式，這將會建立 2 個（或更多）外掛程式實例，每個實例都有自己的設定。

  先前這個情況是無法預見的，因此會發生錯誤。

  現在即使這樣做可以運作，但預設情況下，MkDocs 仍會顯示警告，除非外掛程式新增了一個類別變數 supports_multiple_instances = True。

• 錯誤修正（1.4.1 版中的回歸問題）：當外掛程式將純文字字串放入 warnings 時，不會發生錯誤 (#3016)

• 錯誤修正：相對連結將始終以尾隨斜線呈現 (#3022)

  先前在 use_directory_urls 下，從子頁面連結到主索引頁面的連結會呈現為例如 <a href="../..">，即使在所有其他情況下，連結看起來像 <a href="../../">。這導致某些網頁瀏覽器和伺服器組合出現不必要的行為。現在已移除此特殊情況錯誤。

• 內建 "mkdocs" 主題現在也支援挪威語 (#3024)

• 與外掛程式相關的警告看起來更易讀 (#3016)

請參閱提交日誌。

版本 1.4.1 (2022-10-15)

• 支援主題命名空間的外掛程式載入 (#2998)

  外掛程式的進入點可以命名為 'sometheme/someplugin'。這將產生以下結果

  • 如果目前的主題是 'sometheme'，則外掛程式 'sometheme/someplugin' 將始終優先於 'someplugin'。
  • 如果目前的主題不是 'sometheme'，則使用此外掛程式的唯一方法是指定 plugins: [sometheme/someplugin]。

  也可以指定 plugins: ['/someplugin'] 而不是 plugins: ['someplugin']，以明確避免使用主題命名空間的外掛程式。

• 錯誤修正：mkdocs serve 將使用非 ASCII 路徑和重新導向正確運作 (#3001)

• Windows：'colorama' 現在是 MkDocs 的相依性，以確保色彩豐富的日誌輸出 (#2987)

• 與外掛程式相關的設定選項具有更可靠的驗證和錯誤報告 (#2997)

• setup.py 的翻譯子命令已完全刪除。請參閱文件 [1] [2] 了解其新的替代方案 (#2990)

• 'mkdocs' 套件（wheel 和原始碼）現在由 Hatch 建置系統和 pyproject.toml 產生，而不是 setup.py (#2988)

其他小改進；請參閱提交日誌。

版本 1.4.0 (2022-09-27)

功能升級

Hook (#2978)

新的 hooks: 設定允許您從本機 Python 檔案新增類似外掛程式的事件處理常式，而無需設定和安裝實際的外掛程式。

請參閱文件。

edit_uri 彈性 (#2927)

有一個新的 edit_uri_template: 設定。
它的運作方式與 edit_uri 類似，但更廣泛地涵蓋了建構編輯 URL 的方法。
請參閱文件。

此外，即使省略了 repo_url，edit_uri 功能現在也能完全運作 (#2928)

外掛程式開發人員的升級

自訂外掛程式事件處理常式的事件順序 (#2973)

外掛程式現在可以選擇為其事件處理常式設定優先順序值。這可以覆寫舊的行為，其中每個事件類型的處理常式都按照其外掛程式在plugins 設定中出現的順序呼叫。

如果設定了此值，則會先呼叫優先順序較高的事件。沒有選擇優先順序的事件會獲得預設值 0。具有相同優先順序的事件會按照其在設定中出現的順序排序。

建議的優先順序值：100 "first"、50 "early"、0 "default"、-50 "late"、-100 "last"。
隨著不同的外掛程式發現彼此之間更精確的關係，應進一步調整這些值。

請參閱文件。

在 mkdocs serve 中跨建置持續存在的新事件 (#2972)

新的事件是 on_startup 和 on_shutdown。它們在 mkdocs 呼叫的開始和結束時執行。
on_startup 還會收到有關如何呼叫 mkdocs 的資訊（例如 serve --dirtyreload）。

請參閱文件。

取代 File.src_path 以處理反斜線 (#2930)

屬性 src_path 在 Windows 上使用反斜線，這沒有意義，因為它是一個虛擬路徑。
為了不進行重大變更，此屬性的使用方式沒有任何變更，但現在您應該

• 使用 File.src_uri 而不是 File.src_path
• 和 File.dest_uri 而不是 File.dest_path。

這些始終使用正斜線，現在是 MkDocs 本身使用的明確來源。

請參閱原始碼。

作為相關提示：您也應該停止使用 os.path.* 或 pathlib.Path() 來處理這些路徑，而是使用 posixpath.* 或 pathlib.PurePosixPath()

MkDocs 已加入類型註解，可以使用 mypy (#2941, #2970)

事件處理常式方法的類型註解 (#2931)

MkDocs 的外掛程式事件方法現在具有類型註解。您可能已經在為事件新增註解，但現在它們將被驗證以符合原始註解。

請參閱原始碼和文件。

其中一個重大更新是，現在您應該更具體地將方法參數註解為 config: defaults.MkDocsConfig，而不是 config: base.Config。這不僅清楚地表明它是 MkDocs 本身的主要設定，還提供通過物件屬性進行的型別安全存取（請參閱下一節）。

請參閱原始碼和文件。

將 ConfigOption 結構重新設計為基於類別的結構 (#2962)

在開發外掛程式時，它接受的設定過去是在外掛程式類別上的 config_scheme 變數中指定的。
此方法現在已軟性棄用，您應該改為在 base.Config 的子類別中指定設定。

舊範例

from mkdocs import plugins
from mkdocs.config import base, config_options

class MyPlugin(plugins.BasePlugin):
    config_scheme = (
        ('foo', config_options.Type(int)),
        ('bar', config_options.Type(str, default='')),
    )

    def on_page_markdown(self, markdown: str, *, config: base.Config, **kwargs):
        if self.config['foo'] < 5:
            if config['site_url'].startswith('http:'):
                return markdown + self.config['baz']

這段程式碼實際上有很多錯誤，但它會通過所有類型檢查，並且在某些情況下會靜默地執行甚至成功。

接下來，我們來看新的等效範例，它已更改為新式 schema 和基於屬性的存取方式
（來自 "mypy" 的抱怨會內嵌顯示）

from mkdocs import plugins
from mkdocs.config import base, config_options as c

class MyPluginConfig(base.Config):
    foo = c.Optional(c.Type(int))
    bar = c.Type(str, default='')

class MyPlugin(plugins.BasePlugin[MyPluginConfig]):
    def on_page_markdown(self, markdown: str, *, config: defaults.MkDocsConfig, **kwargs):
        if self.config.foo < 5:  # Error, `foo` might be `None`, need to check first.
            if config.site_url.startswith('http:'):  # Error, MkDocs' `site_url` also might be `None`.
                return markdown + self.config.baz  # Error, no such attribute `baz`!

這讓您在執行程式碼之前就能注意到靜態類型檢查器的錯誤，並加以修正

class MyPlugin(plugins.BasePlugin[MyPluginConfig]):
    def on_page_markdown(self, markdown: str, *, config: defaults.MkDocsConfig, **kwargs):
        if self.config.foo is not None and self.config.foo < 5:  # OK, `int < int` is valid.
            if (config.site_url or '').startswith('http:'):  # OK, `str.startswith(str)` is valid.
                return markdown + self.config.bar  # OK, `str + str` is valid.

請參閱 文件。

另請注意，我們必須明確將 config 屬性 foo 標記為 Optional。
新式 config 的所有屬性預設都會標記為必填，而且不允許指定 required=False 或 required=True！

新增：config_options.Optional (#2962)

將某個東西包裝到 Optional 中，概念上類似於「我希望預設值為 None」—— 而且您必須這樣表達，因為寫成 default=None 實際上不起作用。

重大變更：方法 BaseConfigOption.is_required() 已移除。請改用 .required。（#2938）
而且現在 required 屬性大多應該不會用到。
對於基於類別的 config，選項是否為「必填」有新的定義

• 它沒有預設值，而且
• 它沒有被包裝到 config_options.Optional 中。

新增：config_options.ListOfItems (#2938)

定義一個項目列表，每個項目都必須符合相同的限制。有點像驗證過的 Type(list)

如何表示整數列表的範例（使用 from mkdocs.config import config_options as c）

請參閱 文件 中更多範例。

已更新：config_options.SubConfig (#2807)

SubConfig 過去會靜默忽略對其 config 選項的所有驗證。現在您應該傳遞 validate=True 給它，或者直接使用新的基於類別的 config，其中這已成為預設值。

因此，它可以被用來驗證具有所有預定義金鑰和嚴格驗證數值類型的巢狀子字典。

請參閱 文件 中的範例。

對 config 選項的其他變更

URL 的預設值現在是 None 而不是 ''。這仍然可以像之前一樣檢查其真值 — if config.some_url: (#2962)

FilesystemObject 不再是抽象的，可以直接使用，代表具有可選存在檢查的「檔案或目錄」（#2938）

錯誤修正

• 修正 SubConfig、ConfigItems、MarkdownExtensions 不會跨不同實例洩漏數值的問題 (#2916、#2290)
• SubConfig 會引發正確種類的驗證錯誤，而不會出現堆疊追蹤 (#2938)
• 修正 config_options.Deprecated(moved_to) 中以點分隔的重新導向問題 (#2963)

調整處理 ConfigOption.default 的邏輯 (#2938)

已棄用的 config 選項類別：ConfigItems (#2983)、OptionallyRequired (#2962)、RepoURL (#2927)

主題更新

• 「MkDocs」主題中提示框的樣式 (#2981)

  • 更新色彩以增加對比度
  • 將提示框樣式也應用於 <details> 標籤，以支援提供它的 Markdown 擴充功能 (pymdownx.details、callouts)

• 內建主題現在也支援這些語言

  • 俄語 (#2976)
  • 土耳其語（土耳其）(#2946)
  • 烏克蘭語 (#2980)

未來相容性

• 如果將反斜線 \ 傳遞給 extra_css: 和 extra_javascript:，則會發出警告。（#2930、#2984）

• 將 DeprecationWarning 顯示為 INFO 訊息。（#2907）

  如果您使用的任何外掛程式或擴充功能依賴其他程式庫中已棄用的功能，則它在不久的將來可能會無法運作。外掛程式開發人員應及時處理這些問題。

• 從 Python 3.10 開始，避免依賴 importlib_metadata (#2959)

• 停止支援 Python 3.6 (#2948)

對公開 API 的不相容變更

• mkdocs.utils:
  • 如果將反斜線 \ 傳遞給 create_media_urls 和 normalize_url，則會發出警告。（#2930）
  • is_markdown_file 停止接受不區分大小寫的變體，例如 .MD，這與 MkDocs 建置的運作方式相同。（#2912）
  • 已硬性棄用：modified_time、reduce_list、get_html_path、get_url_path、is_html_file、is_template_file。（#2912）

雜項

• 如果外掛程式在 LiveReloadServer 中將路徑新增到 watch，現在可以 unwatch 它們。（#2777）

• 錯誤修正（1.2 中的回歸）：支援在 mkdocs serve 中監聽 IPv6 位址。（#2951）

其他小型改進；請參閱 commit 記錄。

版本 1.3.1 (2022-07-19)

• 將 Python-Markdown 版本鎖定在 <3.4，因此排除其最新版本，因為該版本會破壞太多外部擴充功能 (#2893)

• 當 Markdown 擴充功能無法載入時，印出其名稱和追溯 (#2894)

• 針對「readthedocs」主題的錯誤修正（1.3.0 中的回歸）：在麵包屑中新增遺失的空格 (#2810)

• 錯誤修正：當存在「readme.md」（小寫）檔案時，不要抱怨，否則無法識別它 (#2852)

• 內建主題現在也支援這些語言

  • 義大利語 (#2860)

其他小型改進；請參閱 commit 記錄。

版本 1.3.0 (2022-03-26)

功能升級

• ReadTheDocs 主題已根據上游從 v0.4.1 更新到 v1.0.0 (#2585)

  最值得注意的變更

  • 新增選項 logo：使用者可以指定要顯示的圖片路徑，而不是在標題中顯示 site_name。
  • 用於 Google Analytics 的新選項 anonymize_ip。
  • 相依性已升級：jQuery 升級到 3.6.0，Modernizr.js 已刪除，以及其他變更。

  請參閱主題的 config 選項文件

• 內建主題現在也支援這些語言

  • 德語 (#2633)
  • 波斯語（波斯文）(#2787)

• 支援在執行 mkdocs serve 時監看自訂目錄 (#2642)

  MkDocs 預設會監看 docs 目錄和 config 檔案。現在可以使用 YAML watch 金鑰或命令列旗標 --watch 新增更多目錄以監看變更。

  通常 MkDocs 永遠不會進入任何其他目錄（因此這個功能應該不是必要的），但某些外掛程式和擴充功能可能會這樣做。

  請參閱文件。

• 用於 gh_deploy 的新 --no-history 選項 (#2594)

  允許在部署時捨棄 commit 的歷史記錄，並改用一個根 commit 取代

錯誤修正

• 修復了內建主題中使用搜尋功能時的 XSS 漏洞 (#2791)

• 設定 edit_uri 選項時，不再錯誤地在 repo_url 後面加上尾隨斜線 (#2733)

其他雜項

• 重大變更：已棄用很久的 pages 設定選項，現在使用時會導致錯誤 (#2652)

  要修正此錯誤，只需將 pages 變更為 nav。

• 效能最佳化：在 MkDocs 啟動期間，不會匯入其他指令的程式碼和相依性 (#2714)

  最明顯的效果是，當使用 mkdocs build 時，不會匯入 mkdocs serve 的相依性。

• 遞迴驗證 nav (#2680)

  已重新設計巢狀 nav 結構的驗證，以便及早且可靠地報告錯誤。某些 邊緣案例 已宣告為無效。

其他小改進；請參閱提交紀錄。

版本 1.2.4 (2022-03-26)

• 與 Jinja2 3.1.0 相容 (#2800)

  由於 Jinja2 中的重大變更，MkDocs 會出現錯誤訊息 AttributeError: module 'jinja2' has no attribute 'contextfilter' 而崩潰

版本 1.2.3 (2021-10-12)

• 內建主題現在也支援這些語言

  • 簡體中文 (#2497)
  • 日語 (#2525)
  • 巴西葡萄牙語 (#2535)
  • 西班牙語 (#2545, 之前是 #2396)

• 第三方外掛程式的優先順序高於同名的內建外掛程式 (#2591)

• 錯誤修正：修復某些語言載入翻譯的能力：核心支援 (#2565) 以及具有後備功能的搜尋外掛程式支援 (#2602)

• 錯誤修正 (1.2 版中的回歸)：防止開發伺服器中的目錄遍歷 (#2604)

• 錯誤修正 (1.2 版中的回歸)：防止 Web 伺服器警告在嚴格模式下被視為組建失敗 (#2607)

• 錯誤修正：在 Windows 上正確列印終端機中的彩色訊息 (#2606)

• 錯誤修正：Python 版本 3.10 在 --version 中顯示不正確 (#2618)

其他小改進；請參閱提交紀錄。

版本 1.2.2 (2021-07-18)

• 錯誤修正 (1.2 版中的回歸)：修復提供帶有 Unicode 字元的檔案/路徑 (#2464)

• 錯誤修正 (1.2 版中的回歸)：還原即時重載檔案監看以使用輪詢觀察器 (#2477)

  必須這樣做才能合理支援跨越虛擬檔案系統 (例如非原生 Docker 和網路掛載) 的用法。

  這會回到輪詢方法，與之前一直使用的方法非常相似，這表示延遲和 CPU 使用率方面的大部分缺點仍然存在。

• 從 1.2 版還原：移除 site_url 設定的需求以及對 use_directory_urls 的限制 (#2490)

• 錯誤修正 (1.2 版中的回歸)：在 mkdocs serve 伺服器中提供目錄索引時，URL 中不需要尾隨斜線 (#2507)

  偵測到它是目錄時，不是顯示 404 錯誤，而是會重新導向到加上尾隨斜線的路徑，就像以前一樣。

• 錯誤修正：修復在目前目錄中使用設定檔的 gh_deploy (#2481)

• 錯誤修正：修正 "readthedocs" 主題中反向的麵包屑導覽 (#2179)

• 允許在未傳遞 '--config' 時，使用 "mkdocs.yaml" 作為檔案名稱 (#2478)

• 停止將 ";" 視為 URL 中的特殊字元：urlparse -> urlsplit (#2502)

• 改善具有許多頁面的網站的組建效能 (部分已在 1.2 版中完成) (#2407)

版本 1.2.1 (2021-06-09)

• 錯誤修正 (1.2 版中的回歸)：確保 'gh-deploy' 總是推送。

版本 1.2 (2021-06-04)

1.2 版的主要新增功能

新增對主題本地化的支援 (#2299)

mkdocs 和 readthedocs 主題現在使用 theme.locale 參數支援語言本地化，預設為 en (英文)。此版本中唯一其他支援的語言為 fr (法文) 和 es (西班牙文)。如需使用所提供翻譯的詳細資訊，請參閱使用者指南。請注意，預設不會進行翻譯。使用者必須先使用以下命令安裝必要的相依性

pip install 'mkdocs[i18n]'

歡迎貢獻翻譯，詳細資訊請參閱翻譯指南。

第三方主題的開發人員可能需要檢閱主題開發指南的相關章節。

正在將範本更新到內建主題的貢獻者，應檢閱貢獻指南。

search 外掛程式的 lang 設定現在預設為 theme.locale 中指定的語言。

新增對組態檔中環境變數的支援 (#1954)

現在可以在組態檔中使用 !ENV 標籤指定環境變數。變數的值將由 YAML 剖析器剖析，並轉換為適當的類型。

somekey: !ENV VAR_NAME
otherkey: !ENV [VAR_NAME, FALLBACK_VAR, 'default value']

如需詳細資訊，請參閱組態文件中的環境變數。

新增對組態繼承的支援 (#2218)

組態檔現在可以從父組態檔繼承。在主要檔案中，將 INHERIT 鍵設定為父檔案的相對路徑。

INHERIT: path/to/base.yml

然後這兩個檔案將進行深層合併。如需詳細資訊，請參閱組態繼承。

更新 gh-deploy 命令 (#2170)

已將 ghp_import 的供應商 (和修改後的) 副本取代為上游程式庫的相依性。從 1.0.0 版開始，ghp-import 包含一個 Python API，可直接呼叫。

MkDocs 現在可以受益於最近的錯誤修正和新功能，包括以下內容

• 當部署到 GitHub Pages 時，會自動包含 .nojekyll 檔案。
• 現在可以使用 --shell 旗標，據報導它在 Windows 上效果更好。
• 應該遵守 Git 作者和提交者環境變數 (#1383)。

為 mkdocs serve 重新設計自動重新載入和 HTTP 伺服器 (#2385)

mkdocs serve 現在使用新的底層伺服器 + 檔案監看器實作，基於標準程式庫中的 http.server 和 watchdog。它提供與先前使用的 livereload 程式庫 (現在已從相依性中刪除，以及 tornado) 類似的功能。

這使得重新載入在時間方面更具回應性和一致性。多次快速檔案變更不再導致網站重複組建 (問題 #2061)。

伺服器的幾乎每個方面都略有不同，但實際可見的變更很小。記錄輸出僅類似於舊的輸出。不應預期效能下降，如果發現應回報。

根據 site_url 的子路徑偏移本機網站根目錄 (#2424)

當使用 mkdocs serve 且 site_url 指定為例如 http://example.org/sub/path/ 時，現在本機提供的網站的根目錄會變成 http://127.0.0.1:8000/sub/path/，並且所有文件路徑都會相應地偏移。

新增了 build_error 事件 (#2103)

現在，外掛開發者可以使用 on_build_error 鉤子，在建置網站時發生例外狀況時執行程式碼。

詳細資訊請參閱外掛文件中的 on_build_error。

三個新的例外：BuildError、PluginError 和 Abort (#2103)

MkDocs 現在於 mkdocs.exceptions 中定義了三個新的例外：BuildError、PluginError 和 Abort。

• 外掛可以引發 PluginError 來停止建置並記錄錯誤訊息，不包含追溯資訊。
• 第三方外掛開發者不應使用 BuildError，此例外保留給內部使用。
• Abort 在內部用於中止建置並顯示不包含追溯資訊的錯誤。

詳細資訊請參閱外掛文件中的 處理錯誤。

搜尋索引策略設定

使用者現在可以指定在為網站建立搜尋索引時要使用的策略。使用者可以從以下選項中選擇：

• full：將頁面標題、章節標題和完整頁面文字新增至搜尋索引。
• sections：僅將頁面標題和章節標題新增至搜尋索引。
• titles：僅將頁面標題新增至搜尋索引。

詳細資訊請參閱設定文件中的 搜尋索引。

1.2 版本中的向後不相容變更

• 現在，site_url 設定選項為必要。如果未設定，將會發出警告。在未來的版本中，將會引發錯誤 (#2189)。

  如果 site_url 設定為空字串，則 use_directory_urls 設定選項將會強制設定為 false。在這種情況下，如果 use_directory_urls 未明確設定為 false，將會發出警告 (#2189)。

  注意

  此變更已在 1.2.2 版本中還原。

• google_analytics 設定選項已被棄用，因為 Google 似乎正在逐步淘汰它，轉而支持其新的 Google Analytics 4 資源。請參閱您的佈景主題文件，以尋找可設定為佈景主題設定一部分的替代方案。例如，mkdocs 和 readthedocs 佈景主題都新增了一個新的 theme.analytics.gtag 設定選項，該選項使用新的 Google Analytics 4 資源。請參閱 Google 的文件，了解如何升級至 Google Analytics 4 資源。然後將 theme.analytics.gtag 設定為 "G-" ID，並刪除包含 "UA-" ID 的 google_analytics 設定選項。只要舊的 "UA-" ID 和新的 "G-" ID 在您的 Google 帳戶中正確連結，並且您正在使用 "G-" ID，Google Analytics 就會以新舊格式提供資料。參見 #2252。

• 現在，使用 --livereload 伺服器時，佈景主題的檔案預設會從監視的檔案列表中排除。這種新的預設行為是大多數使用者需要的，並且在編輯網站內容時提供更好的效能。佈景主題開發者可以使用 --watch-theme 選項啟用舊的行為。(#2092)。

• 現在，mkdocs 佈景主題會在列印頁面時移除側邊欄。這可以釋放水平空間，以便更好地呈現表格等內容 (#2193)。

• mkdocs.config.DEFAULT_SCHEMA 全域變數已替換為函式 mkdocs.config.defaults.get_schema()，以確保每個設定實例都是唯一的 (#2289)。

• mkdocs.utils.warning_filter 已被棄用，現在不執行任何操作。外掛應移除對它的任何參考，因為它可能會在未來的版本中被刪除。若要確保任何警告都被計算在內，只需將它們記錄到 mkdocs 記錄檔（例如：mkdocs.plugins.pluginname）。

• on_serve 事件（接收 server 物件和 builder 函式）受到伺服器重寫的影響。現在，server 是 mkdocs.livereload.LiveReloadServer，而不是 livereload.server.Server。外掛可以對這些物件執行的典型操作是呼叫 server.watch(some_dir, builder)，這基本上會將該目錄新增至監視目錄，導致網站在檔案變更時重建。這仍然有效，但是將任何其他函式傳遞給 watch 已被棄用，並會顯示警告。此第二個參數已經是可選的，並且為了相容性，只會接受這個確切的 builder 函式。

• plugins.search.prebuild_index 設定選項的 python 方法自 1.2 版本起即將被棄用。預計在 1.3 版本中，如果使用它，將會發出警告，而在 1.4 版本中，將會引發錯誤。建議使用者使用替代方法來產生預先建立的搜尋索引。

• lunr 和 lunr[languages] 相依性不再預設安裝。這些相依性僅適用於預先建立搜尋索引並使用 python 選項的罕見使用者，該選項現在即將被棄用。如果您使用此功能，則需要手動安裝 lunr 和 lunr[languages]。如果需要但未安裝相依性，則會發出警告。

1.2 版本的其他變更和新增功能

• 錯誤修復：在篩選章節時，正確處理 _get_by_type 中的導覽子項目 (#2203)。
• 已新增對 Python 3.9 的官方支援，並已移除對 Python 3.5 的支援。
• 錯誤修復：修復了會在 ReadTheDocs 佈景主題中導致導覽項目部分截斷的問題 (#2297)。
• 現在，Structure Files 物件具有 remove 方法，以協助外掛開發者操作 Files 樹狀結構。對應的 src_paths 已成為屬性，以適應這種可能的動態行為。參見 #2305。
• 已將 highlight.js 更新至 10.5.0。參見 #2313。
• 錯誤修復：搜尋外掛現在可以與日語一起使用。參見 #2178。
• 已重構文件 (#1629)。
• 還原 readthedocs 佈景主題中表格的樣式 (#2028)。
• 確保 site_url 以斜線結尾 (#1785)。
• 修正 pages 範本內容變數的文件 (#1736)。
• 已將 lunr 相依性更新至 0.5.9，並將 lunr.js 更新至對應的 2.3.9 版本 (#2306)。
• 現在，記錄訊息中使用色彩來識別錯誤、警告和除錯訊息。
• 錯誤修復：當 use_directory_urls 為 False 時識別首頁 (#2362)。

1.1.2 版本 (2020-05-14)

• 錯誤修復：標準化 IP 位址，並將不支援的位址錯誤變更為警告 (#2108)。

1.1.1 版本 (2020-05-12)

• 錯誤修復：透過支援 SOURCE_DATE_EPOCH 環境變數，使壓縮的網站地圖具有確定性 (#2100)。
• 錯誤修復：即使 use_directory_urls 為 false，也將 README.md 用作 index.html (#2081)。
• 錯誤修復：忽略以反斜線開頭的連結 (#1680)。
• 錯誤修復：將 builder 傳遞給 on_serve 事件，以便外掛可以將其傳遞給 server.watch (#1952)。
• 錯誤修復：使用 lunr[languages]==0.5.8 以避免 nltk 不相容問題 (#2062)。
• 錯誤修復：確保 wheel 僅適用於 Python 3 (#2021)。
• 錯誤修復：清理 dev_addr 驗證，並禁止 0.0.0.0 (#2022)。
• 新增對搜尋外掛的 min_search_length 參數的支援 (#2014)。
• 錯誤修復：readthedocs 佈景主題的 code 顏色 (#2027)。

版本 1.1 (2020-02-22)

版本 1.1 的主要新增功能

支援 Lunr.py 作為 prebuild_index 引擎

Mkdocs 現在支援使用 Lunr.py 預先建置索引，它是 Lunr.js 的純 Python 實作，讓使用者可以選擇避免安裝 NodeJS 環境。更多資訊請參閱 prebuild_index 文件。

readthedocs 主題已更新至上游版本 (#588 和 #1374)

readthedocs 主題現在更貼近 上游 Sphinx 主題 (版本 0.4.1)。新增了許多新的主題組態設定，與上游組態選項相對應。詳細資訊請參閱主題文件。

更新 mkdocs 主題至 Bootswatch 4.1.3 (#1563)

mkdocs 主題現在支援 Bootswatch 4.1 的所有功能。此外，本次更新變更了 2 個檔案名稱。如果您使用的主題繼承自 mkdocs 主題，主題開發人員可能需要更新這些檔案名稱，如下所示。

css/bootstrap-custom.min.css => css/bootstrap.min.css
js/bootstrap-3.0.3.min.js => js/bootstrap.min.js

改善命令列上的組態支援 (#1401)

build、serve 和 gh-deploy 子指令現在支援使用旗標來控制是否應該建立目錄 URL：--use-directory-urls / --no-directory-urls。此外，gh-deploy 子指令現在支援 build 和 serve 支援的所有組態選項，新增了 --strict、--theme、--theme-dir 和 --site-dir。

更新 lunr-languages 支援 (#1729)

lunr-languages 外掛程式已更新至 1.4.0，新增了對阿拉伯文 (ar) 和越南文 (vi) 語言的支援。此外，荷蘭文和日文的語言代碼已變更為其標準值：nl 和 ja。舊的語言代碼 (du 和 jp) 仍保留為別名，但可能會在未來版本的 MkDocs 中移除。

版本 1.1 的其他變更和新增功能

• 錯誤修正：確保忽略主題中的巢狀點檔案，並記錄行為 (#1981)。
• 更新最低相依性至 Markdown 3.2.1。
• 更新最低相依性至 Jinja 2.10.1 以解決安全性問題 (#1780)。
• 更新至 lunr.js 2.3.8 (#1989)。
• 新增對 Python 3.8 的支援。
• 停止支援 Python 3.4。
• 停止支援 Python 2.7。MkDocs 現在僅限 PY3 (#1926)。
• 錯誤修正：在 Windows 上為 Python 3.8+ 選擇適當的 asyncio 事件迴圈 (#1885)。
• 錯誤修正：確保巢狀索引頁面不會被識別為首頁 (#1919)。
• 錯誤修正：正確識別部署版本 (#1879)。
• 錯誤修正：為 custom_dir 正確建立 ValidationError 訊息 (#1849)。
• 錯誤修正：從主題中排除 Markdown 檔案和 README (#1766)。
• 錯誤修正：考量編碼過的 URL (#1670)。
• 錯誤修正：確保主題檔案不會覆蓋 docs_dir 檔案 (#1671)。
• 錯誤修正：不正規化 URL 片段 (#1655)。
• 錯誤修正：在 sitemap.xml 中跳過外部 URL (#1742)。
• 錯誤修正：確保主題檔案不會在 Windows 上覆蓋 docs_dir 檔案 (#1876)
• 將 canonical 標籤新增至 readthedocs 主題 (#1669)。
• 改進 git 無法使用時的錯誤訊息。
• 新增對 mkdocs 主題的 nav_style 主題選項的支援 (#1930)。
• 錯誤修正：長/巢狀下拉式選單現在對於 mkdocs 主題的行為更加一致 (#1234)。
• 錯誤修正：mkdocs 主題中的多行導覽標頭不再遮蔽文件內容 (#716)。
• 新增對 mkdocs 主題的 navigation_depth 主題選項的支援 (#1970)。
• page.toc 項目中的 level 屬性現在以 1 為索引，以符合 <hN> 標籤中的層級 (#1970)。

版本 1.0.4 (2018-09-07)

• 錯誤修正：忽略 Markdown 中的絕對連結 (#1621)。

版本 1.0.3 (2018-08-29)

• 錯誤修正：警告導覽中的相對路徑 (#1604)。
• 錯誤修正：正確處理空的 theme_config.yml 檔案 (#1602)。

版本 1.0.2 (2018-08-22)

• 錯誤修正：提供絕對 base_url 給錯誤範本 (#1598)。

版本 1.0.1 (2018-08-13)

• 錯誤修正：防止在搜尋框中按下 [Enter] 時重新載入頁面 (#1589)。
• 錯誤修正：避免在所有資產都準備好之前呼叫 search (#1584)。
• 錯誤修正：如果存在 index.md，則排除 README.md (#1580)。
• 錯誤修正：修正 readthedocs 主題首頁的導覽錯誤 (#1576)。

版本 1.0 (2018-08-03)

版本 1.0 的主要新增功能

頁面、檔案和導覽的內部重構

頁面、檔案和導覽的內部處理已完全重構。重構中包含的變更總結如下。

• 支援隱藏頁面。現在所有 Markdown 頁面都會包含在建置中，無論它們是否包含在導覽組態中 (#699)。
• 導覽現在可以包含外部網站的連結 (#989 #1373 & #1406)。
• 在呈現任何頁面之前，會正確決定所有頁面的頁面資料 (包括標題) (#1347)。
• 自動填入的導覽現在會將索引頁面排序到頂部。換句話說，索引頁面會列為目錄的第一個子項目，而所有其他文件會依檔案名稱字母順序排序在索引頁面之後 (#73 & #1042)。
• README.md 檔案現在會被視為目錄中的索引檔案，並會呈現為 index.html (#608)。
• 所有檔案的 URL 都會計算一次並儲存在檔案集合中。這可確保所有內部連結無論組態如何，都會始終正確計算。這也允許驗證所有內部連結，而不僅僅是其他 Markdown 頁面的連結。(#842 & #872)。
• 新的 url 範本篩選器會智慧地確保所有 URL 都相對於目前頁面 (#1526)。
• 新增了 on_files 外掛程式事件，可用於包含不在 docs_dir 中的檔案、排除檔案、重新定義頁面 URL (例如實作無副檔名 URL)，或以各種其他方式操作檔案。

向後不相容的變更

作為內部重構的一部分，已導入許多向後不相容的變更，總結如下。

當 use_directory_urls 為 False 時，URL 已變更

先前，無論如何組態 use_directory_urls 設定，所有 Markdown 頁面的檔案名稱都會變更為索引頁面。然而，只有在 use_directory_urls 設定為 True (預設值) 時才需要路徑處理。當 use_directory_urls 設定為 False 時，不再進行路徑處理，這會導致所有尚未為索引檔案的頁面產生不同的 URL。由於此行為僅影響非預設組態，且將選項設定為 False 最常見的使用案例是本機檔案系統 (file://) 瀏覽，因此不太可能影響大多數使用者。但是，如果您的 MkDocs 網站在網頁伺服器上託管且將 use_directory_urls 設定為 False，則您的大部分 URL 現在都將損毀。如下所示，新的 URL 更加合理。

請注意，當 use_directory_urls 設定為 True (預設值) 時，URL 或檔案路徑沒有任何變更，除非 MkDocs 更一致地在所有內部產生的 URL 上包含結尾斜線。

pages 配置設定已重新命名為 nav

pages 配置設定已棄用，如果在設定檔中設定，將會發出警告。此設定已重新命名為 nav。若要更新您的設定，只需將設定重新命名為 nav。換句話說，如果您的設定看起來像這樣：

pages:
  - Home: index.md
  - User Guide: user-guide.md

只需如下編輯設定：

nav:
  - Home: index.md
  - User Guide: user-guide.md

在目前版本中，任何包含 pages 設定但沒有 nav 設定的配置，pages 設定將會複製到 nav，並發出警告。但是，在未來的版本中，可能不再會發生這種情況。如果同時定義了 pages 和 nav，則會忽略 pages 設定。

樣板變數和 base_url

在之前的 MkDocs 版本中，某些 URL 預期 base_url 樣板變數會被加在 URL 的開頭，而其他的則不會。這種不一致性已移除，現在任何 URL 在被添加到樣板內容之前都不會被修改。

例如，一個主題樣板可能之前包含了到 site_name 的連結，如下所示：

<a href="{{ nav.homepage.url }}">{{ config.site_name }}</a>

而 MkDocs 會神奇地回傳一個相對於目前頁面的首頁 URL。這種「神奇」的功能已移除，應該使用 url 樣板篩選器：

<a href="{{ nav.homepage.url|url }}">{{ config.site_name }}</a>

這個變更適用於任何導覽項目和頁面，以及 page.next_page 和 page.previous_page 屬性。目前，extra_javascript 和 extra_css 變數仍然像以前一樣工作（沒有使用 url 樣板篩選器），但它們已被棄用，應該改用對應的配置值（分別是 config.extra_javascript 和 config.extra_css）並搭配篩選器使用。

{% for path in config.extra_css %}
    <link href="{{ path|url }}" rel="stylesheet">
{% endfor %}

請注意，導覽現在可以包含指向外部網站的連結。顯然，不應該將 base_url 加在這些項目的開頭。但是，url 樣板篩選器夠聰明，可以識別 URL 是絕對路徑，而不會修改它。因此，所有導覽項目都可以傳遞到篩選器，只有那些需要修改的才會被修改。

{% for nav_item in nav %}
    <a href="{{ nav_item.url|url }}">{{ nav_item.title }}</a>
{% endfor %}

路徑相關設定會相對於設定檔 (#543)

先前，各種配置選項中的任何相對路徑都是相對於目前的工作目錄解析。現在它們會相對於設定檔解析。由於文件一直鼓勵從包含設定檔（專案根目錄）的目錄中執行各種 MkDocs 指令，因此這個變更不會影響大多數使用者。但是，它會讓實現自動化建置或從專案根目錄以外的位置執行指令變得更加容易。

只需使用 -f/--config-file 選項並將其指向設定檔即可：

mkdocs build --config-file /path/to/my/config/file.yml

與先前一樣，如果沒有指定檔案，MkDocs 會在目前工作目錄中尋找名為 mkdocs.yml 的檔案。

新增對 YAML 元資料的支援 (#1542)

先前，MkDocs 只支援 MultiMarkdown 風格的元資料，該風格無法識別不同的資料類型，而且相當有限。MkDocs 現在也支援 Markdown 文件中的 YAML 風格元資料。MkDocs 依賴分隔符號（--- 或 ...）的存在與否來判斷是否正在使用 YAML 風格元資料或 MultiMarkdown 風格元資料。

先前，MkDocs 會識別分隔符號之間的 MultiMarkdown 風格元資料。現在，如果偵測到分隔符號，但分隔符號之間的內容不是有效的 YAML 元資料，MkDocs 不會嘗試將該內容解析為 MultiMarkdown 風格元資料。因此，MultiMarkdown 風格的元資料不得包含分隔符號。請參閱 MultiMarkdown 風格元資料文件 以取得詳細資訊。

在 0.17 版本之前，MkDocs 會將所有元資料值回傳為字串列表（即使是單行也會回傳一個包含一個字串的列表）。在 0.17 版本中，該行為已變更為將每個值回傳為單一字串（多行會被合併），一些使用者覺得這種方式限制了功能（請參閱 #1471）。在目前版本中，MultiMarkdown 風格的元資料仍然維持這種行為。但是，YAML 風格的元資料支援完整的「安全」YAML 資料類型範圍。因此，建議任何複雜的元資料都使用 YAML 風格（請參閱 YAML 風格元資料文件 以取得詳細資訊）。事實上，未來版本的 MkDocs 可能會棄用對 MultiMarkdown 風格元資料的支援。

重構搜尋外掛程式

搜尋外掛程式已完全重構，以包含對以下功能的支援：

• 在瀏覽器中使用 Web Worker 並提供回退機制 (#1396)。
• 可選擇在本地預先建置搜尋索引 (#859 & #1061)。
• 升級至 lunr.js 2.x (#1319)。
• 支援非英語語言的搜尋 (#826)。
• 允許使用者定義單字分隔符號 (#867)。
• 只執行長度 > 2 的查詢搜尋 (#1127)。
• 移除對 require.js 的依賴 (#1218)。
• 壓縮搜尋索引 (#1128)。

使用者可以查看可用的配置選項，而主題作者應檢閱搜尋與主題如何互動。

theme_dir 配置選項已完全棄用

從 0.17 版本開始，custom_dir 選項取代了已棄用的 theme_dir 選項。如果使用者設定了 theme_dir 選項，MkDocs 0.17 版本會將該值複製到 theme.custom_dir 選項並發出警告。從 1.0 版本開始，該值不再被複製，並且會引發錯誤。

1.0 版本的其他變更和新增功能

• 鍵盤快捷鍵已變更為不與常用的輔助功能快捷鍵衝突 (#1502)。
• 更友善的 YAML 解析錯誤訊息 (#1543)。
• 正式支援 Python 3.7。
• 遺失的主題設定檔現在會引發錯誤。
• 空的 extra_css 和 extra_javascript 設定不再引發警告。
• 將 highlight.js 設定選項新增至內建主題 (#1284)。
• 當選擇結果時關閉搜尋模態視窗 (#1527)。
• 將 level 屬性新增至 AnchorLinks (#1272)。
• 將 MkDocs 版本檢查新增至 gh-deploy 腳本 (#640)。
• 改進 Markdown 擴充功能的錯誤訊息。 (#782)。
• 放棄對 Python 3.3 的正式支援，並設定 tornado>=5.0 (#1427)。
• 新增對 GitLab 編輯連結的支援 (#1435)。
• 從版本說明連結到 GitHub issues (#644)。
• 展開 gh-deploy commit 訊息中的 {sha} 和 {version} (#1410)。
• 壓縮 sitemap.xml (#1130)。
• 延遲載入 JS 腳本 (#1380)。
• 將 title 屬性新增至搜尋輸入框 (#1379)。
• 將 RespondJS 更新至最新版本 (#1398)。
• 始終透過 HTTPS 載入 Google Analytics (#1397)。
• 提高捲動幀率 (#1394)。
• 提供更多版本資訊。 (#1393)。
• 重構 writing-your-docs.md (#1392)。
• 解決縮放至 < 100% 時 Safari 的錯誤 (#1389)。
• 移除在 body 和動畫上新增 clicky class。 (#1387)。
• 防止搜尋外掛程式重新注入 extra_javascript 檔案 (#1388)。
• 重構 copy_media_files 工具函式以提高彈性 (#1370)。
• 移除 PyPI 部署文件 (#1360)。
• 更新 Python-Markdown 函式庫的連結 (#1360)。
• 說明如何為 MkDocs 命令產生 manpage (#686)。

版本 0.17.5 (2018-07-06)

• 錯誤修正：修復 Python 3.7 和 PEP 479 的不相容問題 (#1518)。

版本 0.17.4 (2018-06-08)

• 錯誤修正：在 sitemap.xml 中加入多層巢狀結構的支援 (#1482)。

版本 0.17.3 (2018-03-07)

• 錯誤修正：由於 5.0 的變更，將相依性 tornado>=4.1,<5.0 設定為 (#1428)。

版本 0.17.2 (2017-11-15)

• 錯誤修正：修正 extra_* 設定回歸問題 (#1335 & #1336)。

版本 0.17.1 (2017-10-30)

• 錯誤修正：支援缺少結尾斜線的 repo_url。( #1321)。
• 錯誤修正：在 mkdocs.toc.TableOfContext 中加入長度支援 (#1325)。
• 錯誤修正：為第三方佈景主題的搜尋外掛程式加入一些佈景主題特定的設定 (#1316)。
• 錯誤修正：在本機伺服器上使用 dev_addr 覆蓋 site_url (#1317)。

版本 0.17.0 (2017-10-19)

版本 0.17.0 的主要新增功能

外掛程式 API。 (#206)

MkDocs 已新增一個新的 外掛程式 API，讓使用者可以定義自己的自訂行為。請參閱隨附的文件以取得 API 的完整說明。

先前內建的搜尋功能已移除並包裝在一個外掛程式（名為「search」）中，行為沒有任何變更。當 MkDocs 建置時，搜尋索引現在會寫入 search/search_index.json，而不是 mkdocs/search_index.json。如果設定中未定義任何外掛程式，則預設會包含 search 外掛程式。請參閱設定文件以取得覆寫預設值的相關資訊。

佈景主題自訂。 (#1164)

已加入支援以提供佈景主題特定的自訂功能。佈景主題作者可以定義預設選項，如佈景主題設定中所述。佈景主題現在可以繼承自另一個佈景主題，定義要呈現的各種靜態範本，並定義任意預設變數來控制範本中的行為。佈景主題設定定義在名為 mkdocs_theme.yml 的設定檔中，該檔案應放在範本檔案的根目錄。如果找不到設定檔，則會發出警告，並且在未來的版本中會引發錯誤。

使用者可以在其 mkdocs.yml 設定檔的 theme 設定選項下覆寫這些預設值，該設定選項現在接受巢狀選項。其中一個巢狀選項是 custom_dir 選項，它取代了現在已淘汰的 theme_dir 選項。如果使用者先前已設定 theme_dir 選項，則會發出警告，並且在未來的版本中會預期出現錯誤。

如果設定先前定義了像這樣的 theme_dir

theme: mkdocs
theme_dir: custom

那麼應該如下調整設定

theme:
  name: mkdocs
  custom_dir: custom

請參閱theme設定選項文件以取得詳細資訊。

先前已淘汰的範本變數已移除。( #1168)

頁面範本

頁面範本的主要進入點已從 base.html 變更為 main.html。這允許 base.html 繼續存在，同時允許使用者覆寫 main.html 並延伸 base.html。對於 0.16 版，如果不存在 main.html 範本，則 base.html 會繼續運作，但會發出淘汰警告。在 1.0 版中，如果不存在 main.html 範本，建置將會失敗。

內容變數

範本內容中的頁面特定變數名稱已重新架構，如自訂佈景主題中所定義。舊的變數名稱在 0.16 版中發出了警告，但在 1.0 版中已移除。

任何下列舊頁面變數都應該更新為使用者建立和第三方範本中的新變數

此外，許多全域變數已變更和/或移除，使用者建立和第三方範本應更新如下

自動填入的 extra_css 和 extra_javascript 已完全淘汰。( #986)

在先前版本的 MkDocs 中，如果 extra_css 或 extra_javascript 設定為空，MkDocs 會掃描 docs_dir 並自動填入每個設定中找到的所有 CSS 和 JavaScript 檔案。在 0.16 版中，此行為已淘汰，並發出警告。在 0.17 中，任何未列出的 CSS 和 JavaScript 檔案將不會包含在 HTML 範本中，但會發出警告。換句話說，它們仍然會複製到 site-dir，但如果它們未明確列出，則不會對佈景主題產生任何影響。

docs_dir 中的所有 CSS 和 JavaScript 檔案都應該明確列在 extra_css 或 extra_javascript 設定中。

版本 0.17.0 的其他變更和新增功能

• 為 MkDocs 佈景主題加入「編輯連結」支援 (#1129)
• 以 utf-8-sig 開啟檔案以考慮 BOM (#1186)
• 現在會一致地追蹤符號連結 (#1134)
• 已為包含的佈景主題加入了鍵盤導覽快速鍵的支援 (#1095)
• 對 config_options 進行了一些重構和改進 (#1296)
• 正式加入了 Python 3.6 的支援 (#1296)
• 已在 readthedocs 佈景主題中加入 404 錯誤頁面 (#1296))
• Markdown 處理的內部重構 (#713)
• 已移除 mkdocs-bootstrap 和 mkdocs-bootswatch 佈景主題的特殊錯誤訊息 (#1168)
• 不再支援舊版頁面設定 (#1168)
• 已移除已淘汰的 json 命令 (#481)
• 已取消對 Python 2.6 的支援 (#165)
• 建置期間不再複製檔案權限 (#1292)
• 在 edit_uri 中支援查詢和片段字串 (#1224 & #1273)

版本 0.16.3 (2017-04-04)

• 修正 readthedocs 佈景主題中自動捲動引發的錯誤 (#1177)
• 修正了一些文件中的錯字 (#1181 & #1185)
• 修正 0.16.2 版本中引入的 livereload 伺服器回歸問題 (#1174)

版本 0.16.2 (2017-03-13)

• 系統根目錄 (/) 不是 site_dir 或 docs_dir 的有效路徑 (#1161)
• 重構 readthedocs 主題導覽 (#1155 & #1156)
• 新增開發伺服器支援以提供自訂錯誤頁面 (#1040)
• 確保錯誤頁面上 nav.homepage.url 不為空白 (#1131)
• 將 livereload 相依性增加到 2.5.1 (#1106)

版本 0.16.1 (2016-12-22)

• 確保 scrollspy 行為不會影響導覽列 (#1094)
• 僅在使用者明確請求時「載入」主題 (#1105)

版本 0.16 (2016-11-04)

0.16.0 版本的主要新增功能

範本變數已重構。 (#874)

頁面上下文

範本上下文中特定頁面的變數名稱已依照自訂主題中的定義重構。舊的變數名稱將會發出警告，但在 0.16 版本中仍可繼續使用，但在未來版本中可能會移除。

任何下列舊頁面變數都應該更新為使用者建立和第三方範本中的新變數

全域上下文

此外，許多全域變數已變更和/或已棄用，使用者建立的範本和第三方範本應按照以下概述進行更新

先前，全域變數 include_nav 會根據導覽中的頁面數量以程式方式變更。該變數將會發出警告，但在 0.16 版本中仍可繼續使用，但在未來版本中可能會移除。請改用 {% if nav|length>1 %}。

先前，全域變數 include_next_prev 會根據導覽中的頁面數量以程式方式變更。該變數將會發出警告，但在 0.16 版本中仍可繼續使用，但在未來版本中可能會移除。請改用 {% if page.next_page or page.previous_page %}。

先前，全域變數 page_description 會根據目前頁面是否為主頁以程式方式變更。現在它只會對應到 config['site_description']。請在範本中使用 {% if page.is_homepage %} 以條件式地變更描述。

全域變數 homepage_url 直接對應到 nav.homepage.url 且已被棄用。該變數將會發出警告，但在 0.16 版本中仍可繼續使用，但在未來版本中可能會移除。請改用 nav.homepage.url。

全域變數 favicon 對應到組態設定 site_favicon。範本變數和組態設定都已被棄用，且會發出警告，但在 0.16 版本中仍可繼續使用，並可能在未來版本中移除。請在您的範本中使用 {{ base_url }}/img/favicon.ico。使用者可以簡單地將他們的自訂網站圖示複製到其 docs_dir 或 theme_dir 中的 img/favicon.ico。

許多變數直接對應到 config 中名稱相似的變數。這些變數已被棄用，且會發出警告，但在 0.16 版本中仍可繼續使用，但在未來版本中可能會移除。請改用 config.var_name，其中 var_name 是組態變數的名稱之一。

以下是針對全域上下文所做的所有變更摘要

增強的範本自訂功能。 (#607)

內建主題已更新，將其許多部分包裝在範本區塊中，讓每個單獨的區塊都可以使用 theme_dir 組態設定輕鬆覆寫。無需任何新設定，您可以使用不同的分析服務、取代預設搜尋功能或變更導覽的行為等等。如需更多詳細資訊，請參閱相關的文件。

為了啟用此功能，頁面範本的主要進入點已從 base.html 變更為 main.html。這讓 base.html 可以繼續存在，同時允許使用者覆寫 main.html 並擴展 base.html。對於 0.16 版本，如果不存在 main.html 範本，則 base.html 將會繼續運作，但它已被棄用並將發出警告。在 1.0 版本中，如果不存在 main.html 範本，則組建會失敗。任何自訂和第三方範本都應進行相應的更新。

更新第三方主題的最簡單方法是簡單地新增一個僅包含以下行的 main.html 檔案

{% extends "base.html" %}

如此一來，主題包含 main.html 進入點，並支援以與內建主題相同的方式覆寫區塊。鼓勵第三方主題將其範本的各個部分包裝在區塊中，以支援此類自訂。

自動填入的 extra_css 和 extra_javascript 已棄用。 (#986)

在先前版本的 MkDocs 中，如果 extra_css 或 extra_javascript 組態設定為空，則 MkDocs 會掃描 docs_dir 並使用找到的所有 CSS 和 JavaScript 檔案自動填入每個設定。此行為已棄用，並會發出警告。在下一個版本中，自動填入功能將停止運作，並且任何未列出的 CSS 和 JavaScript 檔案將不會包含在 HTML 範本中。換句話說，它們仍會複製到 site-dir，但如果未明確列出，它們將不會對主題產生任何影響。

docs_dir 中的所有 CSS 和 JavaScript 檔案都應該明確列在 extra_css 或 extra_javascript 設定中。

支援髒組建。 (#990)

對於大型網站，建立頁面所需的組建時間可能會成為問題，因此建立了「髒」組建模式。此模式只是比較產生的 HTML 和來源 markdown 的修改時間。如果 markdown 自 HTML 之後已變更，則會重新建構頁面。否則，頁面會保持不變。此模式可以在 mkdocs serve 和 mkdocs build 命令中調用

mkdocs serve --dirtyreload

mkdocs build --dirty

請務必注意，此方法用於組建頁面僅用於內容的開發，因為導覽和其他連結不會在其他頁面上更新。

更嚴格的目錄驗證

先前，如果 site_dir 是 docs_dir 的子目錄，則會發出警告。現在會引發錯誤。此外，如果 docs_dir 設定為包含您的組態檔案的目錄而不是子目錄，現在也會引發錯誤。您需要重新排列您的目錄結構，以更好地符合記錄的版面配置。

0.16.0 版本的其他變更和新增功能

• 錯誤修復：支援 Windows 上使用 Python 3 的 gh-deploy 命令 (#722)
• 錯誤修復：將 .woff2 字型檔案包含在 Python 套件組建中 (#894)
• 對文件首頁/教學課程的各種更新和改進 (#870)
• 錯誤修復：支援組態檔案變更的 livereload (#735)
• 錯誤修復：非媒體範本檔案不再與媒體檔案一起複製 (#807)
• 新增一個標誌 (-e/--theme-dir) 以使用命令 mkdocs build 和 mkdocs serve 指定主題目錄 (#832)
• 修正 Windows 和 Python 2 下的 Unicode 檔案名稱問題。 (#833)
• 改進 MkDocs 主題中內嵌程式碼的樣式。 (#718)
• 錯誤修復：將變數轉換為 JSON 以在傳遞至 JavaScript 時使用 (#850)
• 更新 ReadTheDocs 主題，使其更接近上游的字型大小和顏色。 (#857)
• 修正當滑鼠遠高於它們時，永久連結標記顯示的問題 (#843)
• 錯誤修復：在自動建立頁面組態時處理目錄名稱中的句點。 (#728)
• 將搜尋更新為 Lunr 0.7，它為較大的文件提供了一些效能增強功能 (#859)
• 錯誤修復：支援「可重現」組建的 SOURCE_DATE_EPOCH 環境變數 (#938)
• 複製媒體檔案時追蹤連結 (#869)。
• 將「編輯於...」連結變更為直接指向來源儲存庫中的檔案，而不是指向儲存庫的根目錄 (#975)，可透過新的edit_uri設定進行組態。
• 錯誤修復：如果未在 CLI 上指定，則不要覆寫嚴格模式的組態值 (#738)。
• 為 gh-deploy 命令新增一個 --force 標誌，以強制推送至儲存庫 (#973)。
• 改進 readthedocs 主題中目前選定選單項目的對齊方式 (#888)。
• http://user.github.io/repo => https://user.github.io/repo/ (#1029)。
• 改進安裝說明 (#1028)。
• 考慮寬表格並一致地包裝內嵌程式碼範圍 (#834)。
• 錯誤修復：在錯誤範本中使用導覽和媒體連結的絕對 URL (#77)。

版本 0.15.3 (2016-02-18)

• 改進找不到指定主題時的錯誤訊息。
• 修正相對符號連結的問題 (#639)

版本 0.15.2 (2016-02-08)

• 修正一則錯誤的警告，該警告聲稱外部佈景主題將從 MkDocs 中移除。

版本 0.15.1 (2016-01-30)

• 將套件維護者的最低支援 Click 版本降至 3.3。(#763)

版本 0.15.0 (2016-01-21)

版本 0.15.0 的主要新增功能

新增對可安裝佈景主題的支援

MkDocs 現在支援透過 Python 套件發佈的佈景主題。新增此功能後，Bootstrap 和 Bootswatch 佈景主題已移至外部 git 儲存庫和 python 套件。有關這些特定佈景主題的更多詳細資訊，請參閱它們各自的文件。

• MkDocs Bootstrap
• MkDocs Bootswatch

它們將預設包含在 MkDocs 中，直到未來版本。之後，它們將可透過 pip 安裝：pip install mkdocs-bootstrap 和 pip install mkdocs-bootswatch

有關使用和自訂佈景主題的更多資訊，請參閱自訂佈景主題的文件，以及有關建立和發佈新佈景主題的自訂佈景主題文件

版本 0.15.0 的其他變更和新增功能

• 修正使用 Markdown 檔案的絕對連結時發生的問題。(#628)
• 不建議使用 Python 2.6 的支援，預計在 1.0.0 中移除。(#165)
• 新增對 Python 版本 3.5 的官方支援。
• 為 site_description 和 site_author 新增對 ReadTheDocs 佈景主題的官方支援。(#631)
• 將 FontAwesome 更新至 4.5.0。(#789)
• 透過 X-UA-Compatible 增加對 IE 的支援。(#785)
• 新增對 Python 的 -m 標記的支援。(#706)
• 錯誤修正：確保自動產生的頁面順序一致。(#638)
• 錯誤修正：如果頁面的目錄太長，請在 MkDocs 佈景主題上捲動目錄。(#204)
• 錯誤修正：將所有祖先新增至頁面屬性 ancestors，而不僅僅是初始祖先。(#693)
• 錯誤修正：再次在建置輸出中包含 HTML。(#691)
• 錯誤修正：為 Read the Docs 提供檔案名稱。(#721 和 RTD#1480)
• 錯誤修正：消除 Click 的 unicode_literals 警告。(#708)

版本 0.14.0 (2015-06-09)

• 透過確保所有組態字串都以 Unicode 載入，來改善 Unicode 處理。(#592)
• 移除對 six 程式庫的依賴。(#583)
• 移除對 ghp-import 程式庫的依賴。(#547)
• 為所有子命令新增 --quiet 和 --verbose 選項。(#579)
• 為大多數命令列選項新增簡短選項 (-a)。(#579)
• 為 readthedocs 佈景主題新增版權頁尾。(#568)
• 如果 mkdocs serve 中要求的連接埠已在使用中，請不要向使用者顯示完整的堆疊追蹤。(#596)
• 錯誤修正：修正使用空格搜尋時發生的 JavaScript 編碼問題。(#586)
• 錯誤修正：如果 mkdocs.yml 不在 git 儲存庫的根目錄中，gh-deploy 現在可以運作。(#578)
• 錯誤修正：在剖析 TOC 時處理 (傳遞而非捨棄) HTML 實體。(#612)
• 錯誤修正：將 extra_templates 預設為空清單，不要自動探索它們。(#616)

版本 0.13.3 (2015-06-02)

• 錯誤修正：如果 site_dir 在 docs_dir 中，則將驗證錯誤減少為警告，因為這不會對建置造成任何問題，但會讓多次建置的使用者感到不便。(#580)

版本 0.13.2 (2015-05-30)

• 錯誤修正：確保在結束之前記錄所有錯誤和警告。(#536)
• 錯誤修正：修正與 ReadTheDocs 的相容性問題。(#554)

版本 0.13.1 (2015-05-27)

• 錯誤修正：修正僅在頁面組態中包含路徑清單的最小組態問題。(#562)

版本 0.13.0 (2015-05-26)

版本 0.13.0 的棄用項目

不建議使用 JSON 命令

在此版本中，mkdocs json 命令已標示為不建議使用，且在使用時會顯示棄用警告。它將在 MkDocs 的未來版本中移除，最晚將於 1.0 版移除。mkdocs json 命令為使用者提供了一種方便的方式，可將文件內容輸出為 JSON 檔案，但隨著將搜尋功能新增至 MkDocs，此功能已重複。

在 site_dir 中建立一個包含 MkDocs 建置所有內容的新索引，因此使用 site_dir 的預設值，可以在 site/mkdocs/search_index.json 中找到它。

此新檔案會在每次 MkDocs 建置時建立 (使用 mkdocs build)，且不需要組態即可啟用它。

變更頁面組態

提供一種新方式來在 mkdocs.yml 檔案中定義頁面，特別是巢狀頁面，並棄用現有方法，MkDocs 1.0 將移除支援。

警告使用者將移除內建佈景主題

除了 mkdocs 和 readthedocs 之外的所有佈景主題都將移至 MkDocs 未來版本中的外部套件。這將使它們能夠在 MkDocs 版本之外更容易地獲得支援和更新。

版本 0.13.0 的主要新增功能

搜尋

現在已將搜尋支援新增至 MkDocs。這基於 JavaScript 程式庫 lunr.js。它已新增至 mkdocs 和 readthedocs 佈景主題。有關將其新增至您自己的佈景主題，請參閱支援搜尋的自訂佈景主題文件。

新的命令列介面

MkDocs 的命令列介面已使用 Python 程式庫 Click 重新編寫。這表示 MkDocs 現在具有更容易使用的介面和更好的說明輸出。

此變更部分不向後相容，因為雖然未記錄，但可以將任何組態選項傳遞至不同的命令。現在只有一小部分的組態選項可以傳遞至命令。若要查看完整的命令和可用引數，請使用 mkdocs --help 和 mkdocs build --help 來顯示它們。

支援額外的 HTML 和 XML 檔案

類似於 extra_javascript 和 extra_css 組態選項，新增了一個名為 extra_templates 的新選項。這將自動填入專案文件目錄中的任何 .html 或 .xml 檔案。

使用者可以放置靜態 HTML 和 XML 檔案，它們將被複製過來，或者它們也可以使用 Jinja2 語法並利用全域變數。

預設情況下，MkDocs 將使用此方法為文件建立網站地圖。

版本 0.13.0 的其他變更和新增功能

• 新增對 Markdown 擴充功能組態選項的支援。(#435)
• MkDocs 現在發佈 Python wheels。(#486)
• 僅在首頁上包含建置日期和 MkDocs 版本。(#490)
• 為文件建置產生網站地圖。(#436)
• 新增一種在組態中定義巢狀頁面更清晰的方式。(#482)
• 新增 額外組態選項，用於將任意變數傳遞至範本。(#510)
• 為 mkdocs serve 新增 --no-livereload 以獲得更簡單的開發伺服器。(#511)
• 為所有佈景主題新增版權顯示支援 (#549)
• 在 mkdocs gh-deploy 中新增對自訂提交訊息的支援 (#516)
• 錯誤修復：修正連結到與名為 index.md 的 Markdown 檔案位於同一目錄中的媒體檔案的問題 ( #535 )
• 錯誤修復：修正 Unicode 檔名造成的錯誤 ( #542 )。

版本 0.12.2 (2015-04-22)

• 錯誤修復：修正當頁面設定中，某些子標題遺失但其他子標題存在時會發生錯誤的回歸問題 ( #464 )。

版本 0.12.1 (2015-04-14)

• 錯誤修復：修正某些瀏覽器上目錄中的 CSS 錯誤，該錯誤會導致底部項目無法點擊。

版本 0.12.0 (2015-04-14)

• 在 CLI 輸出中顯示目前的 MkDocs 版本 ( #258 )。
• 使用 gh-deploy 時檢查 CNAME 檔案 ( #285 )。
• 將首頁重新加入所有主題的導覽中 ( #271 )。
• 為本地連結檢查新增嚴格模式 ( #279 )。
• 為所有主題新增 Google Analytics 支援 ( #333 )。
• 將建置日期和 MkDocs 版本新增至 ReadTheDocs 和 MkDocs 主題輸出 ( #382 )。
• 將所有主題的程式碼高亮顯示標準化，並新增遺失的語言 ( #387 )。
• 新增詳細模式標誌 (-v) 來顯示有關建置的更多詳細資訊 ( #147 )。
• 新增在部署到 GitHub 時指定遠端分支的選項。這允許部署到個人和儲存庫站點上的 GitHub Pages ( #354 )。
• 為 ReadTheDocs 主題 HTML 新增 favicon 支援 ( #422 )。
• 當檔案被編輯時自動重新整理瀏覽器 ( #163 )。
• 錯誤修復：永遠不要在程式碼區塊中重寫 URL ( #240 )。
• 錯誤修復：從 docs_dir 複製媒體時，不要複製點開頭的檔案 ( #254 )。
• 錯誤修復：修正 ReadTheDocs 主題中表格的渲染問題 ( #106 )。
• 錯誤修復：在所有 Bootstrap 主題的底部新增內距 (padding) ( #255 )。
• 錯誤修復：修正巢狀 Markdown 頁面和自動頁面設定的問題 ( #276 )。
• 錯誤修復：修正 GitHub Enterprise 的 URL 解析錯誤 ( #284 )。
• 錯誤修復：如果 mkdocs.yml 完全為空，則不要發生錯誤 ( #288 )。
• 錯誤修復：修正相對 URL 和 Markdown 檔案的許多問題 ( #292 )。
• 錯誤修復：如果找不到頁面，請不要停止建置，繼續處理其他頁面 ( #150 )。
• 錯誤修復：從頁面標題中移除 site_name，這需要手動新增 ( #299 )。
• 錯誤修復：修正目錄截斷 Markdown 的問題 ( #294 )。
• 錯誤修復：修正 BitBucket 的主機名稱 ( #339 )。
• 錯誤修復：確保所有連結都以斜線結尾 ( #344 )。
• 錯誤修復：修正 readthedocs 主題中的儲存庫連結 ( #365 )。
• 錯誤修復：在本機包含 jQuery，以避免離線使用 MkDocs 時發生問題 ( #143 )。
• 錯誤修復：不允許 docs_dir 位於 site_dir 中，反之亦然 ( #384 )。
• 錯誤修復：移除 ReadTheDocs 主題中的內嵌 CSS ( #393 )。
• 錯誤修復：修正由於處理頁面設定的順序而導致的子標題問題 ( #395 )。
• 錯誤修復：當主題不存在時，不要在即時重新載入期間發生錯誤 ( #373 )。
• 錯誤修復：修正在 Meta 擴充功能可能不存在時發生的問題 ( #398 )。
• 錯誤修復：包裝長行內程式碼，否則它們會跑出螢幕 ( #313 )。
• 錯誤修復：移除 HTML 解析正規表達式，並使用 HTMLParser 進行解析，以修正包含程式碼的標題的問題 ( #367 )。
• 錯誤修復：修正滾動到錨點時，導致標題隱藏在導覽底下的問題 ( #7 )。
• 錯誤修復：為 Bootswatch 主題中的 HTML 表格新增更好的 CSS 類別 ( #295 )。
• 錯誤修復：修正使用 mkdocs serve 傳入特定設定檔時發生的錯誤 ( #341 )。
• 錯誤修復：不要使用 mkdocs new 命令覆寫 index.md 檔案 ( #412 )。
• 錯誤修復：從 ReadTheDocs 主題中的程式碼移除粗體和斜體 ( #411 )。
• 錯誤修復：在 MkDocs 主題中以行內方式顯示圖片 ( #415 )。
• 錯誤修復：修正 ReadTheDocs 主題中 no-highlight 的問題 ( #319 )。
• 錯誤修復：使用 mkdocs build --clean 時，不要刪除隱藏檔案 ( #346 )。
• 錯誤修復：不要在 Python >= 2.7 上阻止較新版本的 Python-markdown ( #376 )。
• 錯誤修復：修正跨平台開啟檔案時的編碼問題 ( #428 )。

版本 0.11.1 (2014-11-20)

• 錯誤修復：修正 ReadTheDocs 主題中程式碼高亮顯示的 CSS 包裝問題 ( #233 )。

版本 0.11.0 (2014-11-18)

• 如果目前主題存在 404.html 檔案，則渲染該檔案 ( #194 )。
• 錯誤修復：修正 MkDocs 和 ReadTheDocs 主題中的長導覽列、表格渲染和程式碼高亮顯示問題 ( #225 )。
• 錯誤修復：修正 google_analytics 程式碼的問題 ( #219 )。
• 錯誤修復：從套件 tar 中移除 __pycache__ ( #196 )。
• 錯誤修復：修復指向目前頁面上錨點的 Markdown 連結 ( #197 )。
• 錯誤修復：不要將 prettyprint well CSS 類別新增至所有 HTML，只在 MkDocs 主題中新增 ( #183 )。
• 錯誤修復：在 ReadTheDocs 主題中顯示章節標題 ( #175 )。
• 錯誤修復：在 watchdog 中使用輪詢觀察器，以便在沒有 inotify 的檔案系統上正常重新建置 ( #184 )。
• 錯誤修復：改進常見設定相關錯誤的錯誤輸出 ( #176 )。

版本 0.10.0 (2014-10-29)

• 新增 Python 3.3 和 3.4 的支援 ( #103 )。
• 使用設定值 markdown_extensions 設定 Python-Markdown 擴充功能 ( #74 )。
• 新增 mkdocs json 命令，將您渲染的說明文件輸出為 JSON 檔案 ( #128 )。
• 為 build、json 和 gh-deploy 命令新增 --clean 開關，以從輸出目錄中移除過期的檔案 ( #157 )。
• 支援多個主題目錄，以允許替換個別範本，而無需複製完整主題 ( #129 )。
• 錯誤修復：修正 readthedocs 主題中的 <ul> 渲染問題 ( #171 )。
• 錯誤修復：改進較小顯示器上的 readthedocs 主題 ( #168 )。
• 錯誤修復：放寬所需的 Python 套件版本，以避免衝突 ( #104 )。
• 錯誤修復：修正某些設定下目錄的渲染問題 ( #146 )。
• 錯誤修復：修正子頁面中嵌入圖片的路徑 ( #138 )。
• 錯誤修復：修正 use_directory_urls 設定的行為 ( #63 )。
• 錯誤修正：支援所有主題中的 extra_javascript 和 extra_css。（#90）
• 錯誤修正：修正 Windows 下的路徑處理。（#121）
• 錯誤修正：修正 readthedocs 主題中的選單生成。（#110）
• 錯誤修正：修正 Windows 下的 mkdocs 命令建立。（#122）
• 錯誤修正：正確處理外部的 extra_javascript 和 extra_css。（#92）
• 錯誤修正：修正 favicon 支援。（#87）