基于MkDocs框架，如何在Markdown文档中集成已有YAML文件

我刚好在自己的MkDocs项目里处理过类似需求，给你几个实用的方案，你可以根据场景选择：

方案1：用mkdocs-macros-plugin解析并复用YAML数据 #

这个插件允许你在Markdown中嵌入Python代码，能灵活读取并解析YAML内容，适合需要把YAML数据动态渲染到文档里的场景。

1. 先安装插件：

pip install mkdocs-macros-plugin

2. 在mkdocs.yml里启用插件：

plugins:
  - macros

3. 在目标Markdown文件中读取YAML：
   如果是本地相对路径（比如../dir/test.yaml），可以这样写：

{% import yaml %}
{% set yaml_data = yaml.safe_load(open('../dir/test.yaml', 'r')) %}

之后就能在文档里直接调用YAML中的数据了，比如：

### 从YAML读取的标题
{{ yaml_data.title }}

### YAML里的列表项
{% for item in yaml_data.items %}
- {{ item.name }}
{% endfor %}

要是想读取GitHub仓库里的远程YAML（比如仓库raw文件地址），可以在宏里用requests请求内容，记得提前安装requests包。

方案2：用预构建脚本嵌入YAML内容 #

如果只是想把YAML的原始内容嵌入到Markdown中，不想做数据解析，可以写个简单的Python脚本，在MkDocs构建前自动完成嵌入。

1. 编写pre_build.py脚本：

import yaml
from pathlib import Path

# 读取本地YAML文件
yaml_path = Path("../dir/test.yaml")
with open(yaml_path, 'r', encoding='utf-8') as f:
    yaml_content = f.read()

# 生成带代码块的Markdown片段
md_snippet = f"### 嵌入的YAML内容\n```yaml\n{yaml_content}\n```"

# 替换目标Markdown里的占位符（比如你在文档里写了<!-- EMBED_YAML_HERE -->）
target_md = Path("docs/your_doc.md")
with open(target_md, 'r', encoding='utf-8') as f:
    original_content = f.read()

updated_content = original_content.replace("<!-- EMBED_YAML_HERE -->", md_snippet)
with open(target_md, 'w', encoding='utf-8') as f:
    f.write(updated_content)

2. 在mkdocs.yml中配置钩子：

hooks:
  - pre_build.py

这样每次执行mkdocs build或mkdocs serve时，脚本都会自动把YAML内容嵌入到指定位置。

方案3：用mkdocs-include-markdown-plugin直接引用文件 #

如果只是想快速展示YAML文件的原始内容，这个插件能直接帮你嵌入文件，不用写额外代码。

1. 安装插件：

pip install mkdocs-include-markdown-plugin

2. 在mkdocs.yml启用插件：

plugins:
  - include-markdown

3. 在Markdown中引用YAML：
   直接用标签嵌入，还能包裹在代码块里保持格式：

```yaml
{% include "../dir/test.yaml" %}

### 注意事项
- 相对路径的基准：不同插件对路径的解析逻辑有差异，比如`mkdocs-include-markdown-plugin`默认以当前Markdown文件为基准，而macros插件里的`open()`函数是以`mkdocs.yml`所在目录为基准，配置时要注意调整路径。
- 远程GitHub YAML：如果YAML在远程仓库，建议先通过git submodule把仓库克隆到本地，再用相对路径访问，避免网络请求带来的构建延迟或失败问题。

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