如何在adoc转docbook再转docx流程输出的docx文件中添加目录

你遇到的目录缺失问题，是因为asciidoctor生成的DocBook格式中的目录标记无法被pandoc直接识别转换为docx格式的目录，需要在pandoc转换环节主动开启目录生成功能。

方法1：修改pandoc转换命令（适配现有流程，最便捷） #

在你现有的pandoc命令中添加--toc参数即可自动生成目录：

pandoc -r docbook -t docx -o Document.docx index.xml --highlight-style espresso --toc

可选参数调整 #

• 调整目录显示深度：默认显示3级标题，可添加--toc-depth=N自定义，比如只显示到2级标题：

  pandoc -r docbook -t docx -o Document.docx index.xml --highlight-style espresso --toc --toc-depth=2
  

• 修改目录标题为中文：默认目录标题为英文Contents，可添加--variable toc-title="目录"修改：

  pandoc -r docbook -t docx -o Document.docx index.xml --highlight-style espresso --toc --variable toc-title="目录"
  

注意事项 #

• 确保Asciidoc文档中的:toc:声明放置在文档最顶部，前方无任何正文内容
• 确认Asciidoc中的标题层级正确（=对应一级标题、==对应二级标题，以此类推），pandoc会基于标题层级自动生成目录

替代方案：直接使用asciidoctor-docx转换 #

如果不想经过DocBook中间环节，也可以直接使用asciidoctor-docx插件完成转换，原生支持asciidoc的:toc配置：

1. 首先安装插件：gem install asciidoctor-docx
2. 执行转换命令：

   asciidoctor -r asciidoctor-diagram -r asciidoctor-docx -b docx index.adoc
   

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