ASCIIDOC: "Unresolved directive in...": "<stdin>" "or "index.adoc"

Question

我是 ASCIIDOC 的新手，只是想知道以下问题的来源。

设置：

带有最新 ASCIIDOC 插件的 Intellij
新设置 asciidoctor-maven-plugin 与 preserveDirectories = true

我是这样组织我的 asciidocs 的：

footer.adoc
header.adoc
index.adoc
子文件夹
- index.adoc

生成的文档如下所示：

footer.html
header.html
index.html
子文件夹
- index.html

现在，如果我希望 subfolder/index.html 也包含页眉和页脚，我想我需要将 include::../header.adoc[] 写入 adoc 文件，这对Intellij 插件。但是在生成的html中你会发现如下错误：

<p>Unresolved directive in index.adoc - include::../header.adoc[]</p>

因此，当我将以下内容写入 adoc 文件时：include::header.adoc[] 生成的 html 很满意，但 Intellij ASCIIDOC 插件显示错误：

Unresolved directive in <stdin> - include::header.adoc[]

我只是想知道这是 Intellij 插件团队还是 Maven 插件团队的错误。或者有人可以解决这个问题？

还有一个小问题：是否可以将 Maven 插件配置为不生成 header-/footer.htmls，因为它们已经包含在实际的 htmls 中了？

Answer 1

我没有使用 maven 插件的经验，但我对 AsciiDoc、IntelliJ 插件和 Gradle 插件有很多经验。

IntelliJ 插件行为正确。当您转换 /subfolder/index.adoc 时，包含是相对于此文件解析的，因此包含 include::../header.adoc 是正确的。

您描述您没有指定为 maven 插件呈现哪个文件（header.adoc 已转换）。这可能是maven插件的问题：

您只需指定源路径，所有文档都是相对于此源路径呈现的，因此 /subfolder/index.adoc 的源路径有误。

使用Gradle插件，您可以指定要转换的所有文档。这也可以避免 header.adoc 转换。从 Maven 插件文档中我看到你只能指定一个文件。

考虑到这一点，我建议更改文件结构，将所有要转换的文件放在一个文件夹中。然后您可以指定此文件夹，并且不应转换其他文件。这也应该用相对路径名解决你的问题：

/src/docs/
      |
      +-common/
      |    |
      |    +-header.adoc
      |    +-footer.adoc
      +-chapters/
      +-main/
         |
         +-index1.adoc
         +-index2.adoc

Answer 2

我知道这已经晚了，答案可以在 https://spring.io/guides/gs/testing-restdocs/ 的“使用代码段”部分的 Spring.io restdoc 手册的文档中找到示例 gradle 项目

maven插件配置应该是这样的：

            <plugin>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctor-maven-plugin</artifactId>
            <version>1.5.8</version>
            <executions>
                <execution>
                    <id>output-html</id>
                    <phase>prepare-package</phase>
                    <goals>
                        <goal>process-asciidoc</goal>
                    </goals>
                    <configuration>
                        <sourceHighlighter>coderay</sourceHighlighter>
                        <backend>html</backend>
                        <attributes>
                            <toc/>
                            <linkcss>false</linkcss>
                            <snippets>
                                ${project.build.directory}/generated-snippets
                            </snippets>
                        </attributes>
                    </configuration>
                </execution>
            </executions>
        </plugin>

ASCIIDOC: "Unresolved directive in...": "<stdin>" "or "index.adoc"

ASCIIDOC: "Unresolved directive in...": "<stdin>" "or "index.adoc"

intellij-idea

asciidoc

maven