如何在Asciidoc多页文档左侧:toc:上方插入图片？

有几种可行的实现方式，最直接的是通过自定义Asciidoctor模板来实现：

方法一：修改Asciidoctor HTML模板 #

1. 导出默认模板到本地目录：

   asciidoctor --export-template-dir ./custom-templates
   

2. 在导出的模板文件（通常是default.html.erb）中，找到左侧TOC容器的起始代码（类似<div id="toc" class="toc">），在该标签之前插入图片的HTML代码：

   <div class="toc-logo">
     <img src="./assets/your-logo.png" alt="品牌标识" style="width: 100%; margin-bottom: 1.5rem;">
   </div>
   

   注意：图片路径要使用相对路径，确保所有页面都能访问到（比如把图片放在生成的HTML目录下的assets文件夹中）。
3. 生成手册时指定使用自定义模板：

   multidoctor-multipage --template-dir ./custom-templates your-main-doc.adoc
   

方法二：使用Asciidoctor全局自定义HTML片段 #

如果不想修改模板，也可以通过全局注入HTML的方式：

1. 创建一个包含图片代码的文件toc-header.html：

   <div class="toc-logo">
     <img src="./assets/your-logo.png" alt="品牌标识" style="width: 100%; margin-bottom: 1.5rem;">
   </div>
   

2. 在你的主Asciidoc文件顶部添加以下配置，将片段注入到TOC区域前：

   :toc: left
   :header-include: ./toc-header.html
   

   注：部分版本可能需要结合Asciidoctor的docinfo功能，创建docinfo.html文件并写入图片代码，然后在adoc中启用:docinfo: shared。

方法三：修改multidoctor-multipage生成脚本 #

如果你的项目使用自定义生成脚本，可以在脚本中添加逻辑，在每个生成的HTML文件的TOC节点前插入图片代码。比如用Ruby或Python脚本遍历生成的HTML文件，查找TOC的位置并插入图片标签。

内容的提问来源于stack exchange，提问作者Inti Garcés