Notion執筆→Markdown変換→Hugoビルド→GitHub Pagesデプロイへとつながるブログ構築の流れを表したアイキャッチ画像

はじめに

技術関連の内容をEvernoteや個人ドキュメントに整理してきたが、Notionのウェブサイト機能を活用してブログとして運用しようと準備していた。

しかし、Notionはカスタマイズに制約があり、カスタムドメインの利用にも追加費用が発生するため、少し悩むことになった。

代案としてvelogに切り替えるか、Markdownで書き直してJekyllに移行するか検討した。

しかし、書きやすいNotionを諦めることはできなかった。結論はNotionで執筆し、静的ウェブサイトとしてデプロイすること!

目標

  • mdファイルで書かれたドキュメントをHugoでビルドし
  • GitHub Pagesでデプロイを自動化する

💡 構築環境

  • テスト環境: Mac
  • デプロイ環境: GitHub Actions

Hugoを選んだ理由

  • GitHub Starの数が多く、活発に更新されている
  • 1000ページ以上をビルドする際にJekyllより速い

現在このブログは次のような流れで運用している。(ソース参考: )

Notionで執筆
→ Notion APIでMarkdownに変換

→ Hugoで静的サイトをビルド

→ GitHub Pagesにデプロイ

事前準備

Hugoテーマの選定

Hugo Themesでテーマをまず選んだ。

選んだテーマ: m10c

テーマ選定基準

  • SEO最適化機能をサポート
  • 多言語サイト機能をサポート

m10cは一部機能が完全にはサポートされていないが、Hugoのレイアウトオーバーライドで補完できる。

Hugoのインストール

インストールドキュメント: Installation Guide

Hugoドキュメント: Documentation

Macの例

1# Hugoをインストール
2brew install hugo
3
4# インストール確認
5hugo --version

Hugoサイトの作成

プロジェクトの初期化

 1# 作業ディレクトリを作成
 2mkdir hugo && cd hugo
 3
 4# Hugoサイトを作成
 5hugo new site .
 6
 7# 生成結果を確認
 8tree
 9# .
10# ├── archetypes
11# │   └── default.md
12# ├── assets
13# ├── content
14# ├── data
15# ├── hugo.toml
16# ├── i18n
17# ├── layouts
18# ├── static
19# └── themes

テーマのインストール

Git submoduleを使ってテーマをインストールする。

1# Gitリポジトリを初期化(必要な場合)
2git init
3
4# テーマのsubmoduleを追加
5git submodule add https://github.com/vaga/hugo-theme-m10c.git themes/m10c
6
7# インストール確認
8ls -al themes/m10c

サンプルコンテンツのコピー(任意)

1# テーマのサンプルコンテンツをコピー
2cp -R themes/m10c/exampleSite/content ./content
3
4# 確認
5ls -al ./content/

Hugoの設定

デフォルトの設定ファイルであるhugo.tomlをテーマのサンプル設定に置き換える。

1# 既存の設定を削除
2rm hugo.toml
3
4# サンプル設定をコピー
5cp themes/m10c/exampleSite/config.toml ./hugo.toml

hugo.tomlファイルを開いて基本設定を修正する。

1baseURL = "https://testblog.plzhans.com"
2title = "Test blog"
3theme = "m10c"

注意: themesDir設定は削除し、themeは実際のディレクトリ名と一致させる。

ローカルサーバーの実行

1# 開発サーバーを起動
2hugo server -D

実行結果の例:

1Watching for changes in /Users/plzhans/temp/sample/hugo/...
2Start building sites …
3hugo v0.154.5+extended+withdeploy darwin/arm64 BuildDate=2026-01-11T20:53:23Z
4
5Built in 2 ms
6Environment: "development"
7Web Server is available at http://localhost:57264/
8Press Ctrl+C to stop

ブラウザで表示されたアドレスにアクセスして確認する。

http://localhost:57264

GitHub Pagesへのデプロイ

リポジトリの作成

GitHubで新しいリポジトリを作成する。

デプロイ戦略の選択

JekyllとHugoはいずれもソースとビルド成果物を分離して管理する。

