Read the Docs是否支持mkdocs配置中的显式标签？Mermaid渲染遇阻求助

Read the Docs (RTD) 确实不支持 YAML 中的 !!python/name 这类 Python 特定显式标签——这是因为他们的构建环境做了安全限制，会拦截这类可能执行任意 Python 代码的标签，所以你的配置在本地能正常运行，但提交到 RTD 就会触发 YAML 验证错误。

下面给你两种可行的解决办法，按推荐程度排序：

方法1：改用 mkdocs-material 原生 Mermaid 支持（最省心） #

现在 mkdocs-material 已经原生集成了 Mermaid 渲染，完全不需要依赖 super-fences 的自定义配置，步骤非常简单：

1. 在你的 mkdocs.yml 里启用 Mermaid 功能：

theme:
  name: material
  features:
    # 保留你原本的其他特性，新增这一行
    - content.code.mermaid

2. 直接在 Markdown 里写标准的 Mermaid 代码块就行：

```mermaid
graph TD
    A[Start] --> B{Is it?}
    B -->|Yes| C[OK]
    C --> D[End]
    B -->|No| E[Not OK]
    E --> D

这种方式完全避开了 YAML 标签的问题，是官方推荐的方案，兼容性和维护性都更好。

## 方法2：用钩子脚本绕过 YAML 限制（适合坚持原方案的场景）

如果你一定要保留原来的 super-fences 配置思路，可以通过 MkDocs 的钩子脚本绕开 RTD 的 YAML 验证：

1. 在项目根目录新建一个 `mkdocs_config.py` 文件，内容如下：
```python
from pymdownx.superfences import fence_div_format

def define_env(env):
    # 动态添加 super-fences 配置
    superfences_config = {
        "pymdownx.superfences": {
            "format": fence_div_format,
            "custom_fences": [
                {
                    "name": "mermaid",
                    "class": "mermaid",
                    "format": fence_div_format,
                }
            ]
        }
    }
    env.config["markdown_extensions"].append(superfences_config)

2. 修改 mkdocs.yml 启用这个钩子：

hooks:
  - mkdocs_config.py

3. 删除原来 mkdocs.yml 中包含 !!python/name 的那一行配置，把相关逻辑都移到钩子脚本里。

这样 RTD 只会解析普通的 YAML 内容，Python 类的引用会在钩子脚本中处理，完美避开了 YAML 验证的问题。

额外提示 #

如果你的 mkdocs-material 版本比较老，原生 Mermaid 功能可能还没上线，建议先升级到最新版本的 mkdocs-material 和 pymdown-extensions，能省不少麻烦。

内容的提问来源于stack exchange，提问作者roleyfoley