Neunomizuの日記

俺だけが俺だけじゃない

GitbookとGithub Pagesを使ってMarkdownで書けるブログを作りました

情報
tags: 情報

背景

GitbookとGithub Pagesを使ってローカルで編集したMarkdownファイルからオンライン上で自分の勉強に関するメモを共有できるものが作りたいと思いました

最初はGitbookに全てを書こうと思っていたのですが,インライン数式を"$$"で囲う必要があったのが思った以上に面倒でした

またそのため,Markdownファイルを他で使うこともできずもったいないのでより汎用的な形式で書きたいと思いました

それならばGithub Pagesで数式を書いてしまおうと思ったのですがそれもレイアウトが美しくなく(自分にフロントの経験があれば良いのですが,その勉強をするのも大変なので)上手く両者の良い所取りができるものはないかと探した結果両者を合わせて使うことになりました

どういうものがほしかったのか

ほしいものの条件は以下の通り

  • 数式とコードが普通のMarkdown形式で書ける(再利用可能)
  • ローカルで書けてオンラインで共有できる
  • 他人が編集することが可能

GitbookとGithub Pagesを選んだ理由

なぜ両者を使うことになったかというと他のサービスで上の3条件のどれかが満たせるものが見つからず,両サービスを使うと両立ができるからです

  • Gitbookはmarkdown形式でファイルを書いてそれを使って電子書籍が書けます
    • gitを使って管理するので他の人と共同で編集できます
  • Github Pagesもgitを使ったサービス
    • 自分で設定ができる範囲が広い
    • しかも独自のドメインが使えるので後々便利

また,どちらも仕様が分かっているサービスで新たに学ぶ点が少ないのも選んだ理由

どのような手順でこれをするか

環境構築

npmというNode.jsのパッケージ管理ツールを使います

自分の環境は以下の通りです

NAME="Ubuntu"
VERSION="18.04.3 LTS (Bionic Beaver)"
ID=ubuntu
ID_LIKE=debian
PRETTY_NAME="Ubuntu 18.04.3 LTS"
VERSION_ID="18.04"
HOME_URL="https://www.ubuntu.com/"
SUPPORT_URL="https://help.ubuntu.com/"
BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/"
PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy"
VERSION_CODENAME=bionic
UBUNTU_CODENAME=bionic

次にnodejsとnpmについてインストールします

sudo apt install -y nodejs npm

上手くインストールができない場合があるらしいので,エラーが出たら頑張ってください...

それが終わったら,次にgitbookをインストールします

sudo npm install -g gitbook-cli

-gを付けるかどうかはインストール先をグローバルな場所にするかどうかによります.僕はどこでも使うので付けましたが必要ないという人は付けない方が後々面倒に成るかもしれないらしいので気を付けて下さい

Gitbookの使い方

試しに架空のsampleというフォルダを作ってその中でGitbookを作る方法を試してみましょう

$ mkdir sample && cd sample # sampleフォルダを作り,そこへ移動する
$ gitbook init # gitbookを始める
warn: no summary file in this book 
info: create README.md 
info: create SUMMARY.md 
info: initialization is finished 
$ ls # 中身を確認
README.md  SUMMARY.md
$ cat README.md # README.mdの中身を確認
# Introduction

$ cat SUMMARY.md # SUMMARY.mdの中身を確認
# Summary

* [Introduction](README.md)

という風になっています

SUMMARY.mdがフォルダの構造を示すようになっています

SUMMARY.mdを編集して,gitbook initをするとそれに合わせたフォルダ,ファイルを生成してくます

試しにSUMMARY.mdを編集してみます

$ cat SUMMARY.md # SUMMARY.mdを次のように編集
# Summary

* [Introduction](README.md)
* [hoge](hoge/hoge.md)
    * [hogehoge](hoge/hogehoge.md)

$ ls # hogeフォルダが生成されている
hoge  README.md  SUMMARY.md
$ ls hoge/ # hogeフォルダにはhoge.mdとhogehoge.mdが生成されている
hogehoge.md  hoge.md

SUMMARY.mdを書いてから,それに合わせて適宜ファイルを編集するといい感じになるはずです

book.jsonを追加してプラグインを書くことも可能です.最後に自分のbook.jsonを書いておきます

書いた内容を反映するには以下のコマンドを打って下さい

gitbook install

ローカルで出来上がったGitbookを見るにはgitbook serveを実行します.ブラウザ上のURL欄にhttp://localhost:4000/と打つと見ることができます.ちなみにここで作ったファイルは_bookディレクトリ内のものです

最後にビルドをします

gitbook build

これでビルドはできますが,ビルド先のデフォルトは_bookというディレクトリです.これを例えばdocというディレクトリにするには

gitbook build . doc # gitbook build <ビルド対象ディレクトリ> <ビルド先>

というコマンドを打ちます

Github Pages

<ユーザー名>.github.ioというレポジトリをGithub上で作るとそれがそのままGithub Pageになりホームページとして公開されます.しかし,この場合多少の不都合が有ります

下の写真はdiohabara.github.io(僕のGithubのユーザー名はdiohabaraなので)におけるGithub Pagesのソース部分を選択する項目ですが,この場合このレポジトリ内の全てのコードが使われてしまいます

一方,cs-recapというレポジトリ内のSettings→Github PagesではちゃんとSourceという項目を選択できます

cs-recapというレポジトリ内にあるdocsというフォルダを選択すると,diohabara.github.io/docsというURLでdocs以下のファイルのみがホームページ上で公開されます

これによりGitbookで生成する_bookの部分だけを公開でき,無駄にREADME.mdやSUMMARY.mdを公開しなくて済むようになります

また,公開する際にGithub Pages側からJekyllだと思われると不都合があるようなので以下のコマンドで.nojekyllファイルを加える必要が有ります

touch .nojekyll

book.jsonの設定

後回しにすると言ったbook.jsonの設定について書きます

自分は以下のように書きました

{
  "title": "CS-Recap",
  "plugins": [
    "katex@git+https://github.com/gaoxiaosong/plugin-katex.git",
    "copy-code-button",
    "search-pro-kui",
    "custom-favicon",
    "image-captions",
    "japanese-support",
    "advanced-emoji",
    "-lunr",
    "-search",
    "-sharing"
  ],
  "pluginsConfig": {
    "favicon": "img/favicon.ico"
  }
}

それぞれ説明するのは面倒なので端折りますが,大事なのはmathjaxの場合,レンダリングに時間がかかりすぎるのでkatexにしたという点です

加えて,デフォルトのものだとインラインで書く際に"$$"で囲う必要があるので有志の方が改造したバージョンを使っているという点です

"katex@git+https://github.com/gaoxiaosong/plugin-katex.git"と書いてある部分がそれです

実際の画面

以下のコードが書かれたMarkdownファイルはビルドされると次のようになります

コード

実際の画面

これを見るとかなりいい感じなのでは?

まとめ

GitbookとGithub Pagesを使えばドキュメントをキレイに公開できるのでおすすめです

他にももう少し改造できるらしいですが,これで結構満足しているので十分かも知れません

かなり気に入っているのでそのうちカスタムドメインを取るかもしれません

参照