Mkdocs介紹
今天介紹 MkDocs 這款筆記工具。身為一個筆記控，我個人習慣把資料或工作進度寫成筆記，我用過許多筆記軟體，但總覺得撰寫起來很受拘束，如果可以用 markdown 語法來寫筆記就可以更灑脫一點。於是我輾轉發現了 MkDocs 這款開源工具。MkDos 透過 Python 將筆記轉換成靜態網頁的形式，方便查找資料，速度極快，如果有需要也能將資料部署到網路上。
如果是需要個性化網頁外觀設計的化，MkDocs 版面形式選擇也較少，僅能透過 CSS 來做微調，這個工具總的來說還是更著重在更容易且無拘束的撰寫內容上，不過個人覺得基本的版面設計看起來也已經很好看了，重點是純粹使用 Markdwon 寫筆記真的很直覺也很簡單。
MkDocs 是以 Markdown 語法為基礎的靜態網站設計工具，通常用來撰寫文件、操作手冊、知識庫，然後再將結構化的資料轉成 HTML 靜態網站，完成後可以放在本地端自己查看，也可以上傳到網路上或 GitHub Pages 上供人查詢。對於公司內的重要文件，我覺得 MkDocs 可以表現得非常稱職，直接 build 成靜態的 html 放在公司私人的伺服器就可以供同事內部查詢使用。
第一次聽到 Markdown 語法的初學者請不用緊張，Markdown 語法是非常容易上手且直覺的語法，老實說我自己也是之前沒學過，所以我把一些常用的語法整理起來，對照著寫個幾篇整理文後，很快就掌握了，重點是 Markdown 寫出來的文章很好整理也很乾淨，未來要把文章轉移到其他筆記或部落格工具也是無痛轉移。
什麼是 MkDocs？
MkDocs 是一個專門為了專案文件開發的靜態網站產生器。它完全基於 Markdown 格式撰寫，配置則透過單一的 YAML 檔案完成。透過 MkDocs，使用者可以將散亂的純文字筆記轉化為具備搜尋功能、響應式佈局且視覺美觀的專業文件網站。
為什麼要採用這個工具？
對於工程師或技術文件撰寫者而言，MkDocs 提供了以下核心優勢：
- 安裝簡單：安裝簡單，幾分鐘就能建立一個新網站
- 專注寫作：不需要具備 HTML 或 CSS 基礎，只要簡單學習低難度的 Markdown 就能架構出專業的網站
- 即時預覽：內建開發伺服器，當你修改 Markdown 檔案並儲存時，瀏覽器會立即自動重新整理
- 可擴展性：擁有成熟的生態系，透過 Plugin 可以輕鬆加入程式碼高亮、數學公式（LaTeX）或圖表支持
筆記系列導覽
你可以將本頁作為目錄，依照以下進度循序漸進地建立你的網站：
筆記系列導覽
第一部分：環境與基礎
第二部分：內容與美化
- Markdown 語法：掌握 MkDocs 特有的擴充標記與編排技巧。
- 現成主題推薦：選擇適合你的視覺風格，提升閱讀感。
第三部分：進階功能與發布
網站架設工具比較
以下將 MkDocs 與常見的靜態網站產生器（SSG）及內容管理系統（CMS）進行對比：
| 特性 | MkDocs | Hugo | Docusaurus | WordPress |
|---|---|---|---|---|
| 核心語言 | Python | Go | React (JS) | PHP |
| 上手難度 | 低（極易） | 中（需學習模板語法） | 中（需 JS 基礎） | 高（後台設定繁瑣） |
| 生成速度 | 快 | 極快 | 中 | 不適用（動態生成） |
| 適用場景 | 技術文件、個人筆記 | 部落格、形象官網 | 大型開源專案文件 | 電商、大型新聞門戶 |
筆記軟體比較
相對於 Obsidian 或 Notion 等筆記軟體，MkDocs 在公開發布與自定義上有其優勢：
| 特性 | MkDocs | Obsidian | Notion |
|---|---|---|---|
| 主要用途 | 靜態網站發布 | 個人知識管理 | 團隊協作與專案管理 |
| 發布成本 | 免費（GitHub Pages） | 高（官方發布需訂閱） | 中（公開頁面限制較多） |
| 資料存放 | 本地 Markdown 檔案 | 本地 Markdown 檔案 | 雲端資料庫 |
| SEO 友善度 | 高（易於搜尋引擎收錄） | 低（主要為私有筆記） | 中（依賴平台設定） |
| 多人協作 | 依賴 Git 流程 | 依賴第三方同步 | 內建即時協作 |