asciidoctor-gradle-plugin の使い方

google で「asciidoctor gradle plugin」で検索して表示される結果が古すぎて使い物にならなかったので、書いておくことにした。古いものベースで gradle を書いていたところ、DSL でわからないところがあったため、 github でコードを探したが見つからず混乱の原因になった。バージョン 1.5.8 とか 1.5.9 などについて書いてあるものは古い。最新は 3.1.0 である。

---

asciidoctor-gradle-plugin をプロジェクトに入れるには次を記述するだけでよい。

plugins {
  id "org.asciidoctor.jvm.convert" version "3.1.0"
}

Kotlin で書く場合はこうなる

plugins {
  id("org.asciidoctor.jvm.convert") version "3.1.0"
}

---

単一の html ページに出力しようとしていて、

include::sub-page.adoc[]

と別のファイルを入れ込もうとしてもプロジェクトのルートディレクトリーに sub-page.adoc がないというエラーが発生する。 include ディレクティブを解決するための設定は asciidoctor タスクにて設定する必要がある。

asciidoctor {
  baseDirFollowsSourceFile()
}

import org.asciidoctor.gradle.jvm.AsciidoctorTask

tasks {
  "asciidoctor"(AsciidoctorTask::class) {
    baseDirFollowsSourceFile()
  }
}

---

plantuml を記述すると、ドキュメントの図を描けて表現力があがる。そのためには AsciidoctorJExtension から拡張を入れる必要がある。

repositories {
  mavenCentral()
}

asciidoctorj {
  modules {
    diagram.use()
    diagram.version '1.5.16'
  }
}

repositories {
  mavenCentral()
}

asciidoctorj {
  modules {
    diagram.use()
    diagram.version("1.5.16")
  }
}