みんなで使おうAsciiDoc

:::note info
viviONグループでは、DLsiteやcomipoなど、二次元コンテンツを世の中に届けるためのサービスを運営しています。
ともに働く仲間を募集していますので、興味のある方は[こちら](#一緒に二次元業界を盛り上げていきませんか)まで。
:::

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

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

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

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

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

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

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

```markdown
.結合＋箇条書例
[cols="1,2,>3"]
|====
|ほげほげ|ふがふが|ほにゃほにゃ
3+|列の横結合できる！
.2+|行の縦結合もできる！|2-1|右寄せもできるよ！
|2-2|
* なんと……
* 表の中で箇条書きができる！！
|====
```
Markdownの表は自由度が低いので、痒いところに手が届くAsciiDocはかなり使い勝手が良いです。

![Untitled.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/84371/4ea9dbb9-97ae-cdf8-3439-bb9a048d704c.png)

## 目次がGood :thumbsup: 
AsciiDocでは目次を作ることができます。
```markdown
= asciidocの使い方

== asciidocとは？

=== asciidocの概要

== asciidocでできること

=== 表がすごい

=== 目次がつく

=== UMLがかける
```

アンカーリンクになっていて、押したらその章まで飛べるのもいいですね。
![Untitled (1).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/84371/86e16d52-6528-1b56-aa7c-f33019cc44d4.png)

## 外部ファイル読み込みがGood :thumbsup: 
画像などもインクルード可能ですし、表に外部ファイルのCSVをインクルードして表示することもできます。
設計ドキュメント内でソースを参照したり、CSVからテストデータを引っ張ったり、色々とできることは思いつきそうです。
```markdown
[source, dart]
----
include::domain.state.dart[lines=19..31]
----
```

![Untitled (2).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/84371/ba3334fc-4f7f-14c5-8936-6afd7676a027.png)

## 文字色がGood :thumbsup: 
MarkdownだとHTMLを書かないと文字色はつけられませんがAsciiDocなら簡単です。
こういうのは地味にありがたいんですよね。
```markdown
asciidocとは、誰でも使える [red]#軽量マークアップ言語# です！
```

![Untitled (3).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/84371/1b964155-9410-3713-6c55-5791eca6073e.png)

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

### シーケンス図
これは趣味のアプリ作成で使っているシーケンス図です。
文字だけでこんなにわかりやすい図が描けるの、すごくないですか？
![スクリーンショット 2024-01-21 22.05.39.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/84371/fa5a1710-590e-9ff5-db37-bf4c04ace55c.png)

### クラス図
```markdown
[plantuml]
----
class Animal {
  ほえる()
}

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

![Untitled (4).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/84371/9a020fbe-bb62-679e-df37-6869db29d29b.png)

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

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

![Untitled (5).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/84371/e34c1989-dab8-083f-a0bd-232f69da8b04.png)

### PlantUMLで描くことのできるUML（UML以外も）
AsciiDocが設計ドキュメントでよく使われる理由がここにあります。
一般的に利用されるダイアグラムは、ほぼ網羅されているのではないでしょうか。

- シーケンス図
- ユースケース図
- クラス図
- オブジェクト図
- アクティビティ図
- コンポーネント図
- 配置図
- 状態遷移図（ステートマシン図）
- タイミング図
- JSON Data
- YAML Data
- Network diagram (nwdiag)
- ワイヤーフレーム
- アーキテクチャ図仕様及び記述言語 (SDL)
- Ditaa
- ガントチャート
- マインドマップ
- WBS 図 (作業分解図)
- AsciiMath や JLaTeXMath による、数学的記法
- ER 図

## GitHub上での参照がGood…:question: 
私がGitLabを使っている都合上、GitLab上ではPlantUMLの表示まで確認できたのですが、GitHubで可能かどうかは試していません……
ちょっと調べてみたらGitHubリポジトリのREADME.mdにAsciiDocを使ってみたって人がいるのでたぶんできると思います。

（これはGitLab上）
![Untitled (6).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/84371/9992a026-532e-d569-f63e-0bda74cd98a1.png)

# まとめ
## AsciiDocのメリット
- 文章中の上付き文字や下線の設定あり
- 表のセルを結合可能
- 表のセル内で箇条書き可能
- 自動的に目次ができる
- 文字に色がつく
- 外部ファイルをインクルード可能
- PlantUMLでUMLがかける
- テキストベースだから変更管理がしやすい
    - Gitなどかでバージョン管理できる！:tada:

## AsciiDocのデメリット
- Markdownと比べるとやや複雑
- 利用者が少なくて流行ってない :cry:
- 図とかUMLとかやろうとすると色々インストールが必要なことがある
    - Ruby で Asciidoctor をインストールしてエディタと連携
        - VSCodeなら拡張機能の設定で:ok: 

# 最後に
AsciiDocがもっと流行っていろんなサービスで使えるようになればいいなと思っています。
Gitリポジトリでドキュメント管理したいときなど、選択肢としてアリではないでしょうか！

:pencil: みんなで使おうAsciiDoc！ :pencil:

# 参考文献
https://takumon.github.io/asciidoc-syntax-quick-reference-japanese-translation/


# 一緒に二次元業界を盛り上げていきませんか？
株式会社viviONでは、フロントエンドエンジニアを募集しています。

https://vivion.jp/recruit/

また、フロントエンドエンジニアに限らず、バックエンド・SRE・スマホアプリなど様々なエンジニア職を募集していますので、ぜひ採用情報をご覧ください。