MkDocs簡易使用

MkDocs用來將Markdown製作的說明文件快速製作成網站。

安裝

以pip安裝：

pip install mkdocs

顯示版號：

mkdocs --version

開始

建立新的空白專案

以mkdocs new建立新專案會以專案名稱建立新的目錄，並在其中放置二檔案及docs子資料夾：

mkdocs new my_project
cd my_project

其中有：

• mkdocs.yml：單一的設置檔。
• docs/index.md：docs下用來放Markdown文件，目前只index.md。

啟動網站

內建開發用服務器，在修改設置或md文件時會自動載入、重建新的內容。在mkdocs.yml所在目錄：

mkdocs serve

以瀏覽器開啟 http://127.0.0.1:8000/ 或是 http://localhost:8000

設置檔

mkdocs.yml的內容很簡單：

• site_name: 網站名稱。
• pages: 頁面。新增md文件之後，自行在此加入該文件與導覽的對應關係。網頁上的導覽會依此而自動產生。
• theme: 預設沒有這項，可自行加入，readthedocs是不錯的theme。

變更Favicon Icon

自行建立docs/img目錄，在其中放所要的favicon.ico即可。

組建網站

mkdocs build

網站的網頁會產生在 site/ 中。當刪除md文件後，網頁仍會留在其中，若要清除這些：

mkdocs build --clean

其他命令與選項

看一下其他命令清單：

mkdocs --help

看特定命令的選項清單，如：

mkdocs build --help

佈署

site/ 下的東西即靜態網頁，可放在像GitHub project pages的空間。

其他

mkdocs的使用相當簡單，以上就大致夠用，較進階的使用說明也沒太多文字[2]，有必要的時候再去查閱即可。

注意

• 目前預設theme的搜尋功能對中文字並無作用，這點可能要去檢查search plugin。
• docs/ 之下的圖片，就算md文件中沒用到，build時都會被複製到 site/ 下。

參考

1. MkDocs官網入門文件
2. 稍進階的User Guide