MkDocs无法识别extra_templates中的自定义模板，该如何解决？

问题描述 #

使用MkDocs Material主题，已在docs/templates/my_template.html定义自定义模板，在mkdocs.yml中配置：

extra_templates:
  - templates/my_template.html

并在文档front matter中指定：

---
template: my_template.html
---

运行mkdocs build时出现错误：

jinja2.exceptions.TemplateNotFound: 'my_template.html' not found in search paths: '/usr/local/lib/python3.13/site-packages/material/templates', '/usr/local/lib/python3.13/site-packages/mkdocs/templates'

尝试过多种路径形式（my_template、templates/my_template等）均无效。

原因分析 #

extra_templates配置的作用是将指定模板文件复制到输出的site/目录，用于生成独立的静态页面，但它不会将模板所在目录添加到Jinja的模板搜索路径。Jinja渲染markdown文档时只会搜索Material主题自带模板目录、MkDocs核心模板目录，你的自定义模板不在这些路径中，因此无法被找到。

解决方案 #

方法1：将模板移至项目根目录的templates文件夹（最简单） #

MkDocs默认会自动扫描项目根目录下的templates/文件夹，并将其加入Jinja的模板搜索路径：

1. 把docs/templates/my_template.html移动到项目根目录新建的templates/文件夹中
2. 删除mkdocs.yml中的extra_templates配置项
3. 保持文档front matter的template: my_template.html不变，重新运行mkdocs build

方法2：使用Material主题的custom_dir目录（适合主题自定义场景） #

如果需要和Material主题的自定义样式、模板结合，可使用主题的custom_dir配置：

1. 在项目根目录创建overrides文件夹，再在其中创建templates子文件夹
2. 将my_template.html放入overrides/templates/
3. 修改mkdocs.yml的主题配置：

   theme:
     name: material
     custom_dir: overrides
   

4. 保持front matter的模板指定不变，重新执行构建命令

方法3：通过自定义插件添加模板搜索路径（保留docs下路径的场景） #

如果必须保留模板在docs/templates/路径下，可通过自定义插件扩展Jinja的搜索路径：

1. 在项目根目录创建plugins/add_template_path.py，写入以下代码：

   import os
   from mkdocs.plugins import BasePlugin
   
   class AddTemplatePathPlugin(BasePlugin):
       def on_config(self, config):
           # 将docs/templates目录加入Jinja模板搜索路径
           template_dir = os.path.join(config.docs_dir, "templates")
           config.theme.templates.insert(0, template_dir)
           return config
   

2. 在mkdocs.yml中启用该插件：

   plugins:
     - add_template_path:
         path: plugins/add_template_path.py
   

3. 保持front matter的模板指定不变，重新构建即可

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