MkDocs 安裝

詳細的指南。

需求

MkDocs 需要最新版本的 Python 和 Python 套件管理員 pip 安裝於您的系統中。

您可以透過命令列檢查您是否已安裝這些軟體

$ python --version
Python 3.8.2
$ pip --version
pip 20.0.2 from /usr/local/lib/python3.8/site-packages/pip (python 3.8)

如果您已安裝這些套件，您可以跳到 安裝 MkDocs。

安裝 Python

使用您選擇的套件管理員，或從 python.org 下載適用於您系統的安裝程式並執行它。安裝 Python。

請注意

如果您是在 Windows 上安裝 Python，請務必勾選方塊將 Python 加入您的 PATH 中，如果安裝程式提供了這個選項（它通常預設為關閉）。

Add Python to PATH

安裝 pip

如果您使用的是較新的 Python 版本，Python 套件管理員 pip 很可能預設已安裝。但是，您可能需要將 pip 升級至最新版本

pip install --upgrade pip

如果您需要第一次安裝 pip，下載 get-pip.py。然後執行以下指令安裝

python get-pip.py

安裝 MkDocs

使用 pip 安裝 mkdocs 套件

pip install mkdocs

您現在應該已在您的系統中安裝好 mkdocs 指令。執行 mkdocs --version 以檢查一切都正常運作。

$ mkdocs --version
mkdocs, version 1.2.0 from /usr/local/lib/python3.8/site-packages/mkdocs (Python 3.8)

請注意

如果您希望在 MkDocs 中安裝手冊頁，click-man 工具可以為您產生並安裝這些頁面。只要執行以下兩個指令

pip install click-man
click-man --target path/to/man/pages mkdocs

請參閱 click-man 文件，了解為什麼手冊頁不會由 pip 自動產生並安裝。

請注意

如果您使用的是 Windows，上面的一些指令可能無法直接執行。

一個快速的解決方法是在每個 Python 指令前加上 python -m，就像這樣

python -m pip install mkdocs
python -m mkdocs

對於更永久的解決方案，您可能需要編輯您的 PATH 環境變數，以包含您 Python 安裝的 Scripts 目錄。較新的 Python 版本包含一個腳本可為您執行此項操作。導航至您的 Python 安裝目錄（例如 C:\Python38\），開啟 Tools，然後是 Scripts 資料夾，並透過雙擊執行 win_add2path.py 檔案。或者，您可以下載 腳本 並執行它（python win_add2path.py）。