asciidoctor.jvm.convert 2.4.0+Spring Docs 2.0.5：include指令解析及页面加载问题求助

问题根源 #

出现“Unresolved directive”错误及child.html加载失败，核心原因是：

• Asciidoctor转换时无法定位child.adoc文件，导致include指令未被解析
• Gradle配置未正确覆盖所有需要处理的Asciidoc源文件，或文件路径配置错误

具体修复步骤 #

1. 确认文件路径结构 #

确保index.adoc与child.adoc的相对路径正确：

• 若两者在同一目录（如src/docs/asciidoc），include指令写为include::child.adoc[]
• 若child.adoc在子目录（如src/docs/asciidoc/sections），指令需写为include::sections/child.adoc[]

2. 修正Gradle Asciidoctor配置 #

更新配置，确保所有相关Asciidoc文件被纳入转换流程，同时保证资源复制完整：

def snippetsDir = file("build/generated-snippets")

test {
    useJUnitPlatform()
    outputs.dir snippetsDir
}

asciidoctor {
    configurations "asciidoctorExtensions"
    // 指定Asciidoc源文件根目录（根据你的实际路径调整）
    sourceDir = file("src/docs/asciidoc")
    // 包含所有adoc文件，确保child.adoc被处理
    sources {
        include '*.adoc'
        // 若有子目录，可添加 include '**/*.adoc' 递归扫描
    }
    inputs.dir snippetsDir
    dependsOn test

    doLast {
        copy {
            from "${asciidoctor.outputDir}/html5"
            into "$buildDir/resources/main/public/docs"
            // 复制所有生成的HTML及依赖静态资源
            include "**/*.html", "**/*.css", "**/*.js"
        }
    }
}

3. 验证转换结果 #

• 执行./gradlew asciidoctor，查看控制台无路径错误提示
• 检查build/asciidoc/html5目录，确认index.html已正确解析include内容，或child.html已生成
• 启动应用后访问/docs/index.html，确认child内容正常加载

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