注意事項
経緯
作成したページ
GitHub Pagesへの公開までの流れ
GitHub Actionsの設定とmkdocs.ymlの作成
- .github/workflows/push_gh-deploy.yml
- 処理のポイント
レイアウト選択
GitHub Actionsによるビルドとデプロイ結果
まとめ
参考記事

注意事項

本記事は2023/6/18時点の情報です。記事内容は最新の情報(GitHub Pages,リポジトリのリビジョン等)と異なる場合がありますのでご注意ください。

経緯

下記Tweetの通りです。Markdownファイルをgitで管理すること自体は良かったのですが、見栄えが気になっていました。
調べると現在管理してる情報をGitHub Pagesで公開することに関して特に課題はなかったため、学習の意味も込めてGitHub Pageで技術系Tipsを公開することにしました。

本記事ではGitHub Pagesへの公開までの流れについてまとめましたので紹介します。

個人用tipsをGitHubのリポジトリで管理してたけど、GitHub Pagesで管理することに決めた。

はてなブログだと記事内容的に書きづらい。(ただ、タグ管理できるのは良い。)

wikiだとプロジェクトではないし何か違う。結果、Markdownファイルに分けて管理してたけど、内容が増えると見づらかった。
— 7rikaz (@tw_7rikazhexde) June 14, 2023

作成したページ

7rikazhexde.github.io

GitHub Pagesへの公開までの流れ

前提として以下2点がポイントでした。

作成したマークダウンファイルを流用できること
コンテンツの見やすさ

また、調査するとコンテンツは静的サイトジェネレータ(SSG)で作成し、GitHub Actionsでビルドとデプロイをして公開する方法がGitHub Pagesにおける効率的な管理手段でした。

そこで、SSGの選択とコンテンツ作成、 GitHub Pagesの設定および、GitHub Actionsによるビルドとデプロイの設定を調査して作成することにしました。

静的サイトジェネレータ(SSG)の選択

GitHub Pagesのクイックスタートページを確認すると以下の記載がありました。
https://docs.github.com/ja/enterprise-server@3.9/pages/quickstart

GitHub Pagesは、GitHubを通じてホストされ、公開されるパブリックなWebページです。立ち上げて実行するための最速の方法は、Jekyll テーマ選択画面を使って事前作成されたテーマをロードすることです。その後、GitHub Pagesのコンテンツやスタイルを変更できます。

また、他に調べると下記サイトが見つかり、SSGのプロジェクトが複数あることがわかりました。（こんなに多いんですね。）
https://jamstack.org/generators/

GitHub PagesではJekylltが必須条件というわけではなく、基本的に各SSGを使用して公開できるようです。

いろいろ考えましたが、参考サイトが採用しているmkdocsを採用することにしました。
将来的には他の静的ジェネレーターも試してみたいと思います。

基本構成と追加要素検討

基本構成はmkdocsの仕様に従います。

.
├─ docs/
│  └─ index.md
└─ mkdocs.yml

これまではコンテンツ用のフォルダを作成して、その中にマークダウンファイルを作成してREADE.md内でリンクを貼っていましたが、コンテンツ用のフォルダとマークダウンファイルはdocs以下で管理します。

mkdocsでのコンテンツ作成ではcatalogにテーマ、UI、他、様々な情報がまとめられていますが、テーマは後述するレイアウトでも説明しますが、material(Material for MkDocs)を使用することにしました。

また、コンテンツは gitの管理対象としたいと考えていました。コンテンツ作成は後述するmkdocs buildコマンドを実行する必要があるため、これらはpre-commitフックで実行する構成にしました。

さらに、追加要素としてプロジェクトのバージョン管理を自動化するため以前紹介したバージョン管理機能のPython スクリプトを導入しました。

一方でバージョン管理機能追加に伴い、pre-commitフックを使用する際、コミット前に静的解析とコードフォーマットツールを実行しますが、生成されるファイル(HTML,JS,CSS)はプロジェクト側のルールで生成されるため、フックの処理対象から除外したいと考えていました。

実際にpre-commit-hooksを設定して動作確認すると、site以下のファイルで複数回修正が入ることを確認しました。今回はコミットプロセスを考慮するとsiteフォルダ以下のファイルはフック処理の対象に含める必要性はないと判断しました。

