ドキュメントサイトジェネレータdocsifyの基本的な使い方まとめ

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/46492/0dc2cc3b-10e5-30ac-ec98-494a0bc9f95d.png)


ちょっとしたドキュメントを作成するのに便利な「ドキュメントサイトジェネレータ」であるdocsifyについて、基本的な情報＆使い方をまとめます（自分で使いながら追記していきます）。

## docsifyとは

公式サイト：[docsify](https://docsify.js.org/#/)

トップに

> A magical documentation site generator.

と書かれているように、docsifyは"ドキュメントサイトジェネレータ"です。

### ドキュメントサイトジェネレータとは

その名の通り、たとえばプログラミング言語やフレームワークのドキュメントページのような形式のサイトを作るためのツールです。左にメニューがあって、右に本文があって、というあれです。


[docsify](https://docsify.js.org/#/)のサイト自体がdocsifyで作られているので、これを見ていただくのが一番わかりやすいです。

### 類似のツール

- [GitBook - Where software teams break knowledge silos.](https://www.gitbook.com/)
- [docuowl/docuowl: 🦉 A documentation generator](https://github.com/docuowl/docuowl)
- [Build optimized websites quickly, focus on your content | Docusaurus](https://docusaurus.io/)

などなどなど多数存在します


### docsifyを使うメリット

なんといっても、ドキュメントサイトが爆速で作れる点です。HTMLやCSSなど細かいところをいじる必要がなく、Markdownでドキュメントの本文を書くことに集中できる点が魅力です。

また、他のドキュメントサイトジェネレータに比べても**導入が簡単**と個人的に感じたことも大きいです。

コマンドラインで`npm`が実行できれば今すぐに始められる手軽さです。

### 例

本記事執筆時点でつくりかけですが、こんな感じのサイトがすぐ作れます。GitHub Pagesでデプロイしています。

[テストエンジニアのための初めてのプログラミング](https://yoshikiito.github.io/programming4testers/#/)

このサイトで実際にやっている例をベースに説明します。


## docsifyのはじめかた

### 前提

- node.jsがインストールされていること

### 環境構築

基本的には公式の[Quick start](https://docsify.js.org/#/quickstart)の通りにやればOKです。

まずはインストール。

``` bash
npm i docsify-cli -g
```
公式ではグローバルのインストールが推奨されています。

次に初期化です。docsifyのドキュメントを作成したいディレクトリに移動してコマンドを実行します。

ここでは公式の例にそって、カレントの下にある`./docs`ディレクトリにドキュメントサイトを作ることにします。
（ここを揃えておくと、後々GitHub Pagesにデプロイするときに公式のdocsifyドキュメントと整合性がとれた状態で進められます。）

``` bash
docsify init ./docs
```

成功すると、

``` bash
Initialization succeeded! Please run docsify serve ./docs
```

と表示されるので、書いてあるとおりに`docsify serve ./docs`すると・・・

http://localhost:3000

で以下のように表示されます。

![1000.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/46492/1dda8cf3-1aa1-7c70-d368-88548932761f.png)


docsディレクトリの中身は3つです。

- index.html : エントリファイル。ここに設定など色々記述します。
- README.md : ドキュメントサイトのHOMEに相当します。
- .nojekyll : GitHub Pagesでホスティングするときにjekyllとして処理されないようにするためのファイルです。

参考：[GitHub Pagesで普通の静的ホスティングをしたいときは .nojekyll ファイルを置く - Qiita](https://qiita.com/sky_y/items/b96ae52c90457bcd7846)

### 記事を書く

記事を書く際は`.md`ファイルに本文をどんどん書いていけばOKです。

`README.md`はホーム画面にあたるので追記するだけです。

新しくページを追加したいときは、`docs`ディレクトリ内に`hogehoge.md`を追加して、そこに本文を書いていきます。

この先は記事を書いてサイトを構築していくにあたってよく使う機能について説明します。


## よく使う（であろう）機能

### サイドバーを追加する

参考：[Sidebar](https://docsify.js.org/#/more-pages?id=sidebar)

サイドバーを追加するのは2ステップです。

#### 1. index.htmlに追記

`index.html`に`loadSidebar: true`を追記します。

具体的にはココ。このとき、ついでに`subMaxLevel`も設定しておくとよいでしょう。ToCをサイドバーに出してくれます。

参考：[Table of Contents](https://docsify.js.org/#/more-pages?id=table-of-contents)

``` html
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      name: '',
      repo: '',
      loadSidebar: true, /* ココ */
      subMaxLevel: 2, /* h2までをサイドバーに出す、の意 */
    }
  </script>
```

#### 2. _sidebar.mdを作成

`docs`ディレクトリの直下に`_sidebar.md`を作成します。アンダーバーが先頭についています。

`_sidebar.md`の中に、箇条書きでリンクを書いていきます。

例

``` md
* **テストエンジニアのための初めてのプログラミング**

* [Home](/)
* [講師](/instructor.md)
* [ワーク環境構築](/env.md)
* <hr>
* [プログラミングを始めよう](/introduction.md)
* [プログラミングの基礎知識](/fundamentals.md)
* [実際にやってみよう～ワーク～](/work.md)
* <hr>
* [プログラミングを学ぶコツ](/how-to-learn.md)
* <hr>
* [Python環境構築](/python-env.md)
```

このように表示されます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/46492/32f55fca-8201-2549-43c6-21e6bcddadb6.png)


### ナビゲーションバーの追加

参考：[Custom navbar](https://docsify.js.org/#/custom-navbar)

#### 1. index.htmlに追記

`index.html`に`loadNavbar: true`を追記します。

具体的にはココ。

``` html
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      name: '',
      repo: '',
      loadSidebar: true,
      subMaxLevel: 2,
      loadNavbar: true /* ココ */
    }
  </script>
```

#### 2. _navbar.mdを作成

`docs`ディレクトリの直下に`_navbar.md`を作成します。こちらもアンダーバーが先頭についています。

`_navbar.md`の中に箇条書きでリンクを書いていきます。

``` md
* [JaSST'22 Tokyo](http://www.jasst.jp/symposium/jasst22tokyo.html)
```

ここではNavbarの内容が一つだけですが、このように右上に表示されます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/46492/d8aca238-c708-50eb-35e8-16643129d303.png)



### Tipsとポイントの書き方

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/46492/e239049f-ce28-e3ab-b53c-9b2a9553b100.png)

↑こんなやつです。緑背景や、「！」のついたグレー背景の部分です。

それぞれ書き方は以下。

``` md
?> 参考情報を書いたりできるし

!> 気をつけるべきことを書いたりできるよ
```

### 絵文字を使う

リストはこちら＞[Markdown](https://jhildenbiddle.github.io/docsify-themeable/#/markdown?id=emoji)

- :+1: +1
- :clap: clap
- :100: 100

などが使えます。



## 参考

- [ビルド不要のドキュメントサイトジェネレーター「docsify」の個人的まとめ - Qiita](https://qiita.com/kapioz/items/2c2353320ea96c8c43ed)