如何在reStructuredText中引入文件时调整章节层级？

标准reStructuredText的.. include::指令本身没有直接调整引入内容章节层级的选项，但有两种实用方法能满足你的需求，无需修改原文件：

方法1：用Sphinx的toctree替代include（推荐，适用于Sphinx构建的文档） #

如果你的文档是用Sphinx构建的，直接把include换成toctree，通过嵌套结构和参数自动调整层级：

Main title
==========

Subtitle
--------
.. toctree::
   :hidden:  # 隐藏toctree本身的条目，只展示文件内的标题
   :maxdepth: 3

   file1  # 这里写文件名，不用加.rst后缀

.. include:: file2.rst

这样file1.rst里的2级标题会自动降级为3级，嵌套在Subtitle这个2级标题下，完全匹配你的新结构需求。

方法2：构建时动态替换标题下划线（适用于纯docutils场景） #

如果不用Sphinx，可以在构建流程里加个临时替换步骤，把目标文件的2级标题下划线（---）换成3级的（~~~），生成临时文件后再引入，构建完成后删除临时文件。

比如写个Makefile片段：

build-docs:
	# 临时替换file1的标题下划线
	sed 's/^---$$/~~~/' file1.rst > file1_temp.rst
	# 生成HTML文档
	rst2html index.rst output.html
	# 删除临时文件
	rm file1_temp.rst

然后修改主文件的include指向临时文件：

Main title
==========

Subtitle
--------
.. include:: file1_temp.rst

.. include:: file2.rst

这样原文件完全不用改动，就能实现层级调整。

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