そこで、生成されるsiteフォルダ以下のファイルは除外対象とするPython スクリプトを追加して除外対象に設定することにしました。

フォルダ構成検討

構成は下記となりました。

% tree -L 2
.
├── LICENSE
├── README.md
├── ci
│   ├── run_git_tag_base_pyproject.py 
│   │   # 2. git tag実行用スクリプト
│   ├── run_mkdocs_cmd.py 
│   │   # 4. mkdocs buildコマンド実行用スクリプト
│   ├── set_pre-commit-hooks_exclude.py 
│   │   # 3. pre-commit-hooksの指定id毎のexclude追加用スクリプト
│   └── update_pyproject_version.py
│　　　　# 1. pyprojtect.tomlのバージョン更新用スクリプト
├── create_post-commit.sh
├── docs # コンテンツ用マークダウンファイル(docs以下の構成参照)
│   ├── db_tips
│   ├── git_tips
│   ├── index.md
│   ├── markdown_tips
│   ├── python_tips
│   ├── tool_tips
│   └── vscode_tips
├── mkdocs.yml
├── poetry.lock
├── pyproject.toml
├── requirements-dev.txt
├── requirements.txt
└── site # docsを元に自動生成されるファイル
    ├── 404.html
    ├── assets
    ├── db_tips
    ├── git_tips
    ├── index.html
    ├── markdown_tips
    ├── python_tips
    ├── search
    ├── sitemap.xml
    ├── sitemap.xml.gz
    ├── tool_tips
    └── vscode_tips

docs以下の構成

% tree -L 3 docs
docs
├── db_tips
│   └── mariadb
│       └── mariadb-tips.md
├── git_tips
│   └── git-tips.md
├── index.md
├── markdown_tips
│   └── markdown-tips.md
├── python_tips
│   ├── dash_plotly
│   │   └── dash-plotly-tips.md
│   ├── post-commit
│   │   └── post-commit-tips.md
│   ├── pre-commit
│   │   └── pre-commit-tips.md
│   └── pymysql
│       └── pymysql-tips.md
├── tool_tips
│   └── tool-tips.md
└── vscode_tips
    └── vscode-tips.md

スクリプト作成

1. pyprojtect.tomlのバージョン更新用スクリプト

以下の記事を参照ください。

https://7rikazhexde-techlog.hatenablog.com/entry/2023/06/10/005231#1-update_pyproject_versionpy

2. git tag実行用スクリプト

以下の記事を参照ください。

https://7rikazhexde-techlog.hatenablog.com/entry/2023/06/10/005231#2-run_git_tag_base_pyprojectpy

3. pre-commit-hooksの指定id毎のexclude追加用スクリプト

コード

処理のポイント

1)exclude対象の作成

以下idのpre-commit-hooksでsite以下のファイルは除外するようにフォルダを検索してファイルのパスを文字列として作成します。

- id: trailing-whitespace
- id: end-of-file-fixer

2).pre-commit-config.yamlでコメントの体裁を維持する

コメントと体裁を維持するため、ruamel.yamlをYAMLからimportして、yamlファイルの読み込みと書き込み処理をすることで対応します。

3)exclude追加処理

excludeの指定はexclude: "ファイル名"とする必要があるのですが、文字列にしてから書き込むと"'ファイル名'"となるので、最初に空文字で作成してから作成した文字列を追加するようにしています。
同じ関数を2回呼ぶのは冗長でわかりづらいですが、オプション指定も分からなかったのでこの方法にしてます。

4. mkdocs buildコマンド実行用スクリプト

コード

処理のポイント

mkdocs buildを実行してsite以下にGitHub Pages用のファイルを自動生成します。その後、git diff --quiet --exit-codeで差分があればgit addします。

そもそもsite以下のフォルダをgitの管理対象にしない場合は不要ですが、対象とする場合は毎回差分になるのでpre-commitでgit addを実行します。

GitHub Actionsの設定とmkdocs.ymlの作成

mydocsでは静的サイト用のファイルはgh-pagesというブランチを作成して管理されます。
ブランチはmkdocs gh-deployコマンドで作成され自動でPushまで実行されます。

次に、Github ActionsでGitHub Pagesをデプロイする場合には、対処のリポジトリを設定する必要があります。

Github ActionsによりGitHub Pagesの公開元設定を元に、リポジトリのSettings->Pagesからgh-pagsブランチを設定します。

