MkDocs技术问询：如何为指定Markdown文件匹配对应模板

嗨，我来帮你理清MkDocs和Jinja模板匹配的核心逻辑，其实就是要明确告诉MkDocs「哪个Markdown文件该用哪个模板」，这里有几个实用的方法，按你的需求选就行：

1. 给每个页面加元数据（最直接） #

这是最简单的方式，在每个Markdown文件的开头添加YAML元数据块，直接指定对应的模板。比如：

• landing.md开头加：

---
template: landing.html
---

• 所有产品页（product1.md/product2.md等）开头加：

---
template: product.html
---

• 所有文档页（doc1.md/doc2.md等）开头加：

---
template: docs.html
---

MkDocs会自动读取这个元数据，渲染时就会调用你指定的模板。记得把这些模板文件（landing.html/product.html/docs.html）放在docs/templates目录下（如果是自定义主题，也可以放在主题的templates目录），并且每个子模板开头必须写{% extends "main.html" %}，确保正确继承主模板的结构。

2. 按目录批量配置（适合文件多的情况） #

如果你的同类型文件都集中在某个目录里（比如所有文档页在docs/docs/子目录，产品页在docs/products/子目录），可以用MkDocs钩子批量设置模板，不用一个个加元数据。

步骤如下：

1. 在你的项目根目录创建docs/hooks文件夹（如果没有的话）
2. 在里面新建on_page_markdown.py文件，写入以下代码：

def on_page_markdown(markdown, page, config, files):
    # 根据文件路径自动分配模板
    if page.file.src_path == "landing.md":
        page.meta["template"] = "landing.html"
    elif page.file.src_path.startswith("products/"):
        page.meta["template"] = "product.html"
    elif page.file.src_path.startswith("docs/"):
        page.meta["template"] = "docs.html"
    return markdown

这样MkDocs在构建时，会自动根据文件所在路径给页面分配对应的模板，省心很多。

3. 几个关键注意事项 #

• 模板路径要正确：默认MkDocs会优先找docs/templates里的模板，如果你放在其他位置，需要在mkdocs.yml里指定：

theme:
  name: material  # 或者你的自定义主题名称
  templates_dir: docs/custom_templates  # 替换成你的模板目录路径

• 子模板继承要规范：每个子模板必须通过{% extends "main.html" %}继承主模板，然后通过{% block 区块名 %}替换主模板里的对应内容（比如{% block content %}替换主体内容区域）。
• 实时测试验证：用mkdocs serve启动本地服务，随时查看模板是否正确应用，如果没生效，先检查元数据的YAML格式（开头和结尾的---不能少），或者钩子文件的路径是否正确。

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