開始使用 MkDocs

一個教學入門！

---

安裝

若要安裝 MkDocs，請從命令列執行下列指令

pip install mkdocs

更多詳細資訊，請參閱 安裝指南。

建立一個新專案

開始使用非常簡單。若要建立一個新專案，請從命令列執行下列指令

mkdocs new my-project
cd my-project

花點時間檢閱專為您建立的初始專案。

有一個名為 mkdocs.yml 的單一組態檔，以及一個名為 docs 的資料夾，其中將包含您的文件原始檔（docs 是 docs_dir 組態設定的預設值）。目前 docs 資料夾只包含一個名為 index.md 的文件頁面。

MkDocs 內建了一個開發人員伺服器，讓您在進行文件編寫時可以預覽文件。請確定您目前位在與 mkdocs.yml 組態檔相同的目錄中，然後執行 mkdocs serve 指令以啟動伺服器

$ mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.22 seconds
INFO    -  [15:50:43] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO    -  [15:50:43] Serving on http://127.0.0.1:8000/

在瀏覽器中開啟 http://127.0.0.1:8000/，您將會看到顯示預設主頁

此開發人員伺服器也支援自動重新載入，並將在組態檔、文件目錄或主題目錄中的任何項目變更時重建您的文件。

使用您選擇的文字編輯器開啟 docs/index.md 文件，將初始標題變更為 MkLorum，然後儲存變更。您的瀏覽器會自動重新載入，並且您會立即看到更新的文件。

現在嘗試編輯組態檔：mkdocs.yml。將 site_name 設定變更為 MkLorum 並儲存檔案。

site_name: MkLorum

您的瀏覽器會立即重新載入，您會看到新的網站名稱生效。

加入頁面

現在，將第二個頁面加入您的文件

curl 'https://jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md

由於我們的文件網站將包含一些導覽標題，建議您編輯組態檔，並加入 nav 設定，以加入每個主導覽頁面的順序、標題和巢狀結構資訊

site_name: MkLorum
nav:
  - Home: index.md
  - About: about.md

儲存您的變更，您現在將在左側看到一個具有 主頁 和 關於 項目的導覽列，以及在右側具有 搜尋、上一頁 和 下一頁 項目的導覽列。

試試選單中的項目，並在不同的頁面中前後瀏覽。然後按一下搜尋。系統會顯示一個搜尋對話框，讓你可以在任何頁面中搜尋任何文字。請注意搜尋結果包含該網站中搜尋項目出現的所有地方，並連結到該搜尋項目出現於其中之頁面區段。你無需付出任何功夫或進行任何設定，即可順利完成上述作業！

為我們的說明文件建立主題

現在變更設定檔，以變更主題設定，進而變更說明文件顯示的方式。編輯mkdocs.yml檔案並加入主題設定

site_name: MkLorum
nav:
  - Home: index.md
  - About: about.md
theme: readthedocs

儲存變更後，你會看到 ReadTheDocs 主題開始使用。

變更 Favicon 圖示

預設情況下，MkDocs 會使用MkDocs Favicon圖示。若要使用不同的圖示，請在docs目錄中建立 img 副目錄，並將你的自訂favicon.ico檔案複製到該目錄。MkDocs 會自動偵測並採用該檔案作為你的 Favicon 圖示。

建立網站

看起來很棒。現在，你可以部署MkLorum說明文件的初稿。首先，建立說明文件

mkdocs build

此舉會建立新的目錄，命名為site。瀏覽目錄內部

$ ls site
about  fonts  index.html  license  search.html
css    img    js          mkdocs   sitemap.xml

請注意，你的原始文件已輸出為兩個 HTML 檔案，命名為index.html和about/index.html。在說明文件主題中，你也有許多其他媒體檔案已複製到site目錄中。你甚至擁有一個sitemap.xml檔案和mkdocs/search_index.json。

如果你正在使用 git 等原始碼控制，你可能不想將你的說明文件版本控管至存放庫中。在你的.gitignore檔案中新增一行，包含site/。

echo "site/" >> .gitignore

如果你正在使用其他原始碼控制工具，你需要查閱說明文件了解如何忽略特定目錄。

其他命令與選項

有各種其他的命令與選項可用。若要查看命令完整清單，請使用 --help 旗標

mkdocs --help

若要查看特定命令中可用的選項清單，請搭配該命令使用 --help 旗標。例如，若要取得所有供build命令使用的選項，請執行以下動作

mkdocs build --help

部署

你剛剛建立的說明文件網站僅使用靜態檔案，因此你可以從幾乎任何地方主機它。只需將整個site目錄的內容上傳到你的網站主機，即可完成部署。若要取得關於許多常見主機的特定說明，請參閱部署文件頁面。

取得協助

請參閱使用者指南，以取得 MkDocs 所有功能的更完整說明文件。

若要取得關於 MkDocs 的協助，請使用GitHub 討論區或GitHub 問題。