もし、ブランチ設定が正しく行われていない場合、下記のようにビルド時にエラーとなります。元々、テスト用リポジトリで動作確認をしていましたが、本番用リポジトリでmkdocs gh-deployコマンドを実行し忘れた結果、以下エラーとなりました。

詳細は未確認ですが、GitHub Pagesの説明に以下記載があり、デフォルトではビルドプロセスにJekyllが指定されているようです。

Jekyll 以外のビルドプロセスを使用する場合、または専用ブランチでコンパイル済みの静的ファイルを保持したくない場合は、GitHub Actions ワークフローを記述してサイトを公開することをお勧めします。 GitHub には、ワークフローの記述に役立つ一般的な公開シナリオ用のスターターワークフローが用意されています。

次に、GitHub Pagesにデプロイするために必要なGitHub Actions設定ファイル(push_gh-deploy.yml)をpublishing-your-siteを参考に作成しました。

.github/workflows/push_gh-deploy.yml

この設定ファイルにより新しいコミットがmain ブランチにプッシュされると、静的サイトが自動的にビルドされてデプロイされます。

処理のポイント

branchはmainのみとし、未定義警告への対応として、env.cache_idの初期化処理を追加してます。

未定義の場合は、Context access might be invalid: cache_idが表示されるため空文字""の初期化処理を追加してます。

レイアウト選択

レイアウトはほぼゼロから学ぶPython(mkdocs.yml)を参考にさせていただきました。

その他、色指定、features、等はMaterial for MkDocs(mkdocs.yml)とMkDocsによるドキュメント作成を参考にさせていただきました。

タブを追加することも考えましたが、記事内容的にセクションは増えていくと見づらくなると思ったので有効にはしませんでした。
今後mkdocs.ymlを変更することはあると思いますが、今のところ下記で満足しています。

site_name: Dev Insights Tips
repo_name: 7rikazhexde/dev-insights-tips
repo_url: https://github.com/7rikazhexde/dev-insights-tips
copyright: "&copy; 2023 7rikazhexde"

theme:
  name: material
  palette:
    # ライトモード
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: indigo
      accent: blue
      toggle:
        icon: material/weather-sunny
        name: ダークモードに切り替え
    # ダークモード
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: blue
      accent: blue
      toggle:
        icon: material/weather-night
        name: ライトモードに切り替え
  font:
    text: Noto Sans
    code: Inconsolata
  language: ja
  icon:
    repo: fontawesome/brands/github
  features:
    - navigation.instant
    - navigation.top
    - content.code.copy
    #- navigation.footer
    #- navigation.tabs
    #- navigation.indexes
    - navigation.sections
    #- navigation.tabs
    #- navigation.top
    - navigation.tracking

GitHub Actionsによるビルドとデプロイ結果

mainブランチの変更をPushすると、GitHub Actionsによるフローが実行され、正常にビルドとデプロイが完了し、サイトの内容も更新されていることを確認できました。

まとめ

本記事では、MkDocsで技術系Tipsを作成してGitHub Pagesで公開する内容について、主に以下内容を紹介しました。

MkDocsによるコンテンツ作成方法
GitHub PagesにるGitHub Pagesへの公開方法
各種設定方法

作成したサイトはじめに - Dev Insights Tipsは随時更新していきますので、
気になればスターやブックマークなどして頂けると嬉しいです。

参考記事

以下の記事を参考にさせていただきました。

Qiita / Hugo で静的なサイト・ブログを構築しよう
https://qiita.com/peaceiris/items/ef38cc2a4b5565d0dd7c

Jamstack / Site Generators
https://jamstack.org/generators/

mkdocs / catalog
https://github.com/mkdocs/catalog

DevelopersIO / プロジェクトドキュメント構築向け静的サイトジェネレータ『MkDocs』及び『Material for MkDocs』の個人的導入＆設定まとめ
https://dev.classmethod.jp/articles/mkdocs-and-material-for-mkdocs-tips-matome/

Github Pages / ゼロから学ぶPython
https://rinatz.github.io/python-book/

Zenn / MkDocsによるドキュメント作成
https://zenn.dev/mebiusbox/articles/81d977a72cee01

GitHub PagesをMKDocsで作ってみた
https://enu23456.hatenablog.com/entry/2022/11/11/192039

以上です。