GitHub PagesをMKDocsで作ってみた - 気ままに技術勉強ブログ

はじめに

この記事では、「GitHub PagesをMKDocsで作ってみる方法」について書いています。

GitHub PagesをMKDocsで手軽に作ってみたいなぁと思ったのが記事を書いたきっかけでした。

自分に向けた備忘録の意味もありますが、「GitHub PagesをMKDocsで作ってみたい」な人の一助になれば嬉しいです。

方法

mkdocsのファイルを用意する

GitHub Pagesを作るためのリポジトリを適当に用意してください。

そしてその中にMkDocsのファイルを作ります。

今回の私の場合、（邪道かもしれませんが）一旦mkdocs new)コマンドを実行し、生成されたものを移動させました。

移した後のフォルダは以下のようになっています。

sample
├ .git
├ docs
│  └ index.md
└ mkdocs.yml

GitHubへデプロイする

この状態で、以下のコマンドを実行してください

mkdocs gh-deploy

このコマンドは、自動でgh-pagesというブランチを作り、公開できる状態にしてくれるとても便利なコマンドです。

このコマンドを実行すると、下記のような出力が出てきます。（URLやフォルダパスは適当な名前に変えてます）

INFO     -  Cleaning site directory
INFO     -  Building documentation to directory: C:\xxx\sample\site
INFO     -  Documentation built in x.xx seconds
WARNING  -  Version check skipped: No version specified in previous deployment.
INFO     -  Copying 'C:\xxx\sample\site' to 'gh-pages' branch and pushing to GitHub.
Enumerating objects: 29, done.
Counting objects: 100% (29/29), done.
Delta compression using up to 8 threads
Compressing objects: 100% (28/28), done.
Writing objects: 100% (29/29), xxx.xx KiB | x.xx MiB/s, done.
Total 29 (delta 1), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (1/1), done.
remote:
remote: Create a pull request for 'gh-pages' on GitHub by visiting:
remote:      https://github.com/xxx/sample/pull/new/gh-pages
remote:
To https://github.com/xxx/sample.git
 * [new branch]      gh-pages -> gh-pages
INFO     -  Your documentation should shortly be available at: https://xxx.github.io/sample/

githubのリポジトリのページを見て、gh-pagesというブランチが出来ていることを確認してください

ページの設定を行う

次はGitHub Pagesの設定を変更しましょう。デプロイするサイトはgh-pagesのブランチの内容ですので、そのブランチを参照するように変更します。

リポジトリのSettingタブの右側からPagesの欄を選択し、Branchの項目の部分をgh-pagesと変更し、右側のSaveボタンを押してください。（下図参照）

これで全てが完了です。GitHub Pagesのサイトへアクセスすると、MKDocsで作成したサイトが表示されているはずです。

注意

（あまりいないかもしれませんが）mainブランチにindex.htmlがあると、そちらが優先されて表示されるようですので、もしmainブランチにあれば消すようにしてください（私はindex.htmlがある状態で試したことがあり、その時全然ページが変わらず「あれ？」となりました）

おわりに

「GitHub PagesをMKDocsで作ってみる方法」について解説しました。

GitHub Pages x MKDocsで自分のサイトを手軽におしゃれに作ってみてはいかがでしょうか。

さいごに、記事を書く上で参考にしたサイトのリンクを以下に掲載します。合わせて読んでいただくと良いかと思います。

aiedoc.github.io