ローカル Markdown から Hugo（Stack）と Cloudflare Pages でサイトを公開する [#DE-0001-0001]

ローカルで書いた Markdown を、Hugo + Stack テーマで静的サイト化し、GitHub 経由で Cloudflare Pages に公開するまでの流れをまとめます。Windows での Hugo Extended の導入、ローカルプレビュー、Pages のビルド設定、必要に応じた独自ドメイン設定の入口までを含みます。

想定読者: ローカルで Markdown を書く習慣はあるが、まだ自前サイトとして公開していない人。Git とコマンドラインの基本操作が分かると進めやすいです。

この手順が向いている条件:

WordPress やサーバー管理まではやりたくない
記事の元データを Markdown ファイルとして手元に持っておきたい
push をきっかけに自動デプロイされる構成にしたい

この記事で持ち帰れること

ローカルの Markdown を公開サイトにする最小構成
Hugo / GitHub / Cloudflare Pages の役割分担
Windows で Hugo Extended を入れて hugo server まで動かす手順
Pages で必要なビルド設定
独自ドメインをつなぐときの入口

背景

記事やメモを「あとから見返せる」「発信にも使える」形で残したい一方、ブラウザだけで書く CMS や、サーバー契約・WordPress 設置のような運用負荷は避けたい、という動機がありました。

そこで、ローカルの Markdown をそのままソースにし、必要なら AI で整形してから公開する流れを取りやすい、静的サイト生成 + Git 管理 + サーバレスホスティング の構成を選びました。

全体像

今回の構成は、次の 3 つだけです。

Hugo: Markdown から静的サイトをビルドする
GitHub: ソースを置き、更新を管理する
Cloudflare Pages: GitHub リポジトリを元にビルド・公開する

データの流れは次のとおりです。

flowchart LR
  md([ローカル Markdown])
  static([生成された静的サイト])
  hugo[Hugo]
  gh[GitHub]
  cf[Cloudflare Pages]
  md --> hugo
  hugo --> static
  static --> gh
  gh --> cf

この記事では、テーマとして Hugo Stack（hugo-theme-stack）を使う前提で進めます。

この構成のいいところ

この構成のよい点は、記事の元データが Markdown のまま残ること と、運用負荷が軽いこと です。

記事本文はローカルのファイルとして持てる
デザインやレイアウトはテーマ側に寄せられる
GitHub に push すれば Cloudflare Pages が自動で更新できる
個人サイト用途なら、無料で始めやすい

逆に、リアルタイム編集の CMS 的な便利さや、GUI だけで完結する手軽さはありません。ファイル管理と Git が苦でない人向け の構成です。

各ツールの役割

Hugo

ローカルで書いた Markdown を、テーマに沿った HTML / CSS の静的サイトに変換します。記事の本体は Markdown のまま保ちつつ、サイトらしい見た目にできます。ローカルでビルド・プレビューができ、無料で利用できます。

Hugo · gohugo.io
静的サイトジェネレータの公式サイト。ドキュメント、Quick Start、テーマ一覧など。

GitHub

Hugo のソース一式（content、hugo.toml、テーマなど）をリポジトリに置きます。Cloudflare Pages はこのリポジトリを参照してビルドするため、push がデプロイの起点 になります。

GitHub · github.com
ソースコードのホスティングと共同開発。リポジトリの作成・push・連携の起点。

Cloudflare Pages

静的サイトのホスティングとビルドを担います。GitHub と連携しておけば、リポジトリ更新をトリガーに再ビルド・再公開できます。個人用途なら無料枠でも十分使いやすいことが多いです。

Cloudflare Pages · pages.cloudflare.com
静的サイト向けホスティング。Git 連携によるビルド・デプロイとグローバル配信。

手順 1: Hugo を導入する

ゴール: hugo コマンドが使え、hugo version でバージョンが表示される状態にします。

全体の流れや用語の整理は、公式の Quick Start もあわせて参照しました。ここでは、Windows で Extended 版 を入れる前提です。

1. Extended 版をダウンロードする

Hugo Releases から Extended 版を入手します。一部のテーマでは Extended 版が必要になるため、最初から Extended を入れる方が無難です。

Windows の例では、hugo_extended_0.158.0_windows-amd64.zip のような zip をダウンロードします。

Hugo Releases で Extended 版を選ぶ例

2. `hugo.exe` に PATH を通す

zip を解凍し、hugo.exe のあるディレクトリを環境変数 PATH に追加します。

3. 動作確認する

hugo version

以下のように表示されれば、Hugo の導入は完了です。

hugo version の出力例

手順 2: サイトの土台を作る

ゴール: ローカルで hugo server を起動し、ブラウザでトップページが表示される状態にします。

1. サイトのルートを作る

作業ディレクトリで次を実行します。test-site は任意の名前です。

hugo new site test-site
cd test-site

2. Stack テーマを入れる

Git サブモジュールとして追加する例です。

git init
git submodule add https://github.com/CaiJimmy/hugo-theme-stack.git themes/stack

3. `hugo.toml` を最小構成で設定する

ルート直下の hugo.toml を、まずは次のような最小構成にします。

baseURL = "https://example.org/"
languageCode = "ja-jp"
title = "My New Hugo Project"
theme = "stack"

[params]
  mainSections = ["post"]

ここではまず、最小の検証用サイト を立ち上げることを優先しています。mainSections は、トップページに主として表示したいセクションです。あとで自分の運用に合わせて、たとえば ["dev", "plant", "book"] のように変えていけば大丈夫です。

4. テスト用記事を作る

動作確認用に content/posts/ 以下へ 2 本記事を置きます。

test-site/
└── content/
    └── posts/
        ├── post1.md
        └── post2.md

post1.md と post2.md は、次の内容を {post名} を post1 / post2 に置き換えて作成します。

---
date: "2026-03-21T02:11:50+09:00"
draft: false
title: "{post名}"
type: "post"
---

本文はたとえば次のようにしておけば十分です。

# {post名}

こんにちは。こちらは {post名} ページです。

5. ローカルで表示確認する

hugo
hugo server

ターミナルに表示された URL を開き、ページが表示されれば成功です。

hugo server でローカル表示できた例

手順 3: GitHub に push する

ゴール: サイトのソースが GitHub にあり、Cloudflare Pages から参照できる状態にします。

GitHub 上に空のリポジトリを作成し、ローカルから push します。

git remote add origin {リポジトリのURL}
git add .
git commit -m "first commit"
git push -u origin main

ブランチ名が main でない場合は、実際のブランチ名に読み替えてください。

手順 4: Cloudflare Pages で公開する

ゴール: *.pages.dev の URL でサイトを閲覧できる状態にします。

1. Pages プロジェクトを作成する

Cloudflare Dashboard にログインします。GitHub と連携できるようにしておき、アカウントホーム → +追加 → Pages から新しい Pages プロジェクトを作成します。

Pages でアプリを作成する例

作成フローで GitHub のリポジトリを選び、先ほど push したサイト用リポジトリを指定します。

リポジトリを選択する例

2. ビルド設定を入れる

リポジトリを選んだあと、ビルドと出力先を次のように設定します。

項目	値
ビルドコマンド	`hugo`
ビルド出力ディレクトリ	`public`
環境変数	`HUGO_VERSION` = ローカルで使っている Hugo のバージョン

HUGO_VERSION は、ローカルと Pages 側の Hugo バージョン差異でハマりにくくするために入れておくと安心です。値は hugo version で確認できます。

Pages のビルド設定例

3. 公開 URL を確認する

ビルドが完了すると、割り当てられた *.pages.dev の URL で表示を確認できます。

デプロイ成功後の画面例

ビルド完了の例

独自ドメインを使わない場合は、ここで公開まで完了です。以後は main ブランチへの push で自動デプロイが走ります。

手順 5: 独自ドメインをつなぐ（任意）

ゴール: *.pages.dev ではなく、自分で取得したドメインで同じサイトを開けるようにします。

1. ドメインを取得する

独自ドメインを使う場合は、まずレジストラでドメインを取得します。例として、さくらインターネットの .com ドメインなどがあります。価格や契約条件は時期によって変動します。

2. Cloudflare でドメインを管理できるようにする

Cloudflare の「ドメイン登録 → ドメイン管理 → ドメインのオンボード」などの手順に従い、レジストラ側の設定と合わせて DNS を Cloudflare 側で管理できるようにします。ネームサーバー変更や移管が必要になる場合があります。

ドメインのオンボード周りの画面例

3. Pages にカスタムドメインを設定する

Cloudflare の コンピュート → Workers & Pages → 対象のサイト → カスタムドメイン で、使いたいホスト名を追加します。

カスタムドメインを設定する例

DNS と証明書の反映後、自前のドメインでサイトが表示されます。

よくあるつまずきどころ

この構成はシンプルですが、最初につまずきやすい点もあります。

Hugo の通常版を入れてしまう Stack を含む一部テーマでは Extended 版が必要です。
ローカルと Cloudflare Pages の Hugo バージョンがずれる Pages 側で HUGO_VERSION を明示するとズレに気づきやすくなります。
テーマは入れたのにトップに記事が出ない mainSections と記事の配置ディレクトリがずれている可能性があります。
Push したのに公開されない Pages の対象リポジトリ、対象ブランチ、ビルド設定を再確認すると切り分けやすいです。

この構成が向く場面・向かない場面

向いているのは、ローカルで書くことを中心に据えたい個人サイト です。記事をファイルで管理できるので、Git との相性もよく、後から構成を変えやすいです。

一方で、複数人がブラウザ上で同時編集するような使い方や、管理画面ベースで完結したい使い方には向きません。そういう場合は CMS の方が合うこともあります。

まとめ

ローカルの Markdown を Hugo（Stack）で静的サイトにし、GitHub と Cloudflare Pages を組み合わせると、サーバー運用を最小限にしつつ、自分の文章を自前サイトとして公開する流れ を作れます。

今回の手順のポイントは、次の 3 つです。

ローカルでは Hugo Extended を入れて hugo server まで確認する
GitHub を Cloudflare Pages のビルド元 として使う
Pages では hugo / public / HUGO_VERSION を押さえる

まずは最小構成で *.pages.dev まで出し、必要になったら記事構成や独自ドメインを育てていく、という順番が取りやすいと思います。