GitHub で Web コンテンツ(html/Markdown)を公開する

GitHub には「Pages」と呼ばれるコンテンツの Web 公開機能が標準機能があります

作成したオープンソースの説明とか、実行モジュールのダウンロード用ページ等によく使われていますが、普通に Web コンテンツの公開ツールとしても使用できます

面白い事に、Pages では Markdown ファイルも Web コンテンツとして公開できるので、Markdown で簡易的に Web ページを書くことが出来ます

注意事項

GitHub の Pages では、コンテンツファイル名と、ディレクトリ名の大文字/小文字が区別されます

このため、大文字/小文字に誤りがある URI を指定すると 404 になるので注意が必要です

一般公開するコンテンツであれば、Public でリポジトリを作るだけなので、特別な事をする必要はありません

社内だけとか、公開先を限定するのであれば、GitHub Enterprise の契約をすれば限定公開が可能になります(説明割愛します)

公開するコンテンツは、html/Markdown 共通でルート( / )か、/docs に配置します

公開設定は Setings の Page で設定します

ブランチでコンテンツ更新するのであれば、「Source」は「Deploy from a branch」のままで問題ありません

ブランチを使用するので、使用するブランチとコンテンツの配置場所( / or /docs )を指定し Save します

一度も commit していないリポジトリだとブランチ指定が出来ないので、commit 後に公開するブランチを指定します

公開される URI は「https://ユーザー名.github.io/リポジトリ名/」となります

カスタムドメインを使う事も可能ですが、不勉強につき説明割愛します

Default page の名前は「index.html」ですので、この名前で html コンテンツを作成します
(大文字/小文字が区別されるので、ファイル名には注意)

作成した html コンテンツをルート( / )か、/docs に配置し、commit & push します

今回は /docs に作成しました

公開するブランチ(main)と、コンテンツの配置場所(/docs)を指定して Save すると Web コンテンツ公開処理が走ります

しばらく(5分程度)待って Pages を再度開くと、公開 URI が表示されます

Visit site をクリックすると、default コンテンツ(/docs に置いた index.html)が表示されますし、普通にページ遷移できます

Default コンテンツの名前は「index.md」ですので、この名前で Markdown ファイル(UTF-8)を作成します

作成した Markdown コンテンツをルート( / )か、/docs に配置し、commit & push します

Markdown は / に作成しました

公開するブランチ(main)と、コンテンツの配置場所( / )を指定して Save すると html と同様にコンテンツ公開処理が走ります

5分程度待って待って Pages を再度開くと、公開 URI が表示されますので、Visit site でコンテンツ表示します

Markdown の場合は、コンテンツのトップに遷移する URL が自動表示されます

1 リポジトリ内に html と Markdown を混在することも可能なので、トップページは index.html にして、それ以外は Markdown で作成することも可能です

Markdown の場合は、GitHub 組み込みの Jekyll で静的コンテンツが生成されます

このため、コンテンツを指定する場合は拡張子を省略して指定する必要があります

拡張子(.md)まで指定してしまうと、素の Markdown が表示されてしまいます

実は html も Jekyll で静的コンテンツが生成されていますが、生成されたコンテンツの拡張子が html なので気にならないだけだったりします

Markdown の場合、ページタイトルの概念が無いのですが、Markdown ファイルの先頭に以下のような指定書くと Jekyll にページタイトルを付ける指示になります
(Jekyll 操作はネット検索してください)

---
title: "テストページ"
---

GitHub Pages のドキュメント - GitHub Docs
https://docs.github.com/ja/pages