參與 MkDocs 貢獻

參與 MkDocs 專案貢獻簡介。

MkDocs 專案歡迎開源社群中的開發人員和使用者參與貢獻。參與貢獻的方式有很多，以下是一些範例

• 透過 pull requests 的程式碼修補程式
• 文件改善
• 錯誤報告和修補程式檢閱

有關可用的溝通管道，請參閱 GitHub 儲存庫中的 README 檔案。

回報問題

請盡可能提供詳細資料。讓我們知道您的平台和 MkDocs 版本。如果問題是視覺上的（例如佈景主題或設計問題），請加入螢幕截圖。如果您遇到錯誤，請附上完整的錯誤訊息和追溯資料。

如果問題回報涵蓋以下所有面向，將特別有幫助

1. 您試圖達成什麼目標？

2. 您的 mkdocs.yml 組態是什麼（+ 其他相關檔案）？最好簡化成最小的重現範例。

3. 您預期套用此設定將會發生什麼事？

4. 實際發生了什麼事，以及與您的預期有何不同？

嘗試開發版本

如果您只想安裝並嘗試 MkDocs 的最新開發版本（如果裡面已經有問題的修正），您可以使用以下指令來執行。如果您想提供新功能的回饋，或確認您遇到的錯誤已在 git 的 master 中修正，這會很有幫助。強烈建議您在 虛擬環境 中執行這個動作。

pip install git+https://github.com/mkdocs/mkdocs.git

安裝進行開發

請注意，對於開發，您可以像以下描述一樣直接使用 Hatch。如果您還是想要安裝 MkDocs 的本機複製，您可以執行 pip install --editable .。強烈建議您在 虛擬環境 中執行這個動作。

安裝 Hatch

作為開發主要使用的工具是 Hatch。它可以管理相關性（在動態建立的虛擬環境中），同時也是指令執行器。

所以首先，安裝它。理想的做法是以獨立的方式透過 pipx install hatch（在安裝 pipx 之後），或以更廣為人知的方式僅執行 pip install hatch。

執行所有檢查

要執行 MkDocs 所需的所有檢查，請直接在所複製的 MkDocs 儲存庫中執行下列命令

hatch run all

這涵蓋以下所述的檢查。

所有檢查都必須通過。

執行測試

要執行 MkDocs 的測試套件，請執行下列命令

hatch run test:test
hatch run integration:test

系統會嘗試對我們支援的所有 Python 版本執行測試。所以如果你遺漏某些版本，無需擔心。GitHub Actions 會在你提交プルリク時驗證其餘版本。

Python 編碼風格

MkDocs 程式碼庫內的 Python 程式碼使用 Black 和 Isort 進行格式化，並使用 Ruff 進行提示檢查，這些設定全都在 pyproject.toml 中。

你可以使用下列命令來根據這些工具自動檢查和格式化程式碼。

hatch run style:fix

程式碼也會使用 mypy 進行類型檢查，該設定也納入 pyproject.toml，可以用下列方式執行

hatch run types:check

其他風格檢查

還有其他數個檢查，例如拼字和 JS 風格。要執行這些檢查，請使用這個命令

hatch run lint:check

MkDocs 本身的說明文件

對 docs/ 目錄下的檔案進行編輯後，你可以使用下列命令來在本地預覽網站

hatch run docs:serve

請注意，在提交內容前應先解決任何「警告」。

markdownlint 也會檢查說明文件檔案，因此你也應該執行此命令

hatch run lint:check

如果你新增外掛至 mkdocs.yml，你無需將其新增至任何「必要」檔案，因為這是自動管理的。

.venv/bin/pip install -r requirements/requirements-docs.txt  # Exact versions of dependencies.
.venv/bin/pip install -r $(mkdocs get-deps)  # Latest versions of all dependencies.

翻譯主題

要將主題在地化成你喜愛的語言，請遵循 翻譯主題 指南。我們歡迎翻譯プルリ克！

提交プルリ克

如果你考慮要對 MkDocs 進行大型程式碼提交，請先提交一個議題，以便提早收到意見回饋。

當你認為該程式碼準備好檢閱時，請推播它到分支，然後送出プルリ克。若變更要被接受，如果它是一項新功能，很可能需要附上測試與文件。

當使用プル里克分支時
除非另有約定，請首選使用 commit 而非 amend，以及 merge 而非 rebase。避免強制推播，否則將更難瀏覽檢閱歷程。對於最終結果，即使歷程「不乾淨」也沒關係，因為 GitHub 上大多數的プル里克都是使用 squash 合併。

請不要新增至release-notes.md，這會在稍後撰寫。

提交對內建主題的變更

若透過 i18n 功能安裝 (pip install 'mkdocs[i18n]')，MkDocs 可以讓主題支援翻譯成各種語言 (稱為區域設定)，前提是這些語言符合 Jinja 的 i18n 擴充功能，方法是將文字放置區塊包在 {% trans %} 和 {% endtrans %} 標籤中。

每一當在主題範本中新增、移除或變更可翻譯文字放置區塊時，必須執行 extract_messages 指令更新該主題的 Portable Object Template (pot) 檔案。若要同時更新內建主題的 pot 檔案，請執行下列指令

pybabel extract --project=MkDocs --copyright-holder=MkDocs --msgid-bugs-address='https://github.com/mkdocs/mkdocs/issues' --no-wrap --version="$(hatch version)" --mapping-file mkdocs/themes/babel.cfg --output-file mkdocs/themes/mkdocs/messages.pot mkdocs/themes/mkdocs
pybabel extract --project=MkDocs --copyright-holder=MkDocs --msgid-bugs-address='https://github.com/mkdocs/mkdocs/issues' --no-wrap --version="$(hatch version)" --mapping-file mkdocs/themes/babel.cfg --output-file mkdocs/themes/readthedocs/messages.pot mkdocs/themes/readthedocs

更新後 pot 檔案應與更新的範本一同納入 PR 中。更新後的 pot 檔案讓翻譯貢獻者可以提出其偏好語言所需翻譯。詳細資訊請參閱 翻譯主題 指南。

行為守則

在 MkDocs 計畫的程式碼庫、問題追蹤器、聊天室和郵件清單中互動的每個人都必須遵守 PyPA 行為守則。