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

マークダウンとは

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

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

なぜGitbookなのか

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

2. HTMLが成形されて出てくる
   地味に便利。

3. PDFも作れる
   これが最重要

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

Node.jsをインストール

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

Windowsの場合

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

Macの場合

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

$ brew install nodebrew

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

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

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

$ nodebrew install-binary latest

Gitbookをインストール

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

$ npm install -g gitbook-cli

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

$ gitbook help

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

早速作ってみる

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

$ mkdir gitbook-sample
$ cd gitbook-sample
$ gitbook init

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

• README.md
• SUMMARY.md

book.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が書けると思って頂ければ結構です。

book.json

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

インストールする

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

$ gitbook install

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

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

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

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

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

/gitbook-sample
 ├ /docs
 │　└file1.md - サンプル用のマークダウンを指定します
 └ /styles
 　 ├ site.scss - HTML出力用のスタイル
 　 └ pdf.scss - PDF出力用のスタイル

file1.mdには、ひとまず適当な情報を入力します。

file1.md

# サンプルファイル

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

サンプルです。

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

# Summary

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

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

$ gitbook serve

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

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

PDF出力する

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

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

$ gitbook pdf

まとめ

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

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