GitHub Actions中MkDocs构建失败：docs_dir配置路径不存在错误

嘿，我看你在GitHub Actions里跑MkDocs构建时踩了路径配置的坑，提示docs_dir对应的路径不存在，而且你尝试创建目录后还是没解决，这大概率是配置文件的相对路径搞混了，我来帮你理清楚～

先把你遇到的错误日志贴出来，方便定位问题：

Run mkdocs build -f mkdocs/mkdocs.yml

mkdocs build -f mkdocs/mkdocs.yml

shell: /usr/bin/bash -e {0}
env:
pythonLocation: /opt/hostedtoolcache/Python/3.12.3/x64
PKG_CONFIG_PATH: /opt/hostedtoolcache/Python/3.12.3/x64/lib/pkgconfig
Python_ROOT_DIR: /opt/hostedtoolcache/Python/3.12.3/x64
Python2_ROOT_DIR: /opt/hostedtoolcache/Python/3.12.3/x64
Python3_ROOT_DIR: /opt/hostedtoolcache/Python/3.12.3/x64
LD_LIBRARY_PATH: /opt/hostedtoolcache/Python/3.12.3/x64/lib
ERROR   -  Config value 'docs_dir': The path 'mkdocs/Docs' isn't an existing directory.

Aborted with a configuration error!

Error: Process completed with exit code 1.

你之前尝试过修改mkdocs.yml里的docs_dir为mkdocs/Docs，还执行了创建目录的命令：

mkdir -p mkdocs/Docs
echo "# Welcome to MkDocs" > mkdocs/Docs/index.md

但没生效，问题出在相对路径的基准目录上！

问题根源 #

你用-f mkdocs/mkdocs.yml指定了配置文件在mkdocs/目录下，此时MkDocs会以这个配置文件所在的目录（也就是mkdocs/）作为基准来解析docs_dir的路径。如果你在mkdocs/mkdocs.yml里写docs_dir: mkdocs/Docs，MkDocs会去mkdocs/mkdocs/Docs找目录，这显然不是你要的路径，自然会提示不存在。

解决步骤 #

1. 修正mkdocs.yml的docs_dir配置

打开mkdocs/mkdocs.yml，把docs_dir改成相对于配置文件的路径：

# 配置文件在mkdocs/目录下，直接写Docs就对应实际路径mkdocs/Docs
docs_dir: Docs

2. 在GitHub Actions中确保目录存在（调整执行顺序）

在你的Workflow里，先执行创建目录和文件的命令，再跑MkDocs构建：

- name: 创建Docs目录和首页文件
  run: |
    mkdir -p mkdocs/Docs
    echo "# Welcome to MkDocs" > mkdocs/Docs/index.md

- name: 构建MkDocs站点
  run: mkdocs build -f mkdocs/mkdocs.yml

3. 可选：添加目录结构验证步骤

如果还是有问题，可以加一步打印当前目录的结构，方便排查：

- name: 查看当前目录结构
  run: |
    pwd
    ls -R

这样调整后，MkDocs就能正确找到mkdocs/Docs目录了，构建应该就能正常运行啦～

备注：内容来源于stack exchange，提问作者Suraj Kumar Behera