如何在不同子文件夹中统一引用同一个adoc包含文件？

方法1：命令行传递根路径属性 #

Asciidoctor支持通过命令行参数定义自定义属性，替代环境变量的作用：

• 在Linux/macOS下执行编译：

  asciidoctor -a my-root-dir="$MY_ROOT_DIR" your-document.adoc
  

• 在Windows下执行编译：

  asciidoctor -a my-root-dir=%MY_ROOT_DIR% your-document.adoc
  

• 对应的adoc文件引用写法：

  include::{my-root-dir}/.inc/include.adoc[]
  

方法2：固定编译基准目录+相对路径 #

如果能保证始终从项目根目录执行Asciidoctor编译命令，不管目标adoc文件在哪个子目录，都可以用相对于根目录的层级路径引用：

• 一级子目录的adoc文件：

  include::../.inc/include.adoc[]
  

• 二级子目录的adoc文件：

  include::../../.inc/include.adoc[]
  

• 可以在项目根目录写统一的编译脚本（比如build.sh或build.bat），避免手动切换目录的麻烦。

方法3：通过配置文件定义根路径 #

创建项目级的Asciidoctor配置文件，统一管理根路径属性：

1. 在项目根目录创建asciidoctorconfig.adoc，内容如下：

   :my-root-dir: .
   

2. 编译时指定配置文件：

   asciidoctor -C asciidoctorconfig.adoc your-document.adoc
   

3. adoc文件里的引用写法和方法1一致：

   include::{my-root-dir}/.inc/include.adoc[]
   

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