跳轉到

安裝與啟用

在開始撰寫 MkDocs 筆記之前，我們需要先在本地電腦建立運行環境。MkDocs 是基於 Python 開發的工具，因此安裝過程非常簡便。在此我會以 Microsoft 推出的整合開發環境 Visual Stuido Code 為例來操作。

系統需求

  • Python 3.8 或更高版本
  • pip (Python 的套件管理工具)

安裝步驟

1. 確認 Python 環境

請開啟終端機（Windows 使用命令提示字元或 PowerShell，Mac/Linux 使用 Terminal），輸入以下指令確認版本：

python --version

如果正確顯示版本號，代表環境已就緒。

2. 安裝 MkDocs 套件

使用 pip 安裝 MkDocs 核心套件。建議同時安裝最熱門的主題 Material for MkDocs：

pip install mkdocs
pip install mkdocs-material

3. 建立新專案

開啟一個你想存放筆記的資料夾，執行以下指令初始化專案：

mkdocs new my-notes
cd my-notes

執行後，系統會產生一個名為 my-notes 的資料夾，內含以下結構：

  • mkdocs.yml：專案的設定檔（核心檔案）
  • docs/：存放 Markdown 原始檔的資料夾
  • docs/index.md：網站首頁

個人習慣

我個人習慣是 mkdocs new my-notes 建立專案資料夾後，從 Visual Studio Code > 檔案 > 開啟資料夾 > 選擇 my-notes 後再繼續操作，這樣就可以省去 cd my-notes 這個步驟，在終端機上查看時也比較簡潔

啟動預覽伺服器

MkDocs 最強大的功能之一就是即時預覽。在專案根目錄下執行：

mkdocs serve

執行後，終端機會顯示一個網址（通常是 http://127.0.0.1:8000/）。請將此網址輸入瀏覽器，你就能看到初步生成的網站。當你修改 docs/ 下的 Markdown 檔案並按下儲存時，網頁內容會自動更新，不需要重新整理。

如果自動更新失效，將啟動指定改成

mkdocs serve --livereload

常用指令彙整

以下是開發過程中頻繁使用的指令對照表：

指令 說明
mkdocs new [專案名稱] 建立一個全新的 MkDocs 專案結構
mkdocs serve 啟動本地開發伺服器，支援存檔即時更新
mkdocs build 將 Markdown 轉換為靜態 HTML 檔案（產出至 site 資料夾）
mkdocs -h 查看所有可用的指令說明