如何让MkDocs支持多位置存储的Markdown文档？

阿华AIGC实验室

2026-4-29

解决MkDocs检索多个分散文档文件夹的问题

我之前也碰到过和你一模一样的困扰——MkDocs默认只能指定一个docs_dir，但文档散在好几个没共同父目录的地方，总不能手动复制吧？下面分享几个我亲测有效的方法：

方法一：用符号链接（软链接）整合（最简单）

这个方法不用改代码，靠系统的软链接把分散的文件夹“挂”到MkDocs默认的docs目录下，让MkDocs以为它们是同一个目录里的内容。

操作步骤：

确保你有一个默认的docs目录（没有就新建一个）
给每个分散的文件夹创建软链接：
- Linux/macOS：在终端运行
```
ln -s /绝对路径/到/你的/文件夹 docs/自定义链接名
```
  比如ln -s /home/user/docs/projectA docs/projectA
- Windows：以管理员身份打开命令提示符，运行
```
mklink /D docs\自定义链接名 C:\绝对路径\到\你的\文件夹
```
  比如mklink /D docs\projectA C:\Users\user\docs\projectA
现在运行mkdocs serve，就能看到所有链接文件夹里的文档了！

⚠️ 注意：如果是部署静态站点，有些平台（比如GitHub Pages）默认不会跟随软链接，这时候可以在构建时用mkdocs build --copy-files（确保把软链接里的文件实际复制到站点目录），或者在部署脚本里先手动复制文件。

方法二：写自定义MkDocs插件（最灵活）

如果软链接的方式满足不了需求（比如需要动态控制文件包含逻辑），可以写一个简单的MkDocs插件，在构建时自动把分散的文件加入文档集合。

示例插件代码：

创建一个multidocs_plugin.py文件，内容如下：

import os
from mkdocs.plugins import BasePlugin
from mkdocs.structure.files import File

class MultiDocsPlugin(BasePlugin):
    def on_files(self, files, config):
        # 在这里定义你要包含的所有额外文档目录
        extra_directories = [
            "/绝对路径/到/文件夹1",
            "/绝对路径/到/文件夹2",
            # 可以继续添加更多目录
        ]

        for dir_path in extra_directories:
            # 遍历目录下所有.md文件
            for root, _, filenames in os.walk(dir_path):
                for filename in filenames:
                    if filename.endswith(".md"):
                        file_full_path = os.path.join(root, filename)
                        # 计算文件相对于当前目录的路径（用来在站点中生成URL）
                        relative_path = os.path.relpath(file_full_path, dir_path)
                        # 创建MkDocs的File对象并添加到文件列表
                        new_file = File(relative_path, dir_path, config["site_dir"], config)
                        files.append(new_file)
        return files

配置插件：

在mkdocs.yml里添加插件配置：

plugins:
  - multidocs_plugin:
      extra_directories:
        - /绝对路径/到/文件夹1
        - /绝对路径/到/文件夹2

⚠️ 注意：要确保插件能被MkDocs找到——你可以把插件文件放在项目根目录，或者安装成Python包。如果是本地使用，也可以在mkdocs.yml里指定插件路径。

方法三：用脚本复制文件后构建（最直接）

如果不想搞软链接和插件，写个简单的脚本先把所有分散的.md文件复制到一个临时目录，再用MkDocs构建，也是个不错的选择。

Linux/macOS 示例Shell脚本：

#!/bin/bash

# 创建临时文档目录
mkdir -p temp_docs

# 复制所有分散的.md文件到临时目录（支持子目录）
cp -r /路径/到/文件夹1/*.md temp_docs/
cp -r /路径/到/文件夹2/**/*.md temp_docs/

# 用临时目录作为docs_dir构建站点
mkdocs build --docs-dir temp_docs

# 可选：清理临时目录
rm -rf temp_docs

Windows 示例Bat脚本：

@echo off

:: 创建临时文档目录
mkdir temp_docs

:: 复制文件到临时目录
xcopy "C:\路径\到\文件夹1\*.md" "temp_docs\" /s /y
xcopy "C:\路径\到\文件夹2\*.md" "temp_docs\" /s /y

:: 构建站点
mkdocs build --docs-dir temp_docs

:: 清理临时目录（可选）
rmdir /s /q temp_docs