MKDocsを使ってFPGA開発日記の記事まとめページを作り直した

初めて知ったのだが、MKDocsはGoogleっぽいページを作ることができるサイトだ。 これまではGitHub PagesでMarkdownを直接書いて作っていたのだが、MKDocsはMarkdownを使って簡単にかっこいいページを作ることができるのでやってみた。

ちなみに、MKDocsでのサイトの構築とGoogle Material Designは別々の管理なので、まずはMKDocsを作ってから、Google Materials Designに変更する。

www.mkdocs.org

試行したのは、Windows上のmsys2環境だ。

MKDocs の環境構築

まずは、pipでMKDocsをインストールする。

pip install mkdocs mkdocs-material

MKDocsでのページ編集

GitHub PagesにMKDocsのページをデプロイするためには、どうも別のリポジトリを作ってそちらにMKDocsの環境を構築する必要があるらしい？ まずは自分のページにgithub_pagesというリポジトリを作った。

github.com

このリポジトリをcloneし、MKDocsのページを構築していく。

git clone https://github.com/msyksphinz/github_pages.git
mkdocs new github_pages
cd github_pages

/docsにソースコードを格納していく。

.
├── docs
│   ├── 30os.md
│   ├── gpgpu.md
│   ├── index.md
│   ├── machine_learning.md
│   ├── mastering_bitcoin.md
│   ├── quantum_computing.md
│   ├── riscv.md
├── get_entry.rb
├── mkdocs.yml
└── output.txt

プレビューのためにビルドを行った。mkdocs buildとすると、/siteにプレビューファイルが作られる。

$ mkdocs build
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: C:/msys64/home/msyksphinz/work/github_pages/site

表示してみると、いい感じだ。

Google Material Designへの変更

次に、Google Material Designの設定を行う。mkdocs.ymlを以下のように設定して、Material Designに設定した。

• mkdocs.yml

site_name: FPGA開発日記 カテゴリ別記事インデックス
theme:
  name: 'material'
  palette:
    primary: 'indigo'
    accent: 'indigo'

以下のようになった。これはいい感じだ。

GitHub Pages にデプロイする

GitHub Pagesにデプロイするには、以下のように入力するだけだ。

$ mkdocs deploy
$ mkdocs gh-deploy
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: C:/msys64/home/masayuki/work/github_pages/site
INFO    -  Copying 'C:/msys64/home/masayuki/work/github_pages/site' to 'gh-pages' branch and pushing to GitHub.

これで、msyksphinz.github.io/github_pages/にページがデプロイされた！なかなかいいね。