AsciidoctorとGradleでつくる文書執筆環境 v4

## はじめに

[asciidoctor-gradle-plugin](https://github.com/asciidoctor/asciidoctor-gradle-plugin)を活用して Asciidoc 形式の文書を Gradle を使って簡単に HTML/PDF 文書に変換できるビルドテンプレートをつくってみました。

こんな時に:

* ビルド依存が「Java 11 以上が導入されていること」のみであることから、多くの Java ソフトウェア開発現場のドキュメント作成に。
* クラウド IDE の [Gitpod](https://gitpod.io/) 及び GitHub [Codespaces](https://github.co.jp/features/codespaces) に対応。ブラウザーさえあればどこでも、プレビューしながらの Asciidoc 文書の執筆・ビルドが可能。薄い技術書の執筆に。

![Screenshot from 2020-04-09 12-08-56.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/102286/6fcb0618-646a-a5ad-b399-5f3fb5d7f27f.png)

![Screenshot from 2020-04-09 12-39-54.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/102286/3f16c06f-e802-0a32-2d8b-5d904366c78e.png)

この記事がみ​な​さ​ん​の​執​筆​活​動​の​お​手​伝​い​に​な​れ​ば​幸​い​で​す。

## 変換用ビルドスクリプト

[asciidoctor-gradle-plugin v3.3.2](https://asciidoctor.github.io/asciidoctor-gradle-plugin/development-3.x/user-guide/) 用の `build.gradle` を次の github リポジトリーに変換サンプル Asciidoc 文書とともに公開しています。

> [https://github.com/h1romas4/asciidoctor-gradle-template](https://github.com/h1romas4/asciidoctor-gradle-template)
>
> AsciidoctorとGradleでつくる文書執筆環境

リポジトリーごと [Download ZIP](https://github.com/h1romas4/asciidoctor-gradle-template/archive/master.zip) 後、`./gradlew docs` もしくは `.\gradlew.bat docs` すると `src/docs/asciidoc/` 配下に含まれている文書が HTML/PDF に変換されます。

本リポジトリーにはフォントや CSS スタイル・PDF テーマ、Asciidoctor 日本語特有の不具合のパッチなどが含まれていますので Java 11 以降が入っている環境であればすぐにビルドできると思います。

## 変換後の文書サンプル

「AsciidoctorとGradleでつくる文書執筆環境」リポジトリー自体の使い方を書いた文書がサンプル文書となっています。詳しいビルドの仕方やカスタマイズ方法は次のリンクから参照ください。

[AsciidoctorとGradleでつくる文書執筆環境(HTML version)](https://h1romas4.github.io/asciidoctor-gradle-template/index.html)

[AsciidoctorとGradleでつくる文書執筆環境(PDF version)](https://h1romas4.github.io/asciidoctor-gradle-template/index.pdf)

リポジトリーには、Visual Studio Code を使った執筆を想定していくつかのワークスペース設定（`.vscode/`）を事前に含めており、vscode 上でプレビューしながら Asciidoc の編集が可能です。

![Screenshot from 2020-04-09 10-49-05.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/102286/b188380c-1d5d-8425-d0de-122ca9c6cf24.png)

## 目次とアップデート内容

> 目次
>
> はじめに
>     ライセンス
>     謝辞
> 1. Asciidoc 文書変換用スクリプトを使う準備
>     1.1. Java 実行環境の導入（macOS / Linux）
>     1.2. Java 実行環境の導入（Windows）
> 2. Asciidoc から HTML/PDF 文書を作成する
>     2.1. サンプル文書の変換を試す
>     2.2. 変換後の文書
>     2.3. テキストエディタで Asciidoc 文書を編集する
>     2.4. 文書のファイル構成
>     2.5. 執筆の開始
>     2.6. 執筆のイテレーション
>     2.7. 文書の Git 管理
>     2.8. クラウド環境による執筆
>     2.9. クラウド環境でのファイル保存と執筆の再開
>     2.10. GitHub Actions によるビルド
> 3. Asciidoc 記法
>     3.1. ドキュメントヘッダーとセクションタイトル
>     3.2. 段落
>     3.3. 文章中のテキストフォーマット
>     3.4. 文書中の相互参照
>     3.5. 外部リンク
>     3.6. 引用
>     3.7. 画像
>     3.8. ソースコードシンタックスハイライト
>     3.9. メニュー・ボタン
>     3.10. ファイルインクルード
>     3.11. 表形式
>     3.12. リスト
>     3.13. 脚注
>     3.14. 改ページ・ブレイク表現
>     3.15. ラベル文言
>     3.16. コラム表現
>     3.17. コメント行
> 4. ダイアグラム記法
>     4.1. シーケンス図
>     4.2. フォルダ・ファイルツリー
>     4.3. 数式
>     4.4. ブロック図
>     4.5. メモリーマップ
>     4.6. ネットワーク構成図
>     4.7. システム構成図
>     4.8. タイミングチャート
>     4.9. マインドマップ
> 5. Gradle ビルドの詳細
>     5.1. Gradle タスクの実行方法
>     5.2. tasks タスク
>     5.3. docs タスク
>     5.4. checkPdfInfo タスク
>     5.5. checkSyncImage タスク
>
> 奥付

(2023-09 更新)

- サポートする Java の最低バージョンを 8 から 11 に変更しました。
- 「2.8. GitHub Actions によるビルド」を追記しました。
- 「4. ダイアグラム記法」内のサンプルをいくつか追加しました。
- GitHub Action ビルドが Ubuntu、macOS、Windows とそれぞれの Java 11, 17 の計 6環境をサポートするようになりました。
- GitHub Codespaces サポートを追記しました。
- Git の導入を追記しました。
- 文書中で使われている Asciidoc 記法の解説を追記しました。

(2025-02-27 更新)

* Gradle に未使用画像検出と PDF メタ情報取得用のユーティリティータスク追加と解説の追記。
* Draw.io サポートを追加。

## Gitpod 対応

クラウド IDE である [Gitpod](https://gitpod.io) 向けに、リポジトリーには `.gitpod.yaml` が含まれています。

次のボタンを押すと Gitpod 上でビルドが走り（初回は 3分程度）、ローカルビルド環境の準備なしにブラウザー上で執筆ができます。画像ファイルなどはブラウザーにドラッグアンドドロップでアップロードすることができます。

[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/h1romas4/asciidoctor-gradle-template)

本格的に使う場合は、ご自身の github アカウントにリポジトリーをコピーするなどしてお使いください。[github の Use this template](https://github.com/h1romas4/asciidoctor-gradle-template) ボタンが便利です。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/102286/dbb0b1b7-2898-3563-7d1d-5f3c7b5f5bc3.png)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/102286/f16554af-de16-1a9d-bb8d-1ce43ea37149.png)

なお 2023/6 現在、[Gitpod の無料枠](https://www.gitpod.io/pricing/)は 50時間/月 までの利用となっており、git push 前の修正ファイルの維持はラストアクセスから 14日間となっているようです。 → [Life of a Workspace](https://www.gitpod.io/docs/life-of-workspace/)

## Codespaces 対応

クラウド IDE である [Codespaces](https://github.co.jp/features/codespaces) 向けに、リポジトリーには `.devcontainer/devcontainer.json` が含まれています。

Gitpod と同様に次のボタンから執筆・ビルド環境の使用が可能です。

[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/h1romas4/asciidoctor-gradle-template)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/102286/fbf789e4-370b-a81c-390f-afe07987acee.png)

## asciidoctor-gradle-plugin について

[Asciidoctor Gradle Plugin Suite](https://asciidoctor.github.io/asciidoctor-gradle-plugin/development-3.x/user-guide/)は Gradle から [AsciidoctorJ](https://github.com/asciidoctor/asciidoctorj) を簡潔な DSL で呼び出すためのプラグインです。

準備したリポジトリーの `build.gradle`（本記事用にコメントを追加） は次のようになっています。修正する場合や、新規作成する場合の参考になれば。[ドキュメント](https://asciidoctor.github.io/asciidoctor-gradle-plugin/development-3.x/user-guide/)と見比べると分かりやすいと思います。

(2023-06-12 更新)

* Asciidoctor と asciidoctor-gradle-plugin を最新までアップグレード。
* PDF 日本語禁則処理で [asciidoctor-nabetani](https://github.com/nabetani/asciidoctor-nabetani) を使わせていただくようにデフォルト設定。
* asciidcoter-pdf を `1.6.2` までアップグレード（自分の使う範囲で asciidoctor-nabetani が動作することを確認）

(2025-02-27 更新)

* asciidoctor-gradle-plugin の依存が解決できなくなっていたため修正。
* AsciidoctorJ、asciidoctor-diagram を動作する最大までアップデート。

```groovy
// asciidoctor-gradle プラグインから依存する okhttp ライブラリの id が変更されて
// 解決できなくなっているのをパッチする定義
buildscript {
    configurations.classpath {
        resolutionStrategy.dependencySubstitution {
            // https://github.com/asciidoctor/asciidoctor-gradle-plugin/issues/679#issuecomment-2371010585
            // fix dependencies (Could not find io.github.rburgst:okhttp-digest:1.10)
            substitute module('com.burgstaller:okhttp-digest') using module('io.github.rburgst:okhttp-digest:1.21')
        }
    }
}

plugins {
    // 利用する asciidoctor-gradle プラグインを宣言
    id 'org.asciidoctor.jvm.convert' version '3.3.2'
    id 'org.asciidoctor.jvm.pdf' version '3.3.2'
    // Ruby gem プロキシープラグイン
    id 'org.asciidoctor.jvm.gems' version '3.3.2'
}

repositories {
    mavenCentral()
    // Asciidoctor 用の追加 gem をプロキシーするための
    // org.asciidoctor.jvm.gems プラグイン用の宣言
    ruby.gems()
}

dependencies {
    // 追加 gem 登録
    // https://github.com/h1romas4/asciidoctor-gradle-template/tree/main/gradle/repos/gem
    // ローカル Ruby gem を追加（diagram SVG 用のフォントパッチ）    
    asciidoctorGems files('gradle/repos/gem/prawn_svg_font_patch-0.2.0.gem')
    // ローカル Ruby gem を追加（asciidoctor-nabetani を使わせていただいて日本語禁則処理などを拡張）
    // only asciidoctor-pdf 1.5.3 - 1.6.2
    asciidoctorGems files('gradle/repos/gem/asciidoctor-nabetani-0.1.4-ruby25-patched.gem')
    // for another asciidoctor-pdf version
    // asciidoctorGems 'rubygems:asciidoctor-pdf-linewrap-ja:0.7.1'
}

// HTML 変換用定義
asciidoctor {
    // 必要な Ruby gem をビルド前に配置するための dependsOn    
    dependsOn asciidoctorGemsPrepare
    baseDir file('src/docs/asciidoc')
    sources {
        include 'index.adoc'
    }
    // 画像リソースを定義（build/ にコピーされる）    
    resources {
        from('src/docs/asciidoc') {
            include 'Chapter*/images/*'
        }
    }
    // CSS を指定（.html の先頭に追記される）    
    asciidoctorj {
        attributes 'stylesdir': '@style',
            'stylesheet': 'asciidoctor.css'
    }
}

asciidoctorPdf {
    // 必要な Ruby gem をビルド前に配置するための dependsOn
    dependsOn asciidoctorGemsPrepare
    baseDir file('src/docs/asciidoc')
    // PDF 用のフォント定義
    fontsDir file('src/docs/asciidoc/@font')
    sources {
        include 'index.adoc'
    }
    // PDF テーマを指定
    asciidoctorj {
        attributes 'pdf-themesdir': "@style",
            'pdf-theme': 'pdf-theme.yml'
            // When using the asciidoctor-pdf standard ward-wrap
            //, 'scripts': 'cjk'
    }
}

// AscidoctorJ の設定定義
asciidoctorj {
    // not working v2.5.10 Upgrade to JRuby 9.4.2.0
    version = '2.5.9'
    // 利用モジュール
    modules {
        diagram.use()
        diagram.version '2.3.1'
        // If asciidoctor-nabetani is used,
        // asciidoctor-pdf must be specified as 1.5.3 - 1.6.2.
        pdf.version '1.6.2'
    }
    // JRuby Asciidoctor 呼び出し時の -r 指定
    requires = [
        'asciidoctor-diagram',
        'prawn_svg_font_patch',
        // only asciidoctor-pdf 1.5.3 - 1.6.2
        'asciidoctor/nabetani',
        // for another asciidoctor-pdf version
        // 'asciidoctor-pdf-linewrap-ja',
    ]
    attributes 'source-highlighter': 'rouge'
}
```
## 謝辞

本​文​書​の​手​順​の​実​装​で​あ​る​ビ​ル​ド​ス​ク​リ​プ​ト​や​テー​マ​で​は​次​の​プ​ロ​ダ​ク​ト​と​技​術​資​料​が​使​わ​れ​て​い​ま​す。

* Font
  * 源​真​ゴ​シッ​ク​ - SIL Open Font License 1.1 - http://jikasei.me/font/genshin/
  * 源​様​明​朝​ - SIL Open Font License 1.1 - https://github.com/ButTaiwan/genyo-font
  * Ricty Diminished - SIL Open Font License 1.1 - https://github.com/edihbrandon/RictyDiminished
  * Morisawa BIZ UDGothic - SIL Open Font License 1.1 - https://github.com/googlefonts/morisawa-biz-ud-gothic
  * Morisawa BIZ UDMincho - SIL Open Font License 1.1 - https://github.com/googlefonts/morisawa-biz-ud-mincho
  * Open Iconic - MIT License - https://github.com/iconic/open-iconic/
* Asciidoc
  * Asciidoctor - MIT License - https://asciidoctor.org/
  * Asciidoctorj - Apache License 2.0 - https://github.com/asciidoctor/asciidoctorj
  * Asciidoctor.js - MIT License - https://asciidoctor.org/docs/asciidoctor.js/
  * Asciidoctor PDF - MIT License - https://asciidoctor.org/docs/asciidoctor-pdf/
  * Asciidoctor Gradle Plugin Suite - Apache License 2.0 - https://github.com/asciidoctor/asciidoctor-gradle-plugin
  * asciidoctor-pdf-linewrap-ja - MIT License - https://github.com/fuka/asciidoctor-pdf-linewrap-ja
  * asciidoctor-nabetani - MIT License - https://github.com/nabetani/asciidoctor-nabetani
* Diagram
  * PlantUML - Multi(MIT/Apache/BSD/EPL/GPLv3/LGPL) - https://github.com/plantuml/plantuml
  * ditaa - LGPL-3.0 license - https://github.com/stathissideris/ditaa
  * Draw.io - Apache License 2.0 - https://github.com/jgraph/drawio
  * vscode-drawio - GPL-3.0 license - https://github.com/hediet/vscode-drawio
* Build Tool
  * SDKMAN - Apache License 2.0 - https://sdkman.io/
  * Gradle - Apache License 2.0 - https://gradle.org/
* Text Editor
  * Visual Studio Code - Microsoft - https://code.visualstudio.com/
  * asciidoctor-vscode - MIT License - https://github.com/asciidoctor/asciidoctor-vscode
  * vscode-paste-image - MIT License - https://github.com/mushanshitiancai/vscode-paste-image
  * vscode-plantuml - MIT License - https://github.com/qjebbs/vscode-plantuml
* Guide
  * asciidoctor-pdf​で​かっ​こ​い​い​PDF​を​作​る​ - https://qiita.com/kuboaki/items/67774c5ebd41467b83e2

素​晴​ら​し​い​成​果​を​公​開​さ​れ​て​い​る​み​な​さ​ま​に​感​謝​し​ま​す。