单个reStructuredText文件转PDF：如何生成章节目录？

核心问题分析 #

你遇到的.. contents::未生效，本质是两个原因：一是rst文件内的章节结构未符合规范导致Pandoc无法识别层级，二是Pandoc默认处理逻辑需要额外参数来触发目录渲染。以下是具体解决步骤：

1. 修正rst文件的目录指令与章节结构 #

首先确保你的test.rst遵循reStructuredText的标题规范，同时正确配置.. contents::指令：

.. contents:: 文档目录
   :depth: 3  # 指定要包含的目录层级，3表示包含三级标题
   :local:    # 仅包含当前文件的内容，适合单文件场景

# 一级标题示例（下划线长度需与标题文本一致或更长）
第一章 入门指南
===============

## 二级标题示例
1.1 什么是reStructuredText
-------------------------
这是二级标题下的段落内容，用于测试目录层级。

### 三级标题示例
1.1.1 基本语法规则
~~~~~~~~~~~~~~~~~~
这是三级标题下的段落内容，会被纳入目录。

# 另一个一级标题
第二章 转换实践
===============

2.1 Pandoc转换配置
------------------
这是第二个二级标题的内容。

关键注意点：

• 标题下划线必须和标题文本长度匹配（或更长），Pandoc依靠这个识别标题层级
• :depth:参数控制目录显示的层级数，根据你的需求调整（比如设为2就只显示一、二级标题）

2. 修改Makefile中的Pandoc命令 #

在Pandoc转换时添加--toc-depth参数，确保和rst文件中.. contents::的:depth:一致，同时可以指定PDF引擎优化渲染（可选）：

PDFS := $(patsubst %.rst,%.pdf,$(wildcard *.rst))

all : $(PDFS)

%.pdf : %.rst
    # --toc-depth 对应rst中contents的depth参数，确保层级一致
    # 如果需要支持中文，添加 --pdf-engine=xelatex --variable mainfont="SimSun"
    pandoc $< -o $@ --from rst --toc-depth=3

clean:
    rm $(PDFS)

rebuild : clean all

3. 验证效果 #

运行make命令生成PDF后，你会看到：

• 文档开头出现包含所有指定层级标题的目录
• 目录中的条目可点击跳转至对应章节（PDF阅读器支持的前提下）

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