如何在AsciiDoc中创建左侧导航面板（非目录列表）

要实现类似官方文档的左侧层级导航面板，核心可通过两种方式实现，以下是具体方案：

方案一：使用Antora（官方文档同款，推荐） #

Antora是专为AsciiDoc打造的文档站点构建工具，默认自带左侧导航面板，步骤如下：

1. 初始化项目
   创建项目并安装依赖：

   mkdir my-docs-site && cd my-docs-site
   npm init -y
   npm install @antora/cli @antora/site-generator-default --save-dev
   

2. 定义导航结构
   在组件目录下创建nav.adoc，按层级编写导航项：

   * xref:intro.adoc[文档介绍]
   * xref:basic.adoc[基础用法]
     * xref:basic/syntax.adoc[核心语法]
     * xref:basic/format.adoc[格式规范]
   * xref:advanced.adoc[高级技巧]
   

3. 生成站点
   执行命令构建带左侧导航的完整站点：

   npx antora playbook.yml
   

方案二：自定义Asciidoctor HTML模板 #

若无需完整站点，可通过修改模板给单文档添加左侧导航：

1. 导出默认模板
   先获取Asciidoctor默认HTML模板用于修改：

   asciidoctor --dump-template html5 > custom-template.html
   

2. 插入导航面板代码
   在模板的<body>区域添加左侧导航容器，利用模板变量读取文档目录结构：

   <div class="sidebar-nav">
     <h3>目录导航</h3>
     {{#toc}}
       <ul class="nav-level-1">
         {{#each items}}
           <li><a href="{{url}}">{{text}}</a>
             {{#if items}}
               <ul class="nav-level-2">
                 {{#each items}}
                   <li><a href="{{url}}">{{text}}</a></li>
                 {{/each}}
               </ul>
             {{/if}}
           </li>
         {{/each}}
       </ul>
     {{/toc}}
   </div>
   

3. 用自定义模板编译文档
   指定模板生成带导航的HTML文档：

   asciidoctor -T custom-template.html your-doc.adoc
   

注意事项 #

• Antora适合管理多版本、多组件的大型文档，导航支持自动同步内容结构
• 自定义模板需具备基础HTML/CSS能力，可通过样式调整导航的外观布局

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