GitHub ActionsとMarkdownで静的サイト作成 ~ mdbook 編~

目的

Markdownで書いた文書を静的サイトとしてまとめ上げたい。 そしてそのままそれを本番の文章として提出しちゃいたい。

要求:

• 検索機能つきの静的なサイトが生成される
• 表現が豊か（数式・図表・Admonitionなど）
• PDFに出力可能

超参考になるサイト：

in-neuro.hatenablog.com

ここから，mdbook, (gitbook), mkdocsあたりを試していこうと思います。

mdbook

開発が終了したGitbook v1のRust版後継です。

こんなかんじの見た目になります。

Pros and Cons

• 🙆Pros
  • 動作が軽量。コンパイルが早い。
  • サーバを建てずともサイトの検索機能が動作する
• 🙅Cons
  • 現状日本語検索に対応する気があまりなさそう…
  • 発展途上なので現状表現力は他の手法に劣る。

Dockerを用いた最小動作

Rust環境を建てても良いですが，Dockerで開発するのが無難です。 自分はWSLでやっていますが，Docker for windowsの場合は適宜`pwd`を”%CD%”にするなど置き換えてください。

github.com

• 初期化

wsl docker run --rm -v `pwd`:/book/ peaceiris/mdbook init

• build

wsl docker run --rm -v `pwd`:/book/ peaceiris/mdbook build

ざっくり生成されるファイル・フォルダを説明すると

• book.toml : 書式や署名などを指定する
• src/ : 文書のソースを置く場所
  • SUMMARY.md : リスト形式で文章のネスト構造を指定する
  • xxx.md: 本体の文章
• book/ : 生成されたサイトがここに格納される。文章へはindex.htmlにアクセス。

Github Actionsを用いたドキュメントのHost

ひとまずテストプロジェクトを立ててみました。

github.com

ファイル構造

ファイル構成はこんなかんじです。

mymdBook_Test
├── .github
│  └── workflow
│     └── mdBook.yml
│
├── book.toml
└── src
   ├── chapters
   │  ├── introduction.md
   │  └── <other .md files>
   └── SUMMARY.md

.github以下のActionsについて

Actionの流れは

• ファイルをCIサーバーにUpload
• build
• book以下をgh-pagesに展開

としました。

name: github pages

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2

      - name: Setup mdBook
        uses: peaceiris/actions-mdbook@v1
        with:
          mdbook-version: '0.4.6'
          # mdbook-version: 'latest'

      - run: mdbook build

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./book

gh-pagesの設定

上記のFlowではgh-pagesブランチに生成物をUploadしています。

gh-pagesの設定は「設定」→「一般」から下記の項目で

一般の項から

TODO・その他

• ちょっときになる点
  • 左のTitleが折り畳めない
• PDF生成とか試しておきたい。