GitHub ActionsとMarkdownで静的サイト作成 ~ mkdocs-material 編~

目的

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

なお，前回の記事はこちら。

ossyaritoori.hatenablog.com

要求:

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

超参考になるサイト：

in-neuro.hatenablog.com

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

mkdocs-material

Pythonで動く静的サイト作成手法mkdocsのmaterialというテーマ。

github.com

見た目はこんなかんじ。

Pros and Cons

• 🙆Pros
  • 表現力が豊か（数式，PlantUML，Admonitionなど）
  • 日本語検索にデフォルトで対応
  • cssのカスタムテンプレートなどの数が多い
• 🙅Cons
  • サーバーを立てないと検索窓が立たない（Github Actionsでは無問題）
  • 拡張機能が多く管理が面倒

機能性・拡張性では今の所mdbookよりも良さそうです。

Dockerを用いた動作

多くの人が入れているであろうPython環境で動くので自前でも動かせますが，Dockerイメージもあります。 自分はWSLでやっていますが，Docker for windowsの場合は適宜`pwd`を”%CD%”にするなど置き換えてください。

とりあえず動かす分にはsquidfunk/mkdocs-materialが多く使われている感じがします。

hub.docker.com

• 初期化

wsl docker run --rm -v `pwd`:/book/ squidfunk/mkdocs-material init

• build

wsl docker run --rm -v `pwd`:/book/ squidfunk/mkdocs-material build

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

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

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

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

github.com

なお，拡張機能をいろいろ盛り込んだので動作検証用のossyaritoori/mkdocs-materialにてイメージを公開しました。

したがって，実行コマンドは下記のような感じになります。

docker run --rm -v `pwd`:/docs ossyaritoori/mkdocs-material build

ファイル構造

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

mkdocsTest
├── .github
│  └── workflow
│     └── mkdocs.yml
│
├── mkdocs.yml # book setting
└── docs # Source folder
   ├── index.md # For top page (Not neccesary)
   └── < other .md files >

.github以下のActionsについて

Actionの流れは

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

としました。

name: deploy mkdocs
on:
  push:
    branches:
      - main
      - master

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
      - name: Check out code
        uses: actions/checkout@v2
      # Prepare Python package
      - uses: actions/setup-python@v2
        with:
          python-version: 3.x
      - run: pip install mkdocs-material
      - run: pip install plantuml-markdown python-markdown-math mdx_truly_sane_lists mkdocs-git-revision-date-localized-plugin mkdocs-add-number-plugin
      # deploy
      - run: mkdocs gh-deploy --force

gh-pagesの設定

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

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

一般の項から

TODO・その他

GithubActionについて

面倒でそのままpipを手打ちしていますがRequirement.txtとかを書いてそこからインストールしたほうが良さそうです。 Dockerfileもそれに準拠して書かないとなぁとは思っています。

PDF生成

こんな感じのPDFが拡張機能によって作れます。

github.com

インストール後，CSSファイルをコンパイルして作成することでそれっぽくできます。

ただ，日本語が文字化けしてしまったのでそのあたりはCSSを調整してみないと，といった感じです。