【共有メモ】勉強会ページをHugo + Github Pages で作成する
本記事は以下の対象者に向けての内容となっています.
- 勉強会議事録を公開したい!!
- 個人プロジェクトページを作成したい!!
- 日々の勉強ブログを, 好きなテーマで作りたい...
これらの要望に対し, 本記事では Hugo + Github Pagesで実現する方法の紹介・メモになります.
最後の方に, いろいろな実現方法を一覧で示しているので, Hugo + Github Pages以外のオプションをご検討のかたにも役立てば嬉しいです.
背景
日々の学びを共有する方法として, ZennやQiita、Hatena のような技術ブログを使用することは多い.
ただ,複数ユーザーが関わるようなプロジェクト・活動のページを作りたいとなると, もう少し画面のデザインや記載できる情報にこだわりたいと思うだろう.
例えば, 個人的にかっこいいプロジェクトページに谷口先生の「集合的予測符号化」プロジェクトページがある.
そんな複数人が参加する活動の公式ページを作成したい（と言ってしまえばただの憧れ）という想いから,活動ページを作成したいと考えた.
Hugo + Github Pages
Hugo とは
ひとこといえば,Go言語ベースの静的サイトジェネレーターである.
静的サイトとは,事前に作成しているサイト(HTML,CSS,Javascript）に基づき,単にページを表示するだけである.
それだけに, Hugoはサイトの生成がとても高速であることが知られている.
あと個人的に気に入っているのは, 「記事をMarkdownで記述できる」 ことである.というのは, ページは基本的にHTMLでその表示内容を記述しなければいけないが,いちいちHTMLを書くのは面倒である...
例えば議事録を記載するためのページであれば, HTMLを凝ってサイトページを作成する意欲は低く, むしろ, 即座にページを記載・作成できるほうが、活動の継続性も維持できる.
Markdownであれば, 慣れた操作でページ内の内容を直感的に記載できるので, 開発効率はかなり改善されると思う.
準備編
Hugo + Github Pages で活動ページを作成するための準備を説明する.
といっても必要なのは
- HugoをPCにインストールする
- Githubのアカウントを作成する
- GitをPCにインストールする
だけである.
2. Githubのアカウント作成や, 3.Gitのインストール についてはこの記事では割愛する.(いろいろ記事があるので、ご自身のOSに合わせてご対応ください）
Hugo をPCにインストールする
今回は, Macへのbrewを用いたインストール方法を説明する.[1]
HugoをMacにインストールするにはターミナルで以下のコマンドを打つだけ.
$ brew install hugo
Hugoがインストールされているかは$ hugo --helpを打つことで確認できる.
Hugoで静的サイトを初期作成する
それでは,HugoでローカルにWebサイトの雛形作成を行う.
任意の場所で以下のコマンドを入力する.
$ hugo new site <作成するサイトディレクトリ名>
ここでは、<作成するサイトディレクトリ名>として、test_siteとする.[2]
すると,test_siteというディレクトリが作成され,その中には以下のような各種フォルダーが入っている.
/test_site
├── archetypes # Mdのテンプレート置き場
├── assets
├── content # ページの置き場
├── data
├── hugo.toml # サイト全体の設定ファイル
├── i18n
├── layouts
├── public # Github Pagesに配置するフォルダ(後述）
├── static
└── themes # 好きなページテーマを配置
テーマを設定する前に、デフォルトのWebページを確認することができる. /test_siteに移動して、$ hugo serverを実行する. すると、ブラウザ上でlocalhost:1313で打ち込むと、現在の静的ページが確認できる.
が,何も表示されないはずである. その理由は、まだWebページのレイアウトを何も記述していないため である． では,次に好きなレイアウトテーマを導入していこう.
Hugo テーマを選択する
好きなレイアウトテーマを,公式ページからダウンロードすることができる.
各テーマページ内のDownloadボタンを押せば, 各Githubに移動するので, ダウンロードの方法や, ページ設定などの詳細な情報はそちらで確認する.
今回は, お気に入りのデザインであるPaperModの導入例を述べる.
テーマは,git cloneで導入する./test_site/themesに移動し、以下のコマンドを打つ[3].
/themes $git clone https://github.com/adityatelange/hugo-PaperMod themes/PaperMod --depth=1
そしたら,/themes以下にPaperModが追加されていることがわかる.
次に,このダウンロードしたテーマPaperModを,Webサイトに反映するために,hugo.ymlに以下のコードを追加する.
theme: ["PaperMod"]
変更されたかどうかは,/test-site下でhugo serverでWebサイトを表示してみるとよい.
Github Pagesをつくる
Hugo で作成したWebページを公開する手段としてGithub Pagesを使用する.
といっても,特別なことはなく, みなさんのGithubアカウントで, 新規のPublicのRepositoryを作成するだけである.
このときにレポジトリの名前は,[アカウント名].github.ioにする[4]．
作成後は,[アカウント名].github.io と URLを打つことで, このRepositoryに紐づいているWebページ(HTML)が表示されるようになる.
が,まだ何のWebページもアップロードしていない(このRepositoryに配置していない)ためうまく表示されないはずである.
そこで, 最後の方法として, 作成したHugoのWebページをこのRepositoryに配置することになる.
Github Pagesにサイトを公開する
方法としては,
- Githubで作成した公開用Repositoryを,ローカル環境にCloneする
- 作成したWebページを、1. のローカルRepositoryにコピーする
- コピー後, ローカルレポジトリをリモートにPushし, 内容を更新する.
1については,例えば, test-siteと同じ階層に,ローカルレポジトリを配置するようにしてみる.
$ git clone https://github.com/[アカウント名]/[アカウント名].github.io.git
- 以下、クローン後のレポジトリの位置関係
.
├── /[アカウント名.github.io]
├── /test-site
├── /public
...
ここで, ローカルで作成したWebページを[アカウント名.github.io]にコピーするのだが, その対象として, /test-site/public以下の各フォルダとする.
つまり,以下のコマンドで, /test-site/public以下を[アカウント名.github.io]にコピーする.
/test-site $ cp -r public/* ../[アカウント名].github.io
あとは, この/[アカウント名.github.io]のローカルレポジトリを, リモートにpushするだけである.
/[アカウント名].github.io $ git add .
/[アカウント名].github.io $ git commit -m "commit"
/[アカウント名].github.io $ git push origin main
https://[アカウント名].github.io/ にアクセスすると，作成したWebページが見れるようになっているはずである.
まとめ
今回は, Hugo + Github Pagesで, プロジェクトページを公開する方法を簡単に説明した.
今回は 具体的なテーマ内の設定項目(例えば, PaperModの設定)やページの追加やMdの記入方法といった運用方法については説明を飛ばした.
次回は, そのあたりを詳しく説明できればと思う.
少しハマった点もあったので、備忘録や同じ失敗にハマってしまった人に対し、参考になれば幸いです.
Hugoの拡張などの有用なツールに関する情報をまとめている
参考サイト
こちらを見ていただけたら, ほとんどの導入の流れはわかると思う. ただ, 導入テーマが異なると, 対応方法が違ってくるので, 導入したいテーマの導入手順ページ(Github)を参考に, 調整していって欲しい
もう少しHugoについて知りたい向けの記事
おまけ: プロジェクトページをどの方法でつくればよい？
...というのを, ChatGPTに聞いてみたら, いろいろ方法を教えてもらえたので参考いただけたら.
| 条件 | おすすめ |
|---|---|
| 一番簡単に公開したい | ✅ Notion |
| きれいな構造で活動記録を積み重ねたい | ✅ Obsidian Publish（有料） |
| GitHub経験あり・本格的に公開したい | ✅ Hugo + GitHub Pages or Jekyll |
| 技術系向けの読み物としても活用したい | ✅ Zenn |
詳細な説明
✅ 初心者向け！Markdownで活動記録を公開できるおすすめアプリ／サービス
- Notion + 公開URL機能
URL: https://www.notion.so
特徴:
Markdown記法に対応（# 見出し, - 箇条書き など）
カード形式、リスト形式などで整理できる
「ページごとにURLを公開」できる
おすすめ理由:
書くだけで公開できる簡単さ
活動記録をカテゴリごとに分けて管理できる
見た目が美しい
向いてる人:
Webデザインをいじらずに、シンプルな構成で始めたい人 - Hugo（ヒューゴ）+ GitHub Pages（技術に少し詳しい方向け）
URL: https://gohugo.io/
特徴:
超高速な静的サイトジェネレーター
Markdownで記事を書いて、テーマを使って見栄えも良くできる
GitHub Pagesでそのまま無料公開できる
おすすめ理由:
活動記録が多くなっても整理しやすい
テーマが豊富（カードUI、タイムライン型など）
向いてる人:
Markdownが好きで、簡単なコマンド操作ができる人 - Obsidian Publish（有料だが非常に洗練）
URL: https://obsidian.md/publish
特徴:
Obsidian（ローカルでMarkdownを書くアプリ）の内容をそのままWeb公開
双方向リンクやタグ、カード形式なども対応
見た目もカスタマイズ可能
おすすめ理由:
日々の勉強記録 → Webに簡単公開
親しみやすいUI
費用:
Obsidian Publishは月額 $10（約1,500円） - Zenn（技術記事向けだけど勉強会ログにも使える）
URL: https://zenn.dev
特徴:
Markdownで記事を書く（ブラウザでもOK）
無料で公開可能
技術系の読者におすすめ
おすすめ理由:
参加者に活動報告を共有しやすい
自分のプロフィールページで一覧表示できる - GitHub Pages + Jekyll（ノーコード寄りの公式サポート）
特徴:
GitHubにMarkdownを置くだけで自動的にWebページが生成される
Jekyllという仕組みをGitHubが標準でサポート
テンプレート多数
向いてる人:
少しだけHTMLを触れる or コピペで対応できる人
-
Linux,Windowsでのインストール方法は、公式サイトのInstallationに記載があるのでご参考に ↩︎
-
選択するテーマによっては，
$ hugo new site <作成するサイトディレクトリ名>の後ろに，オプション-f=yamlをつける必要がある．このテーマというのは、Webサイトのレイアウトテーマのことで,後述するPaperModにはこのオプションが必要である. なので,本実装する場合には、事前に導入したいテーマを決めておくことが重要である. ↩︎ -
git clone以外の方法として, ダウンロードしたzipの展開という方法もある.他にもあるので, テーマページを参照してください ↩︎ -
必ずこういう名前にする. アカウント名をつけることが重要 ↩︎
Discussion