Sphinx中如何识别指定目录文件并切换HTML模板结构

当然有办法实现这个需求！你的思路完全找对了方向——通过路径判定文档所属范围，在Sphinx里可以用两种简单靠谱的方式落地：

方法一：直接在Jinja2模板中判断文档路径 #

Sphinx的模板系统（基于Jinja2）可以直接访问env.docname变量，它存储了当前文档相对于源码根目录的路径（不带文件后缀，路径用斜杠/分隔）。你只需要在模板（比如layout.html或者你自定义的模板文件）里添加条件判断：

{% if 'folder X' in env.docname %}
    <!-- 这里写folder X及其子目录专属的HTML结构 -->
    <div class="folder-x-content">
        {{ body }}
    </div>
{% else %}
    <!-- 原有的默认HTML结构 -->
    <div class="default-content">
        {{ body }}
    </div>
{% endif %}

如果想要更精准的匹配（避免像other-folder X这类相似目录名的误判），可以改成判断路径是否以folder X/开头：

{% if env.docname.startswith('folder X/') %}
    {# 专属结构 #}
{% else %}
    {# 默认结构 #}
{% endif %}

方法二：通过自定义Sphinx扩展标记文档 #

如果需要更灵活的逻辑（比如后续要扩展更多目录规则），可以写一个简单的Sphinx扩展，给符合条件的文档添加自定义标记，再在模板里判断这个标记：

1. 在你的Sphinx项目中创建一个扩展文件（比如extensions/folder_flag.py），内容如下：

def setup(app):
    def add_folder_x_metadata(app, doctree, docname):
        # 检查当前文档路径是否包含folder X或其子目录
        if 'folder X' in docname:
            app.env.metadata[docname]['is_in_folder_x'] = True
        else:
            app.env.metadata[docname]['is_in_folder_x'] = False

    # 绑定到文档解析完成的事件
    app.connect('doctree-resolved', add_folder_x_metadata)

2. 在conf.py中启用这个扩展：

extensions = [
    # 其他已有的扩展...
    'extensions.folder_flag'
]

3. 然后在模板里就可以直接判断这个自定义元数据：

{% if metadata.get('is_in_folder_x') %}
    {# folder X专属HTML结构 #}
{% else %}
    {# 默认结构 #}
{% endif %}

注意事项 #

• 路径的大小写要和实际目录名完全一致，Sphinx在路径判断时是区分大小写的；
• 如果使用了.. include::等方式引入内容，env.docname依然指向原文件的路径，不会影响判断逻辑；
• 如果你是修改主题模板，建议先把主题的模板文件复制到本地项目的_templates目录再修改，避免直接修改主题源码。

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