この記事は 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 対象に含めるようにしました。
{"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さんの記事です。