AsciiDoc使ってみた

こんにちわ。コロナウイルスの影響で電車がガラガラの日々が続いていましたが、GW明けから徐々に出勤している人が増えているみたいですね。
電車混まないでえええ！！ということで、テックブログ今週の担当はuraです。

ドキュメント作るのつらい

皆さんは仕様書やマニュアルなどのドキュメントを作りますか？
私は現在受注プロジェクトのPMをしており、頻繁にドキュメントを作る機会があります。
一般的に、ドキュメントはWordやExcel等で作成するかと思います。WordやExcelは見やすいですよね。好きですか？私は嫌いです。

  • Gitで履歴管理しても簡単に文章を検索できない。差分も見えない。
  • チームで同じファイルを同時に編集しづらい。（GoogleDocsを使えばなんとかなるけど）
  • 書式を整えるのが面倒。気づいたら一部だけフォントが異なるとかよくある。
  • 顧客用のドキュメントであれば、修正の度にファイルを送信する必要がある。
ではどうするか？Markdownで作成してGitで管理しよう。
いちいちファイルを送るのは面倒なので、GitにプッシュしたらHTMLに変換してWebページに公開しよう。

いや、でもMarkdownだとテーブルのセル結合すらできないから、ちょっと複雑なドキュメントになると表現力が足りない・・・。

そんなことを考えているときに見つけたのが、今回のテーマのAsciiDocです。

AsciiDocとは？

Asciidocは軽量マークアップ言語の一つです。Markdownの仲間ですね。
以下のような採用事例があります。

Markdownと比較すると以下のような点が優れています。

  • テーブルのセル結合ができる
  • 相互参照が使える
  • 外部ファイルを読み込める（ソースコードをそのまま読み込んで表示したり、分けて作成したドキュメントをマージしたり・・・）
  • PlantUMLを直接書ける

使ってみる

それではさっそく使ってみます。

セクション

「=」の数で表現します。
== セクション1
=== セクション1.1
==== セクション1.1.1
== セクション2
== セクション3

リスト

「*」の数で表現します。
* リスト1
* リスト2
** インデント
*** さらにインデント

テーブル

[cols="1a,1a,1a",options="autowidth"]
|===
|1A|1B|1C
2+|「数値+」で横結合|2C
.2+|「.数値+」で縦結合|3B|3C
|4B
|* 4C
* リストを
* 入れることも可能
|===

画像

image::https://techblog.imagemagic.jp/wp-content/uploads/2018/11/%E6%8E%A1%E7%94%A8%E3%83%90%E3%83%8A%E3%83%BC.png[alt=代替テキスト, width="200" align="center"]

アンカー

アンカーは二重の「[」で表現します。
[[hogehoge]]

リンク

link:https://imagemagic.jp/recruit/[イメージ・マジックではエンジニアを募集中です。]

<<hogehoge, アンカーへのリンクは二重の「<」で表現します。>>

外部ファイルの読み込み

include::hogehoge.adoc[]

まとめ

AsciiDocの特徴や簡単な使い方について紹介しました。
現在マニュアル作成で使っていますが、やはりWordよりはラクをさせてもらっています。

インストール方法や詳しいリファレンスについては公式サイトをご覧ください。
カテゴリー: URA