raiki_dev’s blog

右も左も分かりませんが、よろしくお願いいたします。

Asciidocいいぞという話

markup asciidoc markdown

Asciidocに出会うまでの歴史

煩悩まみれでノート管理難民に

きっかけを遡ると新卒として部署に配属されたてのことから、いろいろ思考整理のメモなどをまとめるアプリを探してNotionに落ち着いたが、他人に文書を共有するときWeb表示可能ではあるが結局Notionというプラットフォームに依存することが気になっていた。 Notionに詳しい人はMarkdownとしてExportすることでいざという時に自分の文書として手元に永久保存できるのではないかと思うだろう。 しかし少し凝ったレイアウトや貼り付けファイル内容次第では使い物にならなかったり、HTML出力したときに今はどうか知らないがページのプロパティなどがデフォルトで表示されてということ満足するレベルではなかった。

つまるところ今後何があるか分からないので、自分用のメモであったり思考整理内容、欲を言えば報告資料や技術文書など資料にまとめるという行為に対して、ある程度ストレスなく万人が読めて、メモする行為自体もストレスにならない形を求めていた。 かつそれを汎用的な形で永久に保存し辞書のように参照できたらいいなとも考えていたのだ。 また、他人に共有するときにオフラインの資料として綺麗な見た目で提出できることも望ましい。

今自分で振り返ってみて、改めて強欲すぎないかと可笑しくなってくる。

Markdownでの実現可能性

ざっくりとそのような煩悩まみれの条件下のもとMarkdownの可能性を探り始めた。 Markdownという形が無くならない限りある程度汎用的に永久保存できそうではあったし、HTMLに変換することでMarkdownを知らない人や描画できる環境に無い人にも共有できるし、オフラインでも見てもらえるので良いかと考えた。 ただ、メモ的なものであればそれで十分ではあったが、真面目な文章量が多めの技術文書や調査資料を作成する際に、文書の全体像が分かりにくいという問題に直面した。

そこで文書の全体像が把握できるものを色々自身の経験より思い返してみると、Androidの個人開発をしていたときにお世話になっていたAndroiDeveloperという公式Webドキュメントを思い出した。 ページの左側がアウトラインになっており、全体を把握でき、クリックすると該当ページにジャンプしたり遷移したりすることができるのだ。

参考：https://developer.android.com/

求めるものが定まったところで、MarkDownがその要件を満たしてくれるのか調査した。 当然のことながら、独自MarkDownエディタや、プラグイン上での描画でOutlineが表示されているだけではNGであり、HTMLで表示したときにアウトラインを構築できるかどうかがポイントとなる。

色々調べた結果アウトライン表示できるものとして、以下候補が挙がった。

まずDocFx, docusaurus, honkitは基本的にローカルサーバを立ててブラウザからlocalhostに対してhtmlをブラウジングする形となる。 それでは、他人に文書を共有するときにあまりにも汎用性が低く表示してもらうためのストレスが大きいので当然却下。 ただ、honkitだけはexportしたhtmlファイルが./_bookというパスにあり、index.htmlを直接ブラウザで表示しても描画でき、UIとか操作感など文句が無いものであったように見えたため期待させられたが、ページ遷移などにfile:///パスを使ってるせいでCORSエラーが発生しており、ページ遷移など全く機能しなかったので使えなかった。

markdown-preview-enhancedはvscodeのプラグインであり、exportする形式としてhtmlを選択でき、exportされたhtmlはoutlineが表示されており、各セクションへのジャンプも可能であった。 これだと思い、しばらく使ってみた。 要件は満たしていたので、細かい部分には目を瞑りしばらく使っていて当然ある程度運用は出来た。 しかし私は上位互換に出会ってしまったのだ。 それがAsciidocであった。

Asciidocのことを書く前に、markdown-preview-enhancedでoutlineを表示するための私用のヘッダー記述を公開しているのでリンクを貼っておく。

Asciidocとの出会い

あるOSSのgithubソースをみたときに、readmeがmdではなくadocとなっていた。 これは何だと思い調べたのが出会い。

Asciidocの細かい利点については割愛するが、上述した懸念点を解消してくれた他に実際に触ってみて感じた私的大きなメリットは以下である。

  1. Markdown記法でも書ける
  2. include::ファイル名 で別のファイルの内容をその場に展開できる。
  3. 階層化したリストや見出しに番号を自動で振ることができる
  4. outlineもデフォルトで対応している
  5. github, gitlabが標準で描画対応している。

4についてはAsciidoctorというプラグイン依存の内容ではあるが、現状このプラグインが一強のようだ。 機能だけでいうとMarkdownの純粋な上位互換なんじゃないかと思う。

サンプルイメージは以下のような感じ。

プラグインだけで完結する簡単な環境

  1. vscode上に以下のプラグインを入れる

t.co

  1. コードブロックの表示にhighlight.jsを選択する（ほかの表示方法はRubyのインストールが必要） Highlight.js | Asciidoctor Docs

  2. pasteimageプラグインをいれて画像をコピペで貼り付けれるようにする Paste Image - Visual Studio Marketplace

私のテンプレートも載せておく

心残り

一度HatenaBlogにもAsciidocからエクスポートした記事を試しに載せた（ 意識高い系にならないように - raiki_dev’s blog ）が、画像や外部ファイルがローカルパス依存のためhtmlの中身だけをコピーだと当然だが、画像など見当たらない。 なのでブログなどに載せるとなると外部ファイル取り込みに関して制約が発生する。 この記事も迷ったが、画像を入れたかったのでブログに直接書いた。

また、縦型のDisplayで自分のブログを表示したときに、本文にアウトラインが食い込んでいたので、アウトラインを外す設定をした。この辺りは試行錯誤が必要かもしれない。

最低限画像をhtml内に組み込めるとなると幅が広がりそうだ。 一度htmlにエクスポートした文書に対して、html内の画像パスがローカルであれば、バイナリに変換するツールなどを時間があれば作ろうと思う。