Markdown の問題点

ドキュメントや仕様書などを書くのに便利な Markdown ですが、仕様書でよく登場する一覧表などの表現がイマイチでやりたいことができないことがあります。
また Markdown は方言が結構あり、使用するサービスやコンバーターに合わせた記述をしなくてはならないことも多々あります。

AsciiDoc とは

AsciiDoc は Markdown に似たプレーンテキストで記述する言語で、HTML5や電子書籍、manページやPDFに変換ができます。
Markdown よりも多機能で表現も豊富です。

また、Ruby の gem で asciidoctor というプリプロセッサが配布されていて、AsciiDoc からHTMLやPDFへの変換できる環境も揃っています。
今回は Markdown ではできない AsciiDoc の注目機能の紹介をしたいと思います。

AsciiDoc の注目機能

• 目次が自動で作れる
• 表紙が作れる
• テーブルのセル結合ができる
• テーブルの幅や表現など細かく設定できる
  • テーブルを外部のCSVファイルで記載できる
• 画像やテーブルのキャプション表現ができる
• 外部ファイルをインポートできる
• 吹き出し付きソースコードができる
• 番号付きリストが途切れない
• キーボードショートカット表現ができる
• 実は Markdown 記法も使える（asciidoctor 限定）

目次が自動で作れる

AsciiDoc では見出しから自動でページ番号付き（ページ内リンクも！）の目次を作成する機能が備わっています。
Markdown でもできなくはないですが手動で管理だったり、VSCode の機能拡張を駆使して目次を半手動で生成（日本語のページ内リンクに難あり）でした。

:toc:
:toclevels: 5
:toc-title: 目次

表紙が作れる

こちらは asciidoctor-pdf 独自の機能です。
以下の指定をするだけで、ロゴを表示した表紙が簡単に作成できます。
以前は表紙のPDFを別途作成して、Markdown→PDF変換→表示PDFとマージでした。

:author: 株式会社 ジークス
:revdate: 2019/11/25
:revnumber: 1.0
:lang: ja
:doctype: book
:pdf-style: theme.yml
:pdf-fontsdir: fonts
:title-logo-image: image:img/logo.svg[]

テーブルのセル結合ができる

仕様書やマニュアルを書いているときに欲しい機能です。
パイプの前に結合の指定を書きます。数値のあとに+で結合、数値の前に.があれば列の結合で、なければ行の結合です。
Markdown になない機能ですが、もはや魔術のような記述です・・・この辺はトレードオフでしょうかね。

cols では表の揃えやイタリック・強調表示などが指定できますが、列の幅も指定できて便利です。

[options="header",cols="1,5,2,2",width="100%"]
|===
|No|名称|種別|備考
|1 .2+<.^|Alpha|A|
|2|A'|
|3|Bravo|B|
|===

画像やテーブルのキャプション表現ができる

掲載した画像や表のキャプションがあると、ドキュメントとして引き締まる感じがします。
Markdown でも表現はできますが CSS などの調整が必要です。

.図1
image:https://placehold.jp/360x150.png[]

外部ファイルをインポートできる

include 構文を使用して外部ファイルをインポートできます。
地味な機能ですが冗長で読みにくくなりがちな AsciiDoc のドキュメントを章やセクションごとに分けて管理できるので、全体の見通しが良くなり管理しやすくなります。
またソースコードや定義など、繰り返し差し替えが起こる文書は外部ファイルを差し替えるだけですみます。

include::hoge.adoc[]

プログラムのソースコードファイルを直接 AsciiDoc に読み込むことができます。

[source,javascript]
-------------------------------
include::externalfile.js[]
-------------------------------

外部CSVを読み込んでテーブルの表現ができます。

[format="csv",cols="^,<,<,>,<",options="header"]
|===================================================
No,イシュー名,ラベル,担当者,期限
include::issues.csv[]
|===================================================

吹き出し付きソースコードができる

ソースコードの行に番号を振ることができるので行単位での詳しい説明が必要な場合に便利です。

[source,ruby]
----
require 'sinatra' // <1>

get '/hi' do // <2>
  "Hello World!" // <3>
end
----
<1> Library import
<2> URL mapping
<3> HTTP response body

番号付きリストが途切れない

これも地味な機能ですが使ってみるとかゆいところに手が届く機能です。
Markdown では番号付きリストの間にソースコードを挟んだりすると、次のリストは番号がリセットされてしまいます。
AsciiDoc では + でつないだ場合は一連のリストとして処理してくれるようです。
ソースコードを交えながら手順を記載するのに便利ですね。

1. List item one.
+
List item one continued with a second paragraph followed by an
Indented block.
+
2. List item two.

キーボードショートカット表現ができる

マニュアル作成に嬉しい機能です。

|===
|ショートカット|目的

|kbd:[F11]
|全画面表示

|kbd:[Ctrl+T]
|新規タブを開く

|kbd:[Ctrl+Shift+N]
|シークレットウインドウを開く

|kbd:[Ctrl + +]
|ズーム
|===

実は Markdown 記法も使える（asciidoctor 限定）

一部のシンタックスが Markdown と互換がある他、見出し・コードブロック・引用・水平線などは Markdown の形式に対応しているため、Markdown からの移行もスムーズです。

ここまで個人的に注目したい機能を紹介してきましたが、かなり高機能で使いごたえがありますね。
その他にも便利そうな機能がまだまだあります。

• 索引が簡単に作れる
• 注釈が簡単に作れる
• 組み込み環境属性が使える

まだまだ使いこなせるところまではきていませんが、積極的に仕事に取り込んでいきたいと思います！