Go to Qiita Advent Calendar 2024 Top
LoginSignup
15
13

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

More than 1 year has passed since last update.

@h1romas4(ひろましゃ)

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

Last updated at Posted at 2020-04-09

はじめに

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

こんな時に:

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

Screenshot from 2020-04-09 12-08-56.png

Screenshot from 2020-04-09 12-39-54.png

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

変換用ビルドスクリプト

asciidoctor-gradle-plugin v3.3.2 用の build.gradle を次の github リポジトリーに変換サンプル Asciidoc 文書とともに公開しています。

https://github.com/h1romas4/asciidoctor-gradle-template

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

リポジトリーごと Download ZIP 後、./gradlew docs もしくは .\gradlew.bat docs すると src/docs/asciidoc/ 配下に含まれている文書が HTML/PDF に変換されます。

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

変換後の文書サンプル

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

AsciidoctorとGradleでつくる文書執筆環境(HTML version)

AsciidoctorとGradleでつくる文書執筆環境(PDF version)

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

Screenshot from 2020-04-09 10-49-05.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. マインドマップ
    奥付

(2023-09 更新)

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

Gitpod 対応

クラウド IDE である Gitpod 向けに、リポジトリーには .gitpod.yaml が含まれています。

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

Open in Gitpod

本格的に使う場合は、ご自身の github アカウントにリポジトリーをコピーするなどしてお使いください。github の Use this template ボタンが便利です。

image.png

image.png

なお 2023/6 現在、Gitpod の無料枠は 50時間/月 までの利用となっており、git push 前の修正ファイルの維持はラストアクセスから 14日間となっているようです。 → Life of a Workspace

Codespaces 対応

クラウド IDE である Codespaces 向けに、リポジトリーには .devcontainer/devcontainer.json が含まれています。

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

Open in GitHub Codespaces

image.png

asciidoctor-gradle-plugin について

Asciidoctor Gradle Plugin Suiteは Gradle から AsciidoctorJ を簡潔な DSL で呼び出すためのプラグインです。

準備したリポジトリーの build.gradle（本記事用にコメントを追加） は次のようになっています。修正する場合や、新規作成する場合の参考になれば。ドキュメントと見比べると分かりやすいと思います。

(2023-06-12 更新)

  • Asciidoctor と asciidoctor-gradle-plugin を最新までアップグレード。
  • PDF 日本語禁則処理で asciidoctor-nabetani を使わせていただくようにデフォルト設定。
  • asciidcoter-pdf を 1.6.2 までアップグレード（自分の使う範囲で asciidoctor-nabetani が動作することを確認）
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 {
    // ローカル Ruby gem を追加（diagram SVG 用のフォントパッチ）    
    asciidoctorGems files('gradle/repos/gem/prawn_svg_font_patch-0.1.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 {
    version = '2.5.6'
    // 利用モジュール
    modules {
        diagram.use()
        diagram.version '2.2.8'
        // 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'
}

謝辞

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

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

15
13
13

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
15
13

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?