AsciiDoc で書いたドキュメントをPDFに変換する

概要

AsciiDoc で書かれたドキュメントをPDFファイルに変換するための設定についてのメモ。

環境

• Gradle：5.6

詳細

ディレクトリ構成

│
├ gradle
│　│
│　└ wrapper             .. asciidoctorビルド用jar
│
├ src
│　├ themes
│　│　│
│　│　├ custom-theme.yml .. pdfのstyle設定用ファイル
│　│　│
│　│　└ logo.png         .. ロゴ画像
│　│
│　└ index.adoc            
│
├ build.gradle           .. asciidoctorビルド設定ファイル
│
├ gradlew                .. asciidoctorビルド実行exe（unix系統用）
│
└ gradlew.bat            .. asciidoctorビルド実行exe（windows系統用）

• srcフォルダ配下のadocがビルドされる
• pdfのstyleを設定するファイルを用意する

ビルド設定

build.gradle

buildscript {
  ext {
    asciiDoctorGradlePluginVersion = "1.5.7"
    asciidoctorjDiagramVersion = "1.5.8"
    asciidoctorjPdfVersion = "1.5.0-alpha.15"
  }
  repositories {
    jcenter()
  }
  dependencies {
    classpath("org.asciidoctor:asciidoctor-gradle-plugin:${asciiDoctorGradlePluginVersion}")
    classpath("org.asciidoctor:asciidoctorj-diagram:${asciidoctorjDiagramVersion}")
    classpath("org.asciidoctor:asciidoctorj-pdf:${asciidoctorjPdfVersion}")
  }
}

apply plugin: 'org.asciidoctor.convert'
apply plugin: 'org.asciidoctor.gradle.asciidoctor'

asciidoctor {
  dependsOn 'clean'
  requires = ['asciidoctor-diagram'] // asciidoctor-diagram の利用設定
  backends = ['html5', 'pdf']        // htmlとpdfファイルを出力する設定
  sourceDir = file('src')            // ビルド対象のファイルを置くフォルダ
  outputDir = file('build')          // ビルド後のファイルが出力されるフォルダ
  separateOutputDirs = false
}

wrapper {
  gradleVersion = '5.6'
}

defaultTasks 'asciidoctor'

PDFスタイル設定（custom-theme.yml）

• PDF変換時のフォントなどを指定する設定ファイルを用意する
  • 詳しくは https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc を参考にする
  • 元にするスタイル設定はこちらから取得する

サンプルドキュメント（index.adoc）

index.adoc

:data-uri:
:pdf-style: ./themes/custom-theme.yml
:title-logo-image: image:./themes/logo.png[]
:toc: left
:sectnums:
:chapter-label:
:toclevels: 2
:toc-title: 目次
:figure-caption: 図

= タイトル

== TEST1
=== TEST2
==== TEST3
* 設定で目次や段落を自動的に作ってくれる
* toclevelsを2にしているため2段落（x.x）までの表題で目次が作成される

==== UML
* UMLの出力テスト

:imagesdir: /build
[plantuml, test-uml]
----
@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

Alice -> Bob: Another authentication Request
Alice <-- Bob: another authentication Response
@enduml
----

• 出力されるPDFは以下のようになる
  • 

まとめ

社内でのみ運用する仕様書だとHTMLであっても問題ないが、
顧客に納品するとなるとどうしてもそういうわけにはいかなくなってくる。
そういったときにasciidoctorj-pdfを使えばPDFに変換できるため便利だと思う。

仕様書などのドキュメントも、バージョン管理のしやすいテキストベースのもので作成できると
履歴管理などしやすいのでそうなっていけばいいなと思う。