Help us understand the problem. What is going on with this article?

作業手順書を 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 ファイルから簡単にドキュメントサイトを作ることができます。

image.png

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

ちなみに、他にもドキュメント作成ツールの候補として GitBookSphinxMkDocs なども検討したのですが、以下の理由から 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 へのリンクをサイドバーに載せました。

image.png

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

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

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

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

image.png

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

docs/YYYY/README.mddocs/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 さんの記事です。

Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away