個人的に最強のマークダウン環境「Gitbook」を使う


## マークダウンとは

このあたりはQiita見ている方ならだいたいご存知かと思いますので詳しくは省略しますが、

簡単に説明を書いたりできるようになるフォーマットです。

## なぜGitbookなのか

1. __プラグインが導入できる__
    数式やらシーケンス図やらを簡単に書けるようになります。
    ある意味これがすべて。

2.  __HTMLが成形されて出てくる__
    地味に便利。
    
3. __PDFも作れる__ 
    これが最重要


## とりあえずインストールしてみよう

### Node.jsをインストール

みんな大好きNode.jsをインストールします。

#### Windowsの場合

ここからインストールします。
https://nodejs.org/en/

#### Macの場合

nodebrewをインストールします。

```shell-session
$ brew install nodebrew
```

PATHを通します。
※例はbashですが、zshを使っている場合には別途指定してください。

```shell-session
$ echo 'export PATH=$HOME/.nodebrew/current/bin:$PATH' >> ~/.bash_profile
```

最新版をインストールします。

```shell-session
$ nodebrew install-binary latest
```

### Gitbookをインストール

以下のコマンドをシェルから実行します。

```shell-session
$ npm install -g gitbook-cli
```

このままでは本体がインストールされていませんので、
インストールを行います。

```shell-session
$ gitbook help
```

これで、本体のインストールが進みます。

## 早速作ってみる

適当なディレクトリに移動し、以下のコマンドを叩きます。

```shell-session
$ mkdir gitbook-sample
$ cd gitbook-sample
$ gitbook init
```

すると、2つのmdファイルが出来上がっています。

- README.md
- SUMMARY.md

## book.jsonを作成する

さて、それでは以下のファイルを新たに作成します。

```json:book.json
{
    "plugins": [
        "sequence", 
        "flowchart", 
        "uml", 
        "mathjax",
        "-sharing",
        "hide-published-with", 
        "numbered-headings-for-web-and-books",
        "styles-sass-fix"
    ],
    "pluginsConfig": {
        "sequence": {
            "theme": "simple"
        },
        "mathjax": {
            "forceSVG": true
        },
        "theme-default": {
            "showLevel": false
        }
    },
    "styles": {
        "website": "./styles/site.scss",
        "pdf": "./styles/pdf.scss"
    }
}
```

book.jsonには、使用するプラグイン情報や設定を記載します。

使用しているプラグインを簡単に紹介します。

### sequence, flowchart, uml

それぞれ、シーケンス、フローチャート、UML(クラス図)を書くことが出来ます。

本稿では詳しい書き方を省略しますので、
ひとまず書き方の例は下記のサイトを参照にしてください。

*Seqience*
https://www.npmjs.com/package/gitbook-plugin-sequence
*Flowchart*
https://www.npmjs.com/package/gitbook-plugin-flowchart
*UML*
https://www.npmjs.com/package/gitbook-plugin-uml

### mathjax

このプラグインを導入することで、数式を書く事ができます。

同様に書き方は以下を参照してください。

*Mathjax*
https://www.npmjs.com/package/gitbook-plugin-mathjax

### -sharing, hide-published-with

HTML出力する際に出力される不要なリンクを削除します。

### numbered-headings-for-web-and-books

各セクションに対し、1. 、1.1・・・とナンバリングをしてくれます。

### styles-sass-fix

出力されるHTMLまたはPDFに対して独自のスタイルを適用できるようになります。
book.jsonに記載した以下のscssファイルをコンパイルし、生成するHTMLに適用します。

※SCSS/SASSの説明も省略します。
よくわからない人はCSSが書けると思って頂ければ結構です。

```json:book.json
    "styles": {
        "website": "./styles/site.scss",
        "pdf": "./styles/pdf.scss"
    }
```

### インストールする

book.jsonが出来上がったら、以下のコマンドを実行しプラグインをインストールします。

```shell-session
$ gitbook install
```

なお、ここで「unable to connect to github.com」と言われた場合、
ネットワークの問題でうまくダウンロード出来ていない可能性があります。

"git://"で接続している可能性があるので、
強制的にhttpsアクセスするように設定をし直した上で再実行してください。

```shell
git config --global url."https://".insteadOf git://
```

## 最終的なディレクトリ構成

最後に、以下の構成でディレクトリおよびファイルを作成します。

```
/gitbook-sample
 ├ /docs
 │　└file1.md - サンプル用のマークダウンを指定します
 └ /styles
 　 ├ site.scss - HTML出力用のスタイル
 　 └ pdf.scss - PDF出力用のスタイル
 ```
 
 file1.mdには、ひとまず適当な情報を入力します。
 
 
 ```shell:file1.md
# サンプルファイル

## サンプルのサブセクション

サンプルです。

```
 

最後に、SUMMARY.mdを開き、以下のようにします。

```shell-session
# Summary

* [Introduction](README.md)
  * [サンプル](docs/file1.md)
```

ここまでできたら、シェルから以下のコマンドを実行します。

```shell-session
$ gitbook serve
```

これでhttp://localhost:4000 にアクセスすることで書いた内容が見えると思います。

これで作成したサンプルも見れればすべてのインストールが完了です。

### PDF出力する

まず、Calibreをインストールします。
以下からインストーラをダウンロードし、インストールを行ってください。
https://calibre-ebook.com/


PDFを出力するには、以下のコマンドを実行します。

```shell-session
$ gitbook pdf
```

## まとめ

GitBookと名はついていますが、
特に中身自体はGitHubをはじめとするGit系ソフトウェア群とは全く違います。


つくったものをGithubに公開しました。
参考にしてみてください。

https://github.com/hikaruright/gitbook-sample