@kekoin

みんなで使おうAsciiDoc

Last updated at 2024-06-10Posted at 2024-05-29

viviONグループでは、DLsiteやcomipoなど、二次元コンテンツを世の中に届けるためのサービスを運営しています。
ともに働く仲間を募集していますので、興味のある方はこちらまで。

AsciiDoc使ったことありますか？

エンジニアの方であれば、Markdownは簡単なメモ程度からGitHubのREADME.mdまで、いろんな場面で使うことがあると思います。

これは、Markdownはよく使うけどAsciiDocは知らないよ、という人におくるAsciiDocのススメです。

私が趣味の開発で使っていて、あまりにも激アツなのでご紹介したくなりました！

AsciiDocとは

マークアップ言語の一種で、HTMLやPDF、TexやePubなんかにもレンダリングできる優れものです。
IT技術書で有名なO'Reillyでも、このAsciiDocで書かれた書籍があるとかないとか……

よく言われる表現力（フォーマットの自由さ）としてはこんな感じです。

XML > HTML > AsciiDoc > Markdown

AsciiDocはMarkdownのちょっと拡張版みたいな感じのイメージです。
できることの多さから、設計ドキュメントなどをAsciiDocで書く人も多いみたいですね。

どんなことができるの？

表がGood

カラム幅を指定可能
右寄せ、左寄せなどを指定可能
列、行の結合ができる
表の中に外部読み込みした画像を置ける（例では載せていないですが）

.結合＋箇条書例
[cols="1,2,>3"]
|====
|ほげほげ|ふがふが|ほにゃほにゃ
3+|列の横結合できる！
.2+|行の縦結合もできる！|2-1|右寄せもできるよ！
|2-2|
* なんと……
* 表の中で箇条書きができる！！
|====

Markdownの表は自由度が低いので、痒いところに手が届くAsciiDocはかなり使い勝手が良いです。

目次がGood

AsciiDocでは目次を作ることができます。

= asciidocの使い方

== asciidocとは？

=== asciidocの概要

== asciidocでできること

=== 表がすごい

=== 目次がつく

=== UMLがかける

アンカーリンクになっていて、押したらその章まで飛べるのもいいですね。

外部ファイル読み込みがGood

画像などもインクルード可能ですし、表に外部ファイルのCSVをインクルードして表示することもできます。
設計ドキュメント内でソースを参照したり、CSVからテストデータを引っ張ったり、色々とできることは思いつきそうです。

[source, dart]
----
include::domain.state.dart[lines=19..31]
----

文字色がGood

MarkdownだとHTMLを書かないと文字色はつけられませんがAsciiDocなら簡単です。
こういうのは地味にありがたいんですよね。

asciidocとは、誰でも使える [red]#軽量マークアップ言語# です！

UMLがGood

PlantUMLというダイアグラムを簡単に書けるツールがあるのですが、AsciiDocはそのPlantUMLを埋め込むことが可能です。
利用環境によっては多少の事前設定が必要だったりするのですが、VSCodeであれば拡張機能をインストールするだけです。
https://marketplace.visualstudio.com/items?itemName=jebbs.plantuml

シーケンス図

これは趣味のアプリ作成で使っているシーケンス図です。
文字だけでこんなにわかりやすい図が描けるの、すごくないですか？

クラス図

[plantuml]
----
class Animal {
  ほえる()
}

class Cat extends Animal {
  ほえる(にゃー)
}
class Dog extends Animal {
  ほえる(わんわん)
}
----

フローチャート

[plantuml]
----
digraph foo {
  node [style=rounded]
  チャート１ [shape=box]
  チャート２ [fillcolor=yellow, style="rounded,filled", shape=diamond]
  チャート３ [shape=record, label="{ a | b | c }"]

  チャート１ -> チャート２ -> チャート３
}
----