Asciidoc 문서 작성을 위한 프로젝트 경로 설정 팁

eclipse의 AsciiDoctor Editor를 사용하면서 설정한 내용임

asciidoc 문서 작성을 위해 프로젝트를 설정하면서 예제 소스를 include 하기 위해 다음과 같이 설정하였다.

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>${asciidoctor.maven.plugin.version}</version>
    <dependencies>
        <dependency>
            <groupId>org.springframework.restdocs</groupId>
            <artifactId>spring-restdocs-asciidoctor</artifactId>
            <version>${spring-restdocs.version}</version>
        </dependency>
    </dependencies>
    <executions>
        <execution>
            <id>asciidoc-to-html</id>
            <phase>prepare-package</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>html5</backend>
                <sourceHighlighter>coderay</sourceHighlighter>
                <preserveDirectories>true</preserveDirectories>
                <outputDirectory>src/main/resources/static</outputDirectory>
                <attributes>
                    <java-version>${java.version}</java-version>
                    <spring-restdocs-version>${spring-restdocs.version}</spring-restdocs-version>
                    <thymeleaf-version>${thymeleaf.version}</thymeleaf-version>
                    <basedir>${project.basedir}</basedir>
                </attributes>
            </configuration>
        </execution>
    </executions>
</plugin>

maven의 기본 제공 변수인 project.basedir를 asciidoc의 attribute로 넘겨준 후 asciidoc에서는 다음처럼 _attributes.adoc 문서에 변수를 선언하였다.

:sources-root: {basedir}/src
:resources: {sources-root}/main/resources
:resources-test: {sources-root}/test/resources
:java: {sources-root}/main/java
:java-test: {sources-root}/test/java

실제 사용하는 문서엔 다음처럼 _attributes.adoc 문서를 include 하였다.

include::{docdir}/_attributes.adoc[]
= 개발 문서

== 소개

개발 문서 설명

== 사용

properties 설정 예제

[source,properties]
----
include::{resources-test}/example/application.properties[tags=example]
----

이 경우 빌드된 결과물엔 올바르게 include 된 properties 예제가 보이지만 eclipse의 asciidoc editor에선 아래처럼 include 실패 처리로 보였다.

Unresolved directive in 대상문서.adoc - include::{resources-test}/example/application.properties[tags=example]

이유는 maven의 basedir 변수를 asciidoc editor에서 인식하지 못해서였다.

같은 이유로 spring rest docs를 쓰는 경우 제공받는 snippets 변수도 인식하지 못해 snippets 문서를 바로 볼 수 없다.

하지만 asciidoc의 기본 attribute는 올바르게 인식한다

https://asciidoctor.org/docs/user-manual/#env-attributes

Asciidoctor User Manual

이를 사용해서 변수 경로를 잡아주면 eclipse asciidoc editor에서도 바로 include 해서 확인할 수 있다.

:basedir: {docdir}/../../../
:snippets: {basedir}/target/generated-snippets
:sources-root: {basedir}/src
:resources: {sources-root}/main/resources
:resources-test: {sources-root}/test/resources
:java: {sources-root}/main/java
:java-test: {sources-root}/test/java 

asciidoc의 docdir을 기준으로 나머지 변수들의 path를 잡아주면 editor에서 바로 include 해서 볼 수 있다.