如何在Doxygen自定义\page页面的doc-content后插入指定div标签

问题说明 #

需要在Doxygen生成的HTML文档中，仅对\page命令创建的自定义页面，在ID为doc-content的div后直接插入ID为numbered-sections的div容器，结构示例如下：

<div id="doc-content">
<div id="numbered-sections">
<!-- 搜索筛选窗口等内容 -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- 自定义页面的章节、内容等 -->

</div><!-- numbered-sections -->
</div><!-- doc-content -->
<!-- 页脚部分 -->
...

背景是想给自定义页面的章节、子章节、子子章节添加自动编号，但全局CSS方案会影响“命名空间成员”“类”“文件”等自动生成的代码页面，因此需要通过这个自定义容器限定样式范围。

之前尝试在.dox文件中直接用div包裹内容，但该div会被嵌套到<div class="textblock">中，出现时机过晚，无法控制目录样式，还会被重复添加，达不到需求。

可行实现步骤 #

1. 导出Doxygen默认HTML模板 #

在命令行执行以下命令，将默认HTML模板导出到本地目录（比如doxygen_templates）：

doxygen -w html header.html footer.html stylesheet.css

如果找不到page.html模板（该模板专门用于渲染\page自定义页面），可从Doxygen安装目录的share/doxygen/templates路径下复制。

2. 修改page.html模板结构 #

打开page.html，找到包含doc-content的代码块，原结构大致为：

<div id="doc-content">
  $content
</div>

修改为：

<div id="doc-content">
  <div id="numbered-sections">
    $content
  </div><!-- numbered-sections -->
</div>

这样修改只会作用于\page创建的自定义页面，不会影响类、文件、命名空间等自动生成的页面（这些页面使用各自独立的模板）。

3. 配置Doxygen使用自定义模板 #

在Doxygen配置文件Doxyfile中添加以下配置项，指向你修改后的模板文件：

HTML_HEADER = header.html
HTML_FOOTER = footer.html
HTML_STYLESHEET = stylesheet.css
HTML_EXTRA_FILES = page.html

确保文件路径与实际存放位置一致。

4. 添加章节编号CSS样式 #

在stylesheet.css中写入针对#numbered-sections的编号规则，示例如下：

#numbered-sections h2.section {
  counter-increment: section;
  counter-reset: subsection;
}
#numbered-sections h2.section::before {
  content: counter(section) ". ";
}
#numbered-sections h3.subsection {
  counter-increment: subsection;
  counter-reset: subsubsection;
}
#numbered-sections h3.subsection::before {
  content: counter(section) "." counter(subsection) ". ";
}
#numbered-sections h4.subsubsection {
  counter-increment: subsubsection;
}
#numbered-sections h4.subsubsection::before {
  content: counter(section) "." counter(subsection) "." counter(subsubsection) ". ";
}

该样式仅会对自定义页面内的章节生效，不会干扰其他自动生成页面的标题。

验证效果 #

重新运行Doxygen生成文档后，检查自定义页面的HTML结构，可确认numbered-sections容器已正确嵌套在doc-content之后，章节编号样式正常生效。

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