作業手順書を docsify で作成する #docsify

この記事は NTTコミュニケーションズ Advent Calendar 2019 の10日目の記事です。
昨日は @tetrapod117 さんの Cloud RunでSlackの分報をちょっとだけ楽しくしてくれるBotを作ってみたでした。

はじめに

こんにちは。インターネットマルチフィードの @koki-sato です。
普段は transix というサービスの運用・開発などを行なっています。

Infrastructure as Code という言葉が広く浸透している現代でも、残念ながら手順書を書く機会はあります。特に、ネットワーク機器などの物理機器を扱う業務では手順書を書くことが多いかと思います。
弊チームでは、これまでずっと社内の PukiWiki を使って手順書を書いていましたが、PukiWiki 記法（および PukiWiki のエディタ）で書くのがつらかったり、誰が編集したのか証跡が残らないなどの問題がありました。

なぜ docsify なのか？

今回、脱 PukiWiki に当たって最低限以下の要件がありました。

Git 管理したい （ついでに GitLab の merge request で手順書のチェック・承認フローを行いたい）
Markdown で書きたい

単純に社内の GitLab のリポジトリに Markdown ファイルを置いて参照するだけでも良いのですが、せっかくなのでドキュメントサイトを用意したいところです。そこで今回は docsify を使ってみました。

docsify は静的サイトジェネレータの一つで、Markdown ファイルから簡単にドキュメントサイトを作ることができます。

特徴としては ビルドが不要 で、docsify-cli init した際に生成される index.html と Markdown ファイルだけで動作します。
公式ホームページに GitHub Pages などへのデプロイ方法がありますが、ビルドが不要なためどれも簡単にデプロイできます。

ちなみに、他にもドキュメント作成ツールの候補として GitBook や Sphinx や MkDocs なども検討したのですが、以下の理由から docsify にしました。

GitBook は gitbook-cli がもうメンテナンスされていない
Sphinx は reStructredText の印象が強い
Sphinx や MkDocs は普段 python を使わないチームで python の環境構築を強いるため導入コストが高い

docsify の使い方

docsify を使うには docsify-cli を install する必要があります。以下は Yarn でプロジェクト内に install した場合の手順です。

$ yarn add -D docsify-cli

# 初期化
$ yarn docsify init ./docs

# ローカルサーバ立ち上げ
$ yarn docsify serve docs

たったこれだけでローカル環境でドキュメントサーバを作ることができます。

あとは _sidebar.md や _navbar.md によって Sidebar や Navbar の設定もできます。詳しくは公式のドキュメントがわかりやすいのでそちらを参照してください。

多少工夫したところ

docsify が優秀だったので、特に何も考えなくてもいい感じにドキュメントサイトを作れてしまったのですが、強いて言うと工夫した点をいくつか紹介します。

手順書へのリンクの生成

大まかにリポジトリの構成は以下のようになっています。

.
├── docs
│   ├── 2017
│   ├── 2018
│   ├── 2019
│   │   ├── YYYYMMDD_作業名
│   │   │   ├── README.md    // 手順書
│   │   │   ├── _sidebar.md  // サイドバー（ToC 用）
│   │   │   └── image.png    // 手順書内で使う画像等
│   │   ├── YYYYMMDD_作業名
│   │   │   ...
│   │   └── README.md
│   ├── README.md
│   ├── _sidebar.md
│   └── index.html
├── node_modules
├── package.json
├── script
└── yarn.lock

手順書の数が多すぎてサイドバーに載せられなかったので、 docs/YYYY/README.md にその年度に行われた作業の手順書のリンクを載せ、その README.md へのリンクをサイドバーに載せました。

手順書表示時に ToC をサイドバーに表示

docsify ではサイドバーの項目を _sidebar.md で設定できるのですが、基本的には先ほど説明したように docs/YYYY/README.md へのリンクしかありません。

しかし、手順書を表示した場合は ToC がサイドバーにあった方が何かと便利です。_sidebar.md はデフォルトの設定だと Override 可能なので、 docs/YYYY/YYYYMMDD_作業名/_sidebar.md を以下のような内容で作成することで ToC を表示させました。

- [YYYYMMDD_作業名](YYYY/YYYYMMDD_作業名/README.md)

git commit 時にリンクを自動生成

docs/YYYY/README.md と docs/YYYY/YYYYMMDD_作業名/_sidebar.md は手順書を作成するたびに更新しないといけません。それでは手順書を作成する人に負担がかかりますし、追加ミスなどが起こる可能性があります。そこで husky を使って git commit 時に hook して、これらのファイルを自動生成して commit 対象に含めるようにしました。

package.json

{
  "scripts": {
    ...,
    "generate-links": "ts-node script/generate-links.ts"
  },
  "husky": {
    "hooks": {
      "pre-commit": "yarn generate-links && git add docs/20*/README.md docs/**/_sidebar.md"
    }
  }
}

おわりに

docsify で簡単にドキュメントサイトを作ってみました。
また、単に Markdown ファイルを読み込んでいるだけなので、もし将来的に docsify を使わないという選択になったとしても、簡単に外すことができるのも良い点だと思います。

明日は @a0x41 さんの記事です。