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

技術文書を書く環境が欲しくなり、VS Code と Gradle を使って Asciidoc 文書を執筆する環境を整えてみました。 お手軽に構成できて、300ページくらいの文書でも耐えられそうです。 🙂

VS Code でリアルタイムプレビューしながら Asciidoc 文書を執筆し、最後に HTML/PDF 文書にすることができように仕込んだ Gradle ビルド、フォントや CJK パッチ、.vscode 設定などをパッケージして github で公開しています。

https://h1romas4.github.io/asciidoctor-gradle-template/index.html

本文書は Asciidoc とその Ruby による実装である Asciidoctor を用いて Asciidoc 文書を執筆する環境を構築する手順を示します。実行環境は Windows、Linux、macOS の各 OS に対応しています。

上記のサイト(Asciidoc 文書のサンプルになっています)で詳しく手順を書いていますが、基本的にリポジトリを取得し、文書を書いて、 ./gradlew docs するだけでいい感じに Asciidoc を HTML/PDF 文書に変換して公開できるようになっています。

PDF 文書は次のようなものが出力されます。

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

https://h1romas4.github.io/asciidoctor-gradle-template/index.pdf

PDF に関しては本文フォントを明朝体にできるとより技術書らしくなると思うのですが、残念ながら prawnpdf ライブラリが OpenType に対応していないため導入を断念しました。しかし、対応は進んでいるようなので期待します。

https://github.com/prawnpdf/ttfunk/issues/53

Hey there maintainers! I’ve been working for the last several months on supporting OpenType fonts, which really just means supporting the CFF font table.

さて、今回このプロジェクトを作成するにあたり初めて Asciidoc の書式を全て確認しましたが、表現力が高く、思ったことは思った通り書けばよい感じなのでお気に入りました。 😀

リポジトリを github に置けば Github Pages ですぐ綺麗な文書を公開できるようになりますので、良ければお試しください!

このエントリーをはてなブックマークに追加

7 thoughts on “AsciidoctorとGradleでつくる文書執筆環境

  1. 知人からこちらを教えていただき試しています。
    私は日頃の設計書に関する悩みを解消する方法を模索しているしがないSEです。
    設計書にはいくばくかの図を埋め込む可能性がありますが、UML は PlantUML があるので、このテンプレートに asciidoctorj-diagram を組み込んで試したいと思ったのですが、いかんセンチ知識不足でして、自分ではおいそれと追加することが、未だできません。。。
    どのようにすれば良いかご教示いただけるとありがたいです。

  2. 素晴らしい環境をありがとうございます。
    お伺いしたい、ご相談したい事項があります。
    asciidoctor-pdfに関して、表組の中で文字を書くと、日本語の禁則処理がかからないようです。
    以下の作者の方に、以下のプログラムでは修正いただいたのですが、
    https://github.com/fuka/asciidoctor-pdf-linewrap-ja/issues/1#event-1847471497
    それをこの環境に組み込むことは可能でしょうか?
    当方、あまり詳しくなくよくわかりません。ご教示いただけると助かります。
    よろしくお願いします。

  3. コメントありがとうございます。

    表組の禁則処理について気が付きませんでした。お教えいただいた asciidoctor-pdf-linewrap-ja に禁則処理パッチを変更して取り込むことができると思います。

    修正してコミットしたいと思いますので数日お待ちいただければと思います。

  4. 早速にありがとうございます。
    迅速に対応検討いただいてありがとうございます。お時間のある時でかまいませんので、よろしくお願いいたします。

  5. すみません、もう一点気がついたことです。
    PDFの表紙のバージョンの表記が、
    バージョン unspecified,
    となってしまいます。
    これはサンプルで提供していただいている、
    https://h1romas4.github.io/asciidoctor-gradle-template/index.pdf
    においても同様です。
    これはなにか対策をするとなおるものでしょうか?
    自分でもいろいろと記述を試してみましたがだめでした。
    度々ですみませんが、ご教示あるいは何か修正策があれば、修正をご検討いただけると助かります。
    よろしくお願いいたします。

  6. 宮沢さん

    asciidoctor-pdf-linewrap-ja の取り込みをやってみたのですが、使用している asciidoc か Ruby のバージョンの関係かエラーがでて単純な入れ替えだとうまく動作させることができませんでした。

    実は、利用している asciidocj の gradle プラグインが先日アップデートして 1系から 2系になっていましてこちらなら動くかもなのですが、かなり API が変更されているためちょっと修正に時間がかかりそうです。

    自分も本件気になっていまして、再び取り組んでみますのでまた少々お待ち頂ければと思います!(unspecified の件も合わせて修正されるのではないかと思っています)

コメントを残す

メールアドレスが公開されることはありません。