こちらの記事は、GitHubでAsciiDocを使って文章を作成する手順です。ローカル環境(PC)にてAsciiDocを利用する際には、Dockerを利用する別記事をご覧ください。
確か、大学卒業後に働き始めたのが2001年。となると、来年で20年、社会人成人になります。（といいつつ、まだまだ落ち着きませんが）
何度か転職し、今は起業して好き勝手やっていますが、20年前から仕様書（ドキュメント）作成はWordやExcelのままです。
入社当初、会社の教育担当の方に、プログラマーの仕事の半分以上はドキュメント作成だと言われたような記憶があります。
勝手に、「脱Excel宣言」をしている私にとって、ドキュメントをExcelで作成するというのは、あってはならないことなのですが、なかなか脱することができず現在に至ります。
しかし、この度、少しボリュームのあるドキュメント作成が必要になり、いよいよ本気でドキュメント作成の方法を考えることにしました。
そこで辿り着いたのが「asciidoc」です。
目次
asciidocとは
asciidocは決まった記法でテキストで記述していくと、自動的に見出しや箇条書き、表などにきれいに整形されてドキュメントとして出力してくれる便利ツールです。
Markdownに似ていますが、Markdownよりも表現力があるらしく、LaTeXほど複雑ではないようです。
（LaTeXは大学の卒業論文以来、使ったことがないので忘れましたが）
以前にも、asciidocは使ったことがあるのですが、なぜかいまのPC環境ではうまく動作しなくなっており、他のことに手を取られ放置していました。
今回、新ためてasciidocの環境を構築しようとしたのですが、次の条件を課しました。
- 複数台のPCで編集したい。（もっといえば、複数人で同じドキュメントを編集したい）
- PDF出力した際には、どのPCで出力しても全く同じフォント等になるようにしたい。
- ガントチャートを作りたい（GUIではなくテキストベースで）
こんな条件を考えながら検索したところ、こちらのサイトがありました。
見つけたとき、久しぶりに「すげーな！」と声が出ました。
上記ページから過去記事に遡って設定をしていくと、すごいことが出来ます。
この方法でいくと、asciidocのドキュメントは全てGitHubで管理され、もちろん変更履歴も残り、複数PC、複数人でも作業ができ、PDF出力もできます。ガントチャートやUMLのあたりは少し工夫しました。
なんといっても、asciidocからHTML、PDFへの変換をローカルのPCではなく、GitHubのGitHub ActionsでDockerを立ち上げ、そこの環境で変換処理を行ない、出力されたファイルをダウンロードして使うというのが、目から鱗でした。
以前、勤めていた会社では130人くらいのプロジェクトのリリース作業において、わからないなりにツール等を調べ自動化をするなどの作業もした経験があり、そういう作業が結構好きだったのですが、ここ近年は数人での作業のためそこまでツール探しなどをしていませんでした。
あっという間に、置いていかれてます。怖い。
さて、GitHubの設定は上記ページの内容に沿って行えばできます。
ローカルPCでは、Gitが利用できるようになれば、あとはテキストエディタとかは何でもよく、GitでPushすると、自動的にGitHub Actionsが動いて、asciidocからhtmlやPDF（asciidoctor-pdfを使う）を出力してくれます。
ローカル環境の設定
ただ、ローカルでファイルを編集しているときに、最終的にどんな見た目になるのかプレビューをしたいことがあります。私はVisual Studio Codeを使い始めたので、Extentionsで「asciidoctor-vscode」をインストールして、編集しながらリアルタイムにプレビューできるようにしました。
asciidoctorはdiagramでUMLなども記述することができるのですが、この中にガントチャートは含まれておらず、別の方法を検討する必要がありました。
そこで、「PlantUML」を導入し、テキストベースでガントチャートやUMLを作成し、PlantUMLを使ってSVG画像に変換し、その画像をasciidocに挿入するという方法です。
SVG画像の日本語フォントがPDFで文字化け
ここでさらに問題があり、SVG画像に日本語フォントが含まれていると、最終的に出力されるPDFのSVG画像が文字化けしていました。そのあたりも、有益な情報を提供してくださっている下記サイトのおかげて解消できました。
https://qiita.com/koara-local/items/e7a7a7d68a4f99a91ab1
https://qiita.com/Shallot/items/0b5076c98155cb6f38a0
当方の環境では出力されたSVG画像に含まれるフォントが「serif」となっていたため、それに合わせて、config.rbの設定を追加しました。
ガントチャートの書式についてはこちらを参考に作成しました。
https://plantuml.com/ja/gantt-diagram#ca6909da4e1482ab
asciidocの表紙をかっこよく
これで、ほぼ満足のいくPDFが作成できたのですが、もう少し表紙をかっこよくしたいということで、こちらを参考に手直ししてみました。
https://backport.net/blog/2018/12/08/asciidoctor_pdf_title_customize/
タイトルを途中で改行したかったのですが、上記サイトの方法ではうまくいかず、タイトルの改行したい位置に pass:[<br/>] を入力すると、改行できました。
asciidocでプレゼン用スライド作成
これで、一通りうまく動くようになり満足していたのですが、さらに欲がでてきまして、同じ環境でプレゼン用のスライドも作成したくなりました。
asciidocからスライドに変換する、「asciidoctor-revealjs」があります。こちらも、GitHub Actionsで動かすDocker環境に入っているので、asciidocからreveal.js形式のhtmlに変換することができます。
ただ、出力されるのはhtmlのみですので、reveal.jsに必要なcssやjsは別途用意する必要があります。
https://github.com/hakimel/reveal.js/
これで、ブラウザを使ってプレゼンテーションできる環境も整いました。さらに、〇〇〇.htmlの後に「?print-pdf」をつけてブラウザからアクセスし、ブラウザの印刷機能から「PDF保存」をすると、プレゼンテーションのデザインのままのPDFファイルを出力することもできてしまいます。セミナー参加者の方々に配布する資料にはこの方式がよいと思いました。
https://revealjs.com/pdf-export/
最後に
ということで、ドキュメント作成のためにWordやExcelを使う必要がなくなり、さらにプレゼンテーション作成にPowerpointを使う必要がなくなるという、当初想定よりもかなり発展した結果になり、ひとりで大満足しています。
こんなことが、無料でできてしまうのがすごいです。
各種情報を提供してくださっている皆さんに感謝しかありません。