GitLab CIとmdbookで本を書いて公開する

mdbookはRust製のGitbookクローンです。

このように左に章立て、右に本文の形式のHTMLが出来ます。Rustのドキュメントの多くはmdbookで生成されているのでRustを書いていると良く見ますね。

以前の記事で紹介したように、図や数式(MathJax)を追加することができます

今回はこのmdbookで生成したHTMLをGitLabの機能であるGitLab CIを用いて自動的にデプロイするための設定を簡単に行うためのリポジトリを作ったので紹介します。

使い方

1. https://gitlab.com/termoshtt/my-first-mdbook をGitLabでフォークする
2. src/以下にあるMarkdownファイルに追記する
3. GitLabにpushする

でHTTPSで生成されたbook形式のHTMLがホストされます。

• Markdownでの数式の書き方は以前の記事を参考にしてください
  • eom/bookの日本語版を作り始めた
• URLはhttps://{username}.gitlab.com/{repository_name}になるはずです。
  • 実際には左側のSettings > Pagesのタブを見れば正しいリンクがあるはずです
• 初回のデプロイではSSLの証明書の有効化に30分程度(?)かかるはずなので気をつけてください。

手元で生成結果を確認する

書いてる途中で確認するにはmdbookをインストールする必要があります。後述の方法でインストールしたのち、

mdbook build

でbook/ディレクトリ以下にHTMLが生成されます。

バイナリをダウンロードする

GitHubのmdbookのリポジトリのリリースのページでバイナリが配布されているのでそれを使います

tar/zipを解凍すると実行ファイルのmdbookが素ではいっているはずです

cargoでインストールする

Rustの開発環境を整える場合は

cargo install mdbook

で入ります。ただコンパイルはちょっと重めです。