log.pocka.io

Docsifyでお手軽ドキュメント作成

Created at
Updated at

まえがき

この記事はめんどうなドキュメント作成を、ビルド不要かつ Markdown だけで済ませられるツールの紹介記事です。導入方法からどんなドキュメントに向いているか等を記載しています。

想定読者

  • Markdown について知ってる
  • Markdown とか知らないけど手軽にドキュメント作りたい
  • Sphinx のようなドキュメント作成ツールはいいけど環境構築とビルドが面倒...

Docsify - ビルド不要なドキュメントジェネレータ

IT, 特に Web 系において最近はドキュメントをソースからビルドして HTML として出力する、というのが多くなってきているかと思います。 この手法は VCS で管理できたり、ホスティングによる共有が可能といったメリットがあります。

しかし、その大きな特徴である「ビルドする」というステップが大きなデメリットになりがちなのです。 例えば、初期構築時のビルド環境とコマンドの整備、運用時にはどこでビルドをするのかといった問題が出てきます。 また、こういったツールの多くはコマンドを「インストール」して使わせるものが多く、自動ビルド環境の構築や複数人での開発時に多大なオーバヘッドとなりがちです。

これらの「ビルド」というステップに起因した種々の問題を解決するために、「ビルドせずにソースからドキュメントを生成する」ツールが現れ始めました。

今回紹介する Docsify はその中のひとつです。

動作サンプル

公式サイト自身が Docsify を使って生成されています。 また、Showcase ページに Docsify を用いて作成されたドキュメントが多数あるので参考になるかと思います。

導入方法

NOTE: npm の v5.2.0 で導入されたnpxというコマンド(機能)を使っています。npm のバージョンが古い場合は npm を更新するか、nvmやnを使って Node.js 自体のバージョン管理をできるようにすることをおすすめします。

基本的には公式のQuick Startを読めば全てわかりますが、セットアップコマンドに関しては公式のグローバルインストール方式はおすすめできないので以下のコマンドを叩くことを推奨します。

# Nodeのプロジェクトではない場合
npx -p docsify-cli docsify init ./docs

# Nodeのプロジェクトの場合はdevDependencyとして追加したほうがよい
# CIや複数人で開発するときに非常に便利になる
npm i -D docsify-cli
npx docsify init ./docs

コマンドを叩くと指定されたディレクトリindex.htmlとREADME.md, .nojekyll(GitHub Pages 用)が生成されます。 このディレクトリをホストしてルート(/)にアクセスするとREADME.mdがいい感じに綺麗になって表示されているはずです。

# ホストした上でライブリロードしてくれる
# デフォでは http://localhost:3000
npx docsify serve docs

ページを増やす場合は Markdown のファイルをディレクトリ内に置くと、ドキュメントとしてアクセスできるようになります。

echo '# Title' > foo.md
# http://localhost:3000/#/foo でアクセスできる

詳しいルーティングやナビゲーションバー、サイドバーのカスタマイズ等は公式のドキュメントに非常にわかりやすく書いてあるので、 「これどうやるんだろう」ってなったら都度参照すれば詰まることはないかと思います。

仕組み

仕組みはいたって簡単で、SPA としてドキュメントを表示するindex.htmlが、表示するパスに応じて Markdown 形式のドキュメントを Fetch/XHR で取得し、それをパースして表示しているだけです。 実行時(ユーザの閲覧時)に Markdown をパースするため、index.htmlと同じく Markdwon ファイルを公開して取得できるようにする必要があります。

向き/不向き

上述したように、これで生成されたドキュメントは SPA として配信されます。 そのため、<head>内を参照する OGP や Google 以外の検索エンジン等の SEO 面で非常に不利になります。 また、デフォルトではルーティングがハッシュベース(http://localhost/fooではなくhttp://localhost/#/foo)のため、Google にインデックスしてもらう場合は History API ベースに変える必要があります。 ただ、特筆すべきデメリットがこれくらいしかないため、これに当てはまらなければ向いていると言っていいかと思います。

向いてない

  • 各ページがシェアされることがわりかし重要
  • Google だけじゃなく DuckDuckGo や Bing でもインデックスさせたい

向いている

  • Google にさえインデックスされていればいい
  • インデックスされる必要がない(されたくない)
    • 主に仕事ではこのケースが多いかと思います

おわり

一度使えばわかるのですが、他のツールと比べて異常なまでにセットアップやデプロイが簡単なので、個人的にデモやプロトタイプを作る際のドキュメントとして多用しています。 デザインもデフォルトの Vue.js テーマがわりかし綺麗で、メイン色くらいだったら Theme 機能やテーマカスタマイズプラグインを使わずにいけるので困ることは基本的にないかと思います。 大抵のドキュメントに使える汎用性を備えながらも、非常にライトウェイトなので是非一度試してみることをおすすめします。