跳转至

mkdocs Cloudflare

Cloudflare Pages

Cloudflare 把 Pages 入口藏在這個畫面的最下面

Looking to deploy Pages? → Get started

這就是 Pages 的入口（超級反人類設計）

Cloudflare 設定：

  • Build command: pip install -r requirements.txt && mkdocs build

  • Build output directory: site

Cloudflare 的環境中找不到 mkdocs 這個程式。

19:49:32.515Initializing build environment...19:49:32.515Initializing build environment...19:49:36.685Success: Finished initializing build environment19:49:37.806Cloning repository...19:49:38.963No build output detected to cache. Skipping.19:49:38.963No dependencies detected to cache. Skipping.19:49:38.965Detected the following tools from environment: 19:49:39.107Executing user build command: mkdocs build19:49:39.109/bin/sh: 1: mkdocs: not found19:49:39.112Failed: error occurred while running build command

錯誤訊息 /bin/sh: 1: mkdocs: not found 代表系統還沒安裝 MkDocs，就直接執行了打包指令。

mkdocs.yml 檔案應該移動到專案的最頂層（根目錄）

19:53:47.30219:53:47.304Successfully installed babel-2.17.0 backrefs-6.1 certifi-2025.11.12 charset_normalizer-3.4.4 colorama-0.4.6 ghp-import-2.1.0 idna-3.11 jinja2-3.1.6 markdown-3.10 markupsafe-3.0.3 mergedeep-1.3.4 mkdocs-1.6.1 mkdocs-get-deps-0.2.0 mkdocs-material-9.7.1 mkdocs-material-extensions-1.3.1 paginate-0.5.7 pathspec-0.12.1 pygments-2.19.2 pymdown-extensions-10.20 python-dateutil-2.9.0.post0 pyyaml-6.0.3 pyyaml-env-tag-1.1 requests-2.32.5 six-1.17.0 urllib3-2.6.2 watchdog-6.0.019:53:47.370Reshimming asdf python...19:53:47.937Error: Config file 'mkdocs.yml' does not exist.19:53:47.955Failed: error occurred while running build command

錯誤訊息 Config file 'mkdocs.yml' does not exist. 非常明確：Cloudflare 在你目前的根目錄找不到 mkdocs.yml 檔案。

目錄結構

我的專案 (Repository Root)
├── mkdocs.yml          <-- 必須要在這裡
├── requirements.txt
└── docs/               <-- 所有的 .md 檔案放在這
    ├── index.md
    └── ...

docs 的資料夾移動到根目錄

19:55:31.501Installing collected packages: paginate, watchdog, urllib3, six, pyyaml, pygments, pathspec, mkdocs-material-extensions, mergedeep, markupsafe, markdown, idna, colorama, charset_normalizer, certifi, backrefs, babel, requests, pyyaml-env-tag, python-dateutil, pymdown-extensions, mkdocs-get-deps, jinja2, ghp-import, mkdocs, mkdocs-material19:55:35.77019:55:35.774Successfully installed babel-2.17.0 backrefs-6.1 certifi-2025.11.12 charset_normalizer-3.4.4 colorama-0.4.6 ghp-import-2.1.0 idna-3.11 jinja2-3.1.6 markdown-3.10 markupsafe-3.0.3 mergedeep-1.3.4 mkdocs-1.6.1 mkdocs-get-deps-0.2.0 mkdocs-material-9.7.1 mkdocs-material-extensions-1.3.1 paginate-0.5.7 pathspec-0.12.1 pygments-2.19.2 pymdown-extensions-10.20 python-dateutil-2.9.0.post0 pyyaml-6.0.3 pyyaml-env-tag-1.1 requests-2.32.5 six-1.17.0 urllib3-2.6.2 watchdog-6.0.019:55:35.851Reshimming asdf python...19:55:36.537ERROR - Config value 'docs_dir': The path '/opt/buildhome/repo/docs' isn't an existing directory.19:55:36.53719:55:36.538Aborted with a configuration error!19:55:36.573Failed: error occurred while running build command

錯誤訊息 The path '/opt/buildhome/repo/docs' isn't an existing directory 代表 MkDocs 預期會有一個叫作 docs 的資料夾來存放你的 .md 檔案，但在你的專案根目錄找不到它。

plugin 缺失

19:58:14.163Installing collected packages: paginate, watchdog, urllib3, six, pyyaml, pygments, pathspec, mkdocs-material-extensions, mergedeep, markupsafe, markdown, idna, colorama, charset_normalizer, certifi, backrefs, babel, requests, pyyaml-env-tag, python-dateutil, pymdown-extensions, mkdocs-get-deps, jinja2, ghp-import, mkdocs, mkdocs-material19:58:18.61619:58:18.619Successfully installed babel-2.17.0 backrefs-6.1 certifi-2025.11.12 charset_normalizer-3.4.4 colorama-0.4.6 ghp-import-2.1.0 idna-3.11 jinja2-3.1.6 markdown-3.10 markupsafe-3.0.3 mergedeep-1.3.4 mkdocs-1.6.1 mkdocs-get-deps-0.2.0 mkdocs-material-9.7.1 mkdocs-material-extensions-1.3.1 paginate-0.5.7 pathspec-0.12.1 pygments-2.19.2 pymdown-extensions-10.20 python-dateutil-2.9.0.post0 pyyaml-6.0.3 pyyaml-env-tag-1.1 requests-2.32.5 six-1.17.0 urllib3-2.6.2 watchdog-6.0.019:58:18.700Reshimming asdf python...19:58:19.323ERROR - Config value 'plugins': The "awesome-pages" plugin is not installed19:58:19.32419:58:19.324Aborted with a configuration error!19:58:19.358Failed: error occurred while running build command

錯誤訊息是 The "awesome-pages" plugin is not installed。

這是因為你在 mkdocs.yml 裡面啟用了 awesome-pages 這個外掛，但你之前的 pip install 指令或 requirements.txt 裡面沒有包含它。

使用 requirements.txt (推薦)

requirements.txt 就是用來放 Plugin（外掛）和所有 Python 套件的地方。 根目錄建立 requirements.txt。

Build command: 確保指令包含讀取這個檔案的動作：

pip install -r requirements.txt && mkdocs build

目錄結構

我的專案 (Repository Root)
├── mkdocs.yml              # 設定檔
├── requirements.txt        # <--- 必須要在這裡！
└── docs/                   # 文件資料夾
    ├── index.md
    └── ...

requirements.txt