本来なら「Vagrant で Docker コンテナ立ち上げて Ansible でプロビジョニングして開発環境を用意しよう！」のその3を書くところですが。
今回は脱線して軽量マークアップ言語 AsciiDoc について普及したいと思います！
Wikipedia によると、軽量マークアップ言語とは次の通り。
軽量マークアップ言語（けいりょうマークアップげんご、英語: lightweight markup language）は、人間がシンプルなテキストエディタを使っての入力が容易になるように設計された、簡潔な文法をもつマークアップ言語である。
引用：『フリー百科事典 ウィキペディア日本語版』より。
エンジニア界隈で有名どころな軽量マークアップ言語といえば Markdown ですね。
https://ja.wikipedia.org/wiki/Markdown
特定のフォーマットに従って文章を書き、コンバータを通すことでよしなに見た目を整形してくれます。
自分もよく使っていますが、便利ですよね。
backlog や qiita や DropboxPaper 、 HackMD といったサービスでは Markdown で記事を書くこともできまし、 GitHub や GitLab ではトップディレクトリに README.md として Markdown ファイルを置いておけば自動的に整形して表示してくれます。
Markdown はとっても便利なんですけど、個人的にいくつか不満があります。
伝わるでしょうか、この思い。例えば *nix の man コマンドに出てくるオプションの説明欄ですね。
このような感じで -a の説明を書くときにいい感じの見た目にする書き方が Markdown にはありません。
見出しとしてしまうと、次の見出しが出てくるまでが一つのブロックとして扱われてしまうので期待通りにはなりません。
箇条書きという手もありますが、個人的にはインデントが揃わないので残念な気持ち。
表という手もありますが、正直 Markdown の表は書きづらいです。
上でも書きましたが、 Markdown の表は書きづらいです。
シンプルなところがポイントなのかもしれませんが、少し長めの文章を書いていると、こう、「うーん」という残念な気持ちになってきます。
また Markdown では表の内部で改行するには br タグをつける必要があります。
「つければ？」という感じですが、これもやはり煩雑な感じになってきて残念な気持ちになります。
そんな不満に AsciiDoc です！
AsciiDoc を使うと上記の不満は次のように書くことができます。
下記はキーワードの説明を書いた例です。
下記はテーブルの例です。
なんと、テーブルの中に箇条書きやテーブルの入れ子を作ることができます！
さらに設定をすれば PlantUML も書けちゃえます！
すごくないですか？
さぁ、この記事を読んで興味がわいた皆さん！ Let’s AsciiDoc !
「AsciiDoc イイね！早速使おう！」と思ったあなた！
そのモチベーションを持って、早速公式のユーサーマニュアルを見てみましょう！
こちらです！
https://asciidoctor.org/docs/user-manual/
ところで、リファレンスの目次の数を見てください。どう思います？
大項目だけで97あるのですが、すごく多いんですよね。。
「気合い、入ってます！」という感じ。
正直、これを読むくらいならワンピースを1巻から読んだ方が楽しいのでは？という(個人的な)気持ちです。
ということで。次からは自分が参考にしたサイトを紹介していきたいと思います！
下記は公式のクイックリファレンスです。(英語)
AsciiDoc Syntax Quick Reference
https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/
こちらを日本語訳したものが次のサイトです。 asciidoc で書かれているので、実際にどんな書き方をしているのか見たい場合は github を直接見るとよいでしょう。
(「結果を表示する」を押さないと、どのように表示されるか見えないのが玉に瑕)
Asciidoctor 文法クイックリファレンス(日本語訳)
https://takumon.github.io/asciidoc-syntax-quick-reference-japanese-translation/
Asciidoctor 文法クイックリファレンス(日本語訳) – github
https://github.com/Takumon/asciidoc-syntax-quick-reference-japanese-translation
下記は AsciiDoc の概要と記法について日本語でまとめられているサイトです。
AsciiDoc入門
https://qiita.com/xmeta/items/de667a8b8a0f982e123a
下記は公式サイトですが、クイックリファレンスよりも少し詳しく記載されています。(英語)
AsciiDoc Writer’s Guide
https://asciidoctor.org/docs/asciidoc-writers-guide/
下記は先ほどにも記載しました詳細なユーザーマニュアルです。 github のリポジトリもありますのであわせて記載しておきます。
Asciidoctor User Manual
https://asciidoctor.org/docs/user-manual/
Asciidoctor User Manual – github
https://github.com/asciidoctor/asciidoctor.org/tree/af96b33904e05a908bb14127a977458065018cc6
ユーザーマニュアルの最初の方に Markdown との比較がありますので、一読いただくとよいのではないでしょうか。
Asciidoctor User Manual – 1.5.3. Comparison by example
https://asciidoctor.org/docs/user-manual/#comparison-by-example
下記は有志の方が作られたオンラインデモと、その github サイトです。 AsciiDoc のエッセンスが詰まっていて「こんなことができる」というのがわかりやすいかと思います。
オンラインデモ
https://darshandsoni.com/asciidoctor-skins/
github サイト
https://github.com/darshandsoni/asciidoctor-skins/blob/gh-pages/index.adoc
最後に、オンラインデモをベースに個人的に作成したチートシートです。きまぐれで削除する場合があるのでお気をつけください。
https://yoshik159753.github.io/asciidoc-cheatsheet/
https://9bhttzm7x0w8.work/
下記は公式サイトより各種エディタ用エクステンションやプラグインに関する情報です。
Editing AsciiDoc with Live Preview
https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/
こちらを見ると、 atom / Visual Studio Code / Eclipse / IntelliJ IDEA と主要なエディタに対してエクステンションやプラグインがありますので、こちらを利用すれば出力もできるかと思います。(Visual Studio Code 以外は未確認)
また CLI が得意な方には、ユーザーマニュアルに CLI による入出力の章がありますのでこちらを参照してみてはいかがでしょうか。
https://asciidoctor.org/docs/user-manual/#cli-inputs-and-outputs
最後にいくつか補足事項です。
上記のリンク集を確認された方はおわかりかもしれませんが、 GitHub や GitLab は AsciiDoc をサポートしています。
なので、 README.md ではなく README.adoc をトップディレクトリに格納するとよしなに表示してくれます。
便利ですね。個人的には GitHub より GitLab のスタイルの方が好きです。
リンク集の中で asciidoctor という言葉が出てきます。
wikipedia 見ればわかることですが、 asciidoc と asciidoctor の関係は次のようになります。
asciidoc: オリジナル。軽量マークアップ言語としての名称。および、Python で書かれている翻訳ソフト。Python2 系の EOL に伴い、公式にて asciidoctor への移行を促していたが、最近 Python3 系でリブートしている模様。
asciidoctor: Ruby で書かれている翻訳ソフト。
なので asciidoc は形式(および Python の翻訳ソフト)を指し、 asciidoctor は翻訳ソフトのみを指している感じです。Unix と Linux, git と github の関係のような感じでしょうか。
リンク集にある個人的に作成したチートシートですが、実は3箇所ほど差異があります。
ビルド元ファイルは同一ですが、GitHub Pages で公開している方はローカルPCでビルドしたもの、独自ドメインで公開している方は AWS CodeBuild でビルドしたものです。
原因は調べてないですが、 asciidoctor のバージョンが違うのかもしれないですね。
お時間あれば探してみてください。
よしけー