Jekyllは GitHub Pagesが自動的に検知してデプロイするが、Hugoは GitHub Actionsを通じて直接デプロイする必要がある。

デプロイ戦略を選ぶ際に注意すべき点は、ソースリポジトリの公開・非公開の有無である。

ソースリポジトリを非公開にしたい場合は、以下の点に注意すること。

無料プラン

  • 公開リポジトリのみPages設定が可能である。
  • そのためソースを非公開にしたい場合は、方法3を使ってソースリポジトリを非公開にし、デプロイ用リポジトリのみ公開する必要がある。

有料プラン

  • リポジトリが非公開でもPagesは公開可能

方法1: actions/deploy-pages

  • リポジトリを1つ使用
  • GitHub PagesのソースをGitHub Actionsに設定
  • mainブランチへのpush → Hugoビルド → 成果物のアップロード → 自動デプロイ

方法2: peaceiris/actions-gh-pages

  • リポジトリを1つ使用
  • GitHub Pagesをgh-pagesブランチに接続
  • mainブランチへのpush → Hugoビルド → gh-pagesブランチにコミット

方法3: デプロイ用リポジトリを分離

  • リポジトリを2つ使用(ソースリポジトリ、デプロイ用リポジトリ)
  • ビルド成果物をデプロイ用リポジトリにプッシュ

方法4: ビルド成果物を外部にアップロード

  • GitHub Pagesを必ず使う必要はない。
  • ウェブサーバーが接続されたディレクトリにビルド成果物だけをアップロードしてもよい。
  • デフォルトでは成果物は/publicディレクトリに生成される。

この文書では方法1を使ってデプロイ戦略を組み立てた。

GitHub Pagesの設定

Repository → Settings → Pages → SourceをGitHub Actionsに設定

GitHub Actionsワークフローの作成

.github/workflows/deploy-hugo.ymlファイルを作成する。

 1name: Deploy Hugo
 2
 3on:
 4  push:
 5    branches: [ master ]
 6   
 7permissions:
 8  contents: read
 9  pages: write
10  id-token: write
11
12concurrency:
13  group: pages
14  cancel-in-progress: true
15
16env:
17  HUGO_BASEURL: https://plzhans.github.io/hugo-sample/
18
19jobs:
20  build-and-deploy:
21    runs-on: ubuntu-latest
22    env:
23      HUGO_CACHEDIR: /tmp/hugo_cache
24
25    steps:
26      - name: Checkout
27        uses: actions/checkout@v4
28        with:
29          submodules: recursive
30          fetch-depth: 1
31
32      - name: Setup Hugo
33        uses: peaceiris/actions-hugo@v3
34        with:
35          hugo-version: "latest"
36          extended: true
37
38      - name: Cache Hugo
39        uses: actions/cache@v4
40        with:
41          path: $ env.HUGO_CACHEDIR 
42          key: $ runner.os -hugomod-$ hashFiles('**/go.sum') 
43          restore-keys: |
44            $ runner.os -hugomod-
45
46      - name: Build
47        run: hugo --minify --gc --cleanDestinationDir --baseURL "$HUGO_BASEURL"
48
49      - uses: actions/upload-pages-artifact@v3
50        with:
51          path: ./public
52
53      - uses: actions/deploy-pages@v4

Gitでのデプロイ

 1# リモートリポジトリを追加
 2git remote add origin [email protected]:plzhans/hugo-sample.git
 3
 4# .gitignoreを設定
 5echo "/public/" >> .gitignore
 6
 7# 全ファイルをコミット
 8git add . 
 9git commit -m "first commit"
10
11# ブランチを作成してプッシュ
12git branch -M master
13git push -u origin master

デプロイの確認

GitHub Actionsタブでワークフローの実行を確認し、Settings → Pagesでデプロイされたurlを確認する。

例のアドレス: https://plzhans.github.io/hugo-sample/

注意事項

baseURLの設定

hugo.tomlのbaseURL、またはビルド時の--baseURLオプションが正しくないと、CSSと画像のパスが誤っていてエラーが発生する。

このガイドでは、GitHub Actionsワークフローの環境変数HUGO_BASEURLにデプロイ先アドレスを設定した。

関連記事