Skip to content

MkDocs 簡介

MkDocs 是一款快速且簡單的靜態網站產生器，專門為建立專案文件而設計。它能將 Markdown 文件轉換成漂亮的網站，並支援多種主題及擴充功能。

起源

MkDocs 起初是為了滿足軟體開發者快速建立與維護專案文件的需求而開發的。其核心理念是保持簡單易用，同時提供足夠的彈性以滿足不同專案的需求。

環境設置

要使用 MkDocs，首先需要有 Python 環境。因此，請確保您的系統已安裝 Python。MkDocs 支援 Python 3.5 或更新版本。

  • 安裝 Python：前往 Python 官方網站 下載並安裝 Python。安裝時請確認選項中有將 Python 加入系統路徑。

  • 檢查 Python 版本： 開啟終端機或命令提示字元，輸入以下指令來檢查 Python 版本： 

    python --version

為了後續能順利使用 MkDocs，安裝 Python 時，請以自訂方式進行，選取 Add Python to PATH 選項，並避免選擇 所有使用者 都安裝的選項。選取 Add Python to PATH 可以將 Python 執行檔案的目錄添加至環境變數的 path 中。而選擇了所有使用者，Python 相關檔案將會被安裝在 C:\Program Files\Python39，但是 MkDocs 只會在 C:\Users\username\AppData\Roaming\Python\Python39\Scripts 路徑下尋找，這將導致安裝 MkDocs 出現錯誤。

安裝 MkDocs

在設定好 Python 環境之後，請以管理員身分開啟 PowerShell，並透過 pip 來安裝 MkDocs。

pip install mkdocs

安裝完成後，輸入 mkdocs --version 以確認 MkDocs 是否已正確安裝。

安裝 Material for MkDocs

MkDocs 本身只提供基本的功能，如果想要採用 Material 樣式與功能，可以安裝 Material for MkDocs。安裝指令如下:

pip install mkdocs-material

配置檔與範例

  • 建立新專案：

在您希望建立文件的目錄中，執行以下指令以建立一個新的 MkDocs 專案：

mkdocs new my-project

這會建立一個名為 my-project 的新目錄，其中包含 MkDocs 的配置檔案 mkdocs.yml 和一個文件目錄 docs。

如果要在現有目錄中建立新專案，可以使用 . 作為目錄名稱：

mkdocs new .
  • 編輯配置檔 (mkdocs.yml)：

這個檔案用於設定您的網站。基本配置可能如下所示：

site_name: 'Angular Courses 2024'
site_dir: public

nav:
  - Home: index.md

theme:
  name: material
  • 新增文件：

在 docs 目錄下，您可以新增 Markdown 檔案。例如，建立一個 index.md 檔案作為首頁。

  • 加入搜尋：

要加入搜尋功能，請在 mkdocs.yml 中加入以下設定。預設會使用英文搜尋，若要使用中文搜尋，請加入 lang: ja。(目前中文搜尋功能尚未完善，故利用日文搜尋來達成中文搜尋的效果)

plugins:
  - search:
      lang: ja
  • 啟動服務：

在專案根目錄（即含有 mkdocs.yml 的位置）執行以下指令以啟動本地服務：

mkdocs serve

這樣就可以在瀏覽器中預覽您的網站了。通常，它會在 http://127.0.0.1:8000 上運行。

Markdown Extensions

下列是 Material for MkDocs 支援的 Markdown Extensions，雖然可以增加顯示效果，但是不建議使用，因為這些擴充功能會使 Markdown 文件與其他 Markdown 編輯器不相容，而無法正常顯示。未來要轉換成 pdf 時，也會出現錯誤。

  • 加入icon：

要顯示 icon，請在 mkdocs.yml 中加入以下設定：

markdown_extensions:
  - attr_list
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg

接著，便可以在 Markdown 文件中使用 icon 了：

:smile:
😄

:fontawesome-solid-heart:

  • Grid：

要設計成 grid 樣式，請在 mkdocs.yml 中加入以下設定：

markdown_extensions: 
  - attr_list
  - md_in_html

接著，便可以在 Markdown 文件中使用 grid 了：

<div class="grid cards" markdown>

- :fontawesome-brands-html5: __HTML__ for content and structure
- :fontawesome-brands-js: __JavaScript__ for interactivity
- :fontawesome-brands-css3: __CSS__ for text running out of boxes
- :fontawesome-brands-internet-explorer: __Internet Explorer__ ... huh?

</div>
  • HTML for content and structure
  • JavaScript for interactivity
  • CSS for text running out of boxes
  • Internet Explorer ... huh?

調整 VSCode settings.json

為了讓 VSCode 能夠正確顯示 Markdown 文件，請在 VSCode .vscode 目錄下增加或修改 settings.json ，加入以下設定。由於 MkDocs 的縮排為 4 個空格，因此將 tabSize 設為 4，並將 insertSpaces 設為 true 來阻止 VSCode 自動偵測到其他縮排模式來改變已制定好的 tabSize 規則。此外，為了讓 VSCode 能夠正確顯示 mkdocs.yml 中的 yaml 設定，請加入 yaml.schemas 與 yaml.customTags 的設定。

{
    "[markdown]": {
        "editor.tabSize": 4,
        "editor.insertSpaces": true
    },
    "editor.detectIndentation": false,
    "yaml.schemas": {
        "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml"
    },
    "yaml.customTags": [
        "!ENV scalar",
        "!ENV sequence",
        "!relative scalar",
        "tag:yaml.org,2002:python/name:material.extensions.emoji.to_svg",
        "tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji",
        "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format"
    ]
}

建立靜態網站

完成所有文件編輯後，您可以使用以下指令來建立靜態網站：

mkdocs build
這將在 site 目錄中產生靜態內容，可部署至任何靜態檔案伺服器。

MkDocs 以其簡潔和易用性著稱，成為許多開發專案文件的首選工具。透過使用 Markdown 和配置檔案，開發者能迅速建立專業的文件網站。

參考資料:
- MkDocs Official Documentation
- Material for MkDocs
- Icons, Emojis