如何在Sphinx的toctree（启用glob）中自定义显示标题？

我刚好碰到过类似的需求，不用titlesonly也能实现自定义toctree条目标题，给你两种实用的方案：

方案1：混合显式条目+glob（适合少量自定义） #

这种方法最简单，不需要改配置，直接在toctree里给特定文件指定自定义标题，同时保留glob匹配其他文件。调整你的index.md代码如下：

```{toctree}
---
maxdepth: 1
glob:
---
src/audit/README.md    Project Root
src/*/*

这样`src/audit/README.md`会显示为`Project Root`，其他匹配`src/*/*`的文件依然沿用原文件的H1标题或文件名。

## 方案2：利用文件元数据批量自定义（适合大量条目）
如果有很多文件需要修改标题，可以用MyST的frontmatter元数据配合Sphinx配置来实现：

### 步骤1：给目标Markdown文件添加元数据
在你的`src/audit/README.md`里添加frontmatter，指定自定义标题：
```markdown
---
title: Project Root
---
# Projet audit @shared
* Project Root: `audit`

步骤2：修改Sphinx配置文件conf.py #

添加一段自定义逻辑，让Sphinx读取文件的title元数据作为toctree显示标题：

from sphinx.util import logging

logger = logging.getLogger(__name__)

def use_custom_title(app, doctree, docname):
    # 获取当前文档的元数据
    doc_metadata = app.env.metadata.get(docname, {})
    custom_title = doc_metadata.get('title')
    if custom_title:
        # 覆盖文档的默认标题
        app.env.titles[docname] = custom_title

def setup(app):
    app.connect('doctree-read', use_custom_title)

步骤3：确保启用MyST解析器 #

如果你的项目还没启用myst_parser，在conf.py的扩展列表里加上：

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

这样所有带有title元数据的Markdown文件，在toctree里都会显示自定义的标题，没有元数据的文件保持原有行为。

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