Allow INHERIT to list several config files

[shenxianpeng]

INHERIT accepts a single parent file, so splitting a configuration into several files means chaining them, each inheriting from the next. That's hard to maintain.

INHERIT now also accepts a list:

INHERIT:
  - config/markdown_extensions.yml
  - config/plugins.yml
site_name: Foo Project

Semantics

• Files are merged in order: each overrides the ones before it, and the file itself overrides all of them. The merge rules are unchanged: mappings are deep-merged and lists are replaced.
• Parent files can use INHERIT too, with paths relative to themselves. A shared grandparent (diamond inheritance) is fine.
• A file that inherits from itself, directly or indirectly, is a configuration error that shows the chain. Previously it recursed until RecursionError. Paths are compared with realpath, so cycles through symlinks are caught too.
• A value that isn't a path or a list of paths is reported clearly.
• The single-path form and the documented stdin trick (echo '{INHERIT: mkdocs.yml, …}' | mkdocs build -f -) are unchanged.

mkdocs serve watches inherited files

serve watched only the primary config file, so editing an inherited file didn't trigger a rebuild. That already affected single-file INHERIT, and it matters more once a configuration is split. yaml_load gets a new keyword-only inherited argument that collects the paths of inherited files. MkDocsConfig.load_file records them as _inherited_config_files, and serve watches them.

Verification

• New tests cover: merging several files in order, a shared parent, an empty list, direct and indirect cycles, invalid values, load_config recording the inherited files, and serve watching them. All of them fail without the change.
• Manually tested with a config split into three files: the merge result is correct, and mkdocs serve lists all three inherited files among the watched paths and rebuilds when one of them changes.

Known limitation: mkdocs get-deps loads YAML with the mkdocs-get-deps package's own loader, which only supports a single INHERIT path. With a list, it fails with a TypeError until that package is updated.

Related Issue

No issue in this repository.

Checklist

• New tests added for new behavior (if applicable)
• Documentation updated (if applicable)
• Release notes docs/about/release-notes.md updated (if applicable)

🤖 Generated with Claude Code

[codspeed]

Merging this PR will not alter performance

✅ 28 untouched benchmarks

---

_{Comparing feature/inherit-multiple (f59c327) with main (5fd5096)}