使用Asciidoctor JVM Convert 2.4.0时Include子ADOC文件失败求助

问题根源 #

浏览器报错的本质是Asciidoctor在编译index.adoc阶段就没找到child.adoc/child1.adoc，导致未处理的include指令被保留到生成的HTML中，和后续复制HTML文件的步骤无关。替换buildDir为project.layout解决的是路径弃用问题，不影响adoc文件的编译查找逻辑。

解决方案 #

1. 确认被包含文档的路径正确性 #

• 检查index.adoc中的include路径：
  • 如果child.adoc和index.adoc在同一目录，指令应为include::child.adoc[]
  • 如果子文档在子目录，需写相对路径，比如include::subdir/child.adoc[]
• 确保child.adoc/child1.adoc确实存在于Asciidoctor默认的源文件目录（默认是src/docs/asciidoc），或你自定义的源目录下。

2. 配置Asciidoctor的源文件范围 #

如果你的adoc文件不在默认目录，或需要包含多个子目录的文档，修改asciidoctor任务的源文件配置：

test {
  useJUnitPlatform()
  outputs.dir snippetsDir
}

asciidoctor {
  configurations "asciidoctorExtensions"
  inputs.dir snippetsDir
  dependsOn test

  // 指定adoc源文件目录（根据实际路径调整）
  sourceDir = file('src/docs/asciidoc')
  // 确保所有需要的adoc文件被纳入编译范围
  sources {
    include '**/*.adoc'
  }

  doLast {
    copy{
      from (layout.buildDirectory.dir('asciidoc/html5')) // Gradle 8.x推荐的layout写法
      into layout.buildDirectory.dir('resources/main/public/docs')
      include "**/*.html"
    }
  }
}

3. 标记所有adoc文件为任务输入 #

让Gradle检测到adoc文件的变化，确保编译时能正确识别所有依赖文档：

asciidoctor {
  // 新增：将所有adoc源文件作为任务输入
  inputs.files fileTree(dir: sourceDir, include: '**/*.adoc')
  
  // 其余配置保持不变
  configurations "asciidoctorExtensions"
  inputs.dir snippetsDir
  dependsOn test
  sourceDir = file('src/docs/asciidoc')
  sources {
    include '**/*.adoc'
  }

  doLast {
    copy{
      from (layout.buildDirectory.dir('asciidoc/html5'))
      into layout.buildDirectory.dir('resources/main/public/docs')
      include "**/*.html"
    }
  }
}

4. 验证编译过程 #

直接执行./gradlew asciidoctor，查看控制台输出。如果编译阶段出现找不到子文档的错误，说明路径或源目录配置仍有问题，根据报错信息调整即可。

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