Zenn
📖

mdBook&GitHubPagesでのドキュメント公開

2020/09/24に公開
GitHub
Rust
Markdown
mdbook
tech

mdBookとは

Rust製のGitBookライクなツールです。
マークダウンで記述することができ、簡単にオンラインブックを作ることができます。

Rustのインストール

mdBookを使うためにRustのパッケージ管理ツールであるCargoをインストールします。

Ubuntu

curl https://sh.rustup.rs -sSf | sh

上記コマンドを実行するだけでインストールすることができます。

Windows

https://visualstudio.microsoft.com/ja/downloads　から、
BuildTools　for　VisualStudio　2019をダウンロードし、Visual C++ Build Toolをインストールします。
その後、https://www.rust-lang.org/tools/install からRustup-init.exeをダウンロードし、実行します。

以下のコマンドを実行するなどして、正常にインストールできているか確認しておきましょう。

cargo --version

mdBookのインストール

Cargoのインストールが終わったら、以下のコマンドでmdBookをインストールします。

cargo install mdbook

こちらも、以下のコマンドを実行するなどしてインストールできているか確認しましょう。

mdbook --version

GitHub側の準備

GitHubで、GitHubPages用のリポジトリ([ユーザー名].github.io、もしくは設定からGitHubPagesの設定をしたリポジトリ)、mdBookのプロジェクトをアップロードするためのリポジトリの２つを用意します。
次に、リポジトリに登録するためのSSH鍵を用意します。

ssh-keygen -t rsa -b 4096 -f gh-pages

gh-pagesとgh-pages.pubという２つのファイルが生成されるので、公開鍵(gh-pages.pub)をGitHubPages用のリポジトリのSettings > Deploy keysにACTIONS_DEPLOY_KEYという名前で登録します。
この時、Allow write accessのチェックボックスにチェックを付けておきましょう。

秘密鍵(gh-pages)はもう片方のリポジトリのSettings > SecretsにこちらもACTIONS_DEPLOY_KEYという名前で登録します。

これで、GitHub側の準備は終了です。

ローカルでの準備

まず、適当なフォルダを用意し、そのフォルダ内で以下のコマンドを実行します。

mdbook init

すると以下のようにファイルが生成されます。

mdBook
├── book
├── src
│  ├── chapter_1.md
│  └── SUMMARY.md
└── .gitignore(生成時に作成すると答えた場合)

bookディレクトリにはビルドしたファイルが格納されます。
srcディレクトリにはMarkdownファイル群を入れます。
SUMMARY.mdに書いた中身がサイドメニューになります。
mdbook buildを実行するとファイルのビルドをし、mdbook serveを実行するとsrc以下のファイルを監視、変更があると自動で再ビルドをします。
次に、GitHubActionsでの自動ビルドのセットアップをします。
.github以下にファイルを追加します。
追加後は以下のようなディレクトリ構成になります。

mdBook
├── .github
│  ├── actions
│  │  └── build
│  │     └── Dockerfile
│  └── workflows
│     └── main.yml
├── book
├── src
│  ├── chapter_1.md
│  └── SUMMARY.md
└── .gitignore(生成時に作成すると答えた場合)

作成後、main.yml、Dockerfileに以下のように記載してください。

main.yml

name: CI/CD
on:
  push:
    branches:
    - master
    paths:
    - "src/**"
    - "book.toml"

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Build
      uses: ./.github/actions/build
    - name: Deploy
      uses: peaceiris/actions-gh-pages@v3
      with:
        deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
        external_repository: [自分のユーザー名]/[GitHubPagesのリポジトリ名]
        PUBLISH_BRANCH: master
        PUBLISH_DIR: ./book

Dockerfile

FROM rust:latest

RUN cargo install mdbook --no-default-features --features output --vers "^0.3.5"

CMD ["mdbook", "build"]

入力後、プロジェクトにGitを追加し、アップロード用のリポジトリにpushすることで、srcフォルダ内、もしくはbook.tomlに変更があった時にGitHub Actionsが実行され自動でGitHubPages用のリポジトリにHTML等のファイルがアップロードされます。

おわりに

mdBookとGitHubPagesを使うことで無料で簡単にオンラインブックを公開することができます。
ドキュメントやブログなど、幅広く使うことができると思うので是非活用して見てください。

Discussion