Mkdocsを使ったGitHub Pagesの作成方法¶

1. Mkdocsとは¶

Markdownで書いたドキュメントを自動的にHTMLに変換し、静的なHTMLサイトを構築してくれる静的サイトジェネレータです。Pythonが必要になります。

これをGithub Pagesと組み合わせることで、レンタルサーバーなどを用意しなくてもレンタルするブログよりも簡単にドキュメント化＆サーバーへアップが可能になります。ただターミナルをガンガン使うので上級者向けです。

$ pip install mkdocs

自分の場合はpython 3.7なのでpip3でした。

公開するURLは

https://{ユーザー名}.github.io/{リポジトリ名}

とすることもできますが、

https://{ユーザー名}.github.io

というスッキリしたURLにすることができます。

今回は後者の方で進めます。リポジトリ名を以下のようにします。

ここのリポジトリ名が間違っているとスッキリしたURLにならないので注意。

リポジトリ作成後、ローカルの作成したいディレクトリでクローンし、移動します。

$ git clone https://github.com/{ユーザー名}/{ユーザー名}.github.io.git
$ cd {ユーザー名}.github.io

以下でプロジェクトを作成し、

$ mkdocs new {プロジェクト名}
$ cd {プロジェクト名}

ディレクトリを切り替えてローカルサーバーで実行。

$ mkdocs serve

ちなみにMkdocsには終了コマンドが無いため実行しているターミナルでCtrl + Cをして終了。

正常に表示できたら、次はGithubへプッシュします。

$ git add .
$ git commit -m "Mkdocsインストール"
$ git push origin main

GitHubへPushまたはCloneする際のパスワードは、自身で登録したパスワードから個人アクセストークンを使用するよう変更されたため、アクセストークンをGitHub設定から発行する必要があります。

詳細はこちらを参照。

ローカルサーバーを実行したディレクトリで

$ mkdocs gh-deploy

をすると、gh-pagesというブランチが作成されます。

このブランチでは公開用のファイルが自動生成され、mainブランチとは内容が異なります。

このブランチをリポジトリのSetting > Code and automation > Pagesから公開ブランチとして指定します。

これがググってもあまり載っておらず、なかなか公開サーバーに反映されず躓きました。

GitHub Pages設定

保存が完了すると、https://{ユーザー名}.github.io で公開されます。