Asciidoc

MarkdownユーザーがAsciidocを試してみた｜使いやすさ・欠点・移行の所感 この記事でわかること MarkdownとAsciidocの主な違い Asciidocを使って感じたメリット・デメリット 実際の使用例と学習コストの印象 Markdownからの移行はおすすめできるのか？ Markdownの限界 Markdownで記事をずっと書いてきたが、そろそろ限界を感じていた。ルビが振れない。表が書きにくい。数式が表示できない。…そんな中で見つけたのが「Asciidoc」だった。 はじめは軽い気持ちだった。「ちょっと試してみるか」程度で始めたものの、いざ書き始めてみると、予想以上にしっくりきた。「これ、最初からこっちで書いていればよかったのでは？」とすら感じるほどだった。Asciidocの思想は、“なんとなく書ける”Markdownとは違い、“最初から構造的に書く”という方向に向いている。 使い慣れているMarkdownと比べて何がどう違い、どこに惹かれたのかを、ここに記録しておく。 MarkdownからAsciidocに興味を持った理由 Markdownは軽量で便利だが、「構造化された長文」を扱うには力不足だと感じるようになった。特に以下の点で不満があった： 表記の自由度が低い（脚注・ルビ・図番号など） 表が複雑になると地獄（パイプ区切りの視認性） 数式を書こうとするとKaTeXやMathJax頼りで面倒 ファイル構造やテンプレートとの連携に限界がある そんな中で「Asciidocは本格的な技術ドキュメントのために作られた」「見出し構造や属性が自然」「PDFやHTML、EPUBにも出力可能」といった紹介を見て、試してみたくなった。 各記法の詳細等は、Qiitaなどで調べればいくらでも出てくるので割愛するが、以下に実際に使ってみて感じたことを記す。 Asciidocを使って感じた4つのメリット 1. 見出しやリストのネストが、MediaWiki記法に近い Asciidocでの記法 == 見出し * 箇条書き ** ネスト1 *** ネスト2 Markdownのように見出しに#を使うか、asciidocのように=を使うかは、単なるルールの違いのため、どちらが良いとは言えないが、個人的にWikipediaなどのMediaWiki記法には馴染みがあるため、asciidocのように見出しに=を使うというのは、書く上で慣れていて嬉しい。逆に、MediaWiki記法に慣れた状態から、初めてMarkdownを触ったときは、#を使うのに戸惑ったくらいだ。 箇条書き及びネストについては、asciidocの仕様はMediaWiki記法そのものである。個人的にMarkdownのネストの仕様は好きでは無かった。Markdownでは、箇条書きをネストする場合、以下のように空白文字でインデントする必要がある。空白文字でのコントロールは視認性に劣ると感じている。 Markdownでの記法 * 箇条書き * ネスト1 * ネスト2 2. テーブルがCSV形式で書ける Asciidocでの記法 [format="csv", opstions="header"] |====== a, b, c 1, 2, 3 4, 5, 6 |====== csv形式で書けるのが地味に嬉しい。行数・列数が一目瞭然である。以下のようなMarkdownでの記法も悪い訳では無いが、どのパイプ文字「|」の内側にいるかを意識しないと、プログラミング言語における括弧閉じ忘れのように、意図しない挙動になりがちだ。 Markdownでの記法 |a |b |c | |---|---|---| |1 |2 |3 | |4 |5 |6 | 3. ルビが振れる Asciidocでの記法 ...