HugoとGitHub Pagesでポートフォリオを作る手順｜旧Academicテーマとの違い

2019年9月15日2026年10月12日

HugoはMarkdownから静的なWebページを生成するツールです。GitHub Pagesへ公開するには、Hugoのビルドと、GitHub側の公開設定を両方用意します。Gitへpushしただけで公開されるとは限りません。

この記事の元の作例はAcademicテーマを使った過去の構築記録です。現在の新規制作では、利用するテーマが指定するHugoの版・依存関係を確認し、現行の公式手順を使ってください。以下は公式資料に基づく準備と確認の案内で、今回の環境で公開まで実行した結果ではありません。

Hugo・Gitと、テーマの条件を確認する

Hugo公式Quick startとWindowsへのインストールで必要な版を確認します。テーマによってExtended、Go、Node.jsなどが必要になるため、テーマのREADMEも確認してください。

PowerShellで次のコマンドが実行できるか確認します。

hugo version
git --version

手動でhugo.exeを配置した場合は、Windowsの環境変数の編集画面で、そのフォルダーをユーザーのPathへ追加し、新しいターミナルで確認します。古い記事のsetx /MでPath全体を書き換える方法は使いません。既存のPathを壊すと、別のツールも起動できなくなるためです。

ローカルでサイトを作り、先に表示を確認する

自分が管理する作業フォルダーで、公式Quick startのプロジェクト作成手順を進めます。
維持されているテーマを選び、そのテーマの導入手順に従います。旧Academicのフォルダー構成を別テーマへそのまま当てはめないでください。
サイト名、プロフィール、作品と画像を設定します。一般に本文はcontent、変換せず配置するファイルはstaticへ置きますが、テーマによる構成の違いを確認します。
プロジェクトのルートでhugo serverを実行し、ターミナルに表示されたローカルURLで確認します。
hugoでビルドできるか確認します。通常の出力先はpublicですが、設定で変更できます。

hugo server
# 表示確認後、Ctrl+Cでサーバーを終了します。
hugo

baseURLは実際の公開先に合わせます。ユーザーサイトとプロジェクトサイトではパスが異なり、画像・CSSの参照先にも影響します。

GitHub Pagesへ公開する

Hugo公式のGitHub Pages手順は、GitHub Actionsでビルド・公開する方法です。ソースをリポジトリで管理し、生成されたpublicの内容をコミットする方法と混ぜないでください。

自分のGitHubアカウントでリポジトリを用意し、ローカルのソースと接続します。
対象リポジトリのSettings→Pagesで、SourceをGitHub Actionsにします。
公式のワークフローを使い、ブランチ名・Hugoの版・公開URLを自分の環境に合わせます。
ソースをコミットしてpushし、Actionsのビルドとdeployの結果を確認します。
公開URLを匿名で開き、作品ページ、画像、CSS、スマホ表示を確認します。

SSHを使う場合、GitHubへ登録するのは公開鍵です。秘密鍵・アクセストークンや、公開許可のない案件データをリポジトリへ入れないでください。公開対象・無料利用の条件はGitHub Pages公式で確認します。

旧Academicテーマの掲載画面

元記事はacademic-kickstart、config/_default、content/home・authors・project・publication、staticを使った作例でした。生成物をdocsへ出力する設定と、docs内でGitを初期化する記述もありました。現行のActions方式とは別の運用です。

既存サイトを保守する場合は、実際のテーマ・Hugoの版・設定・GitHub PagesのSourceを確認し、バックアップを取ってから変更します。以下の元記事の画像は当時の画面で、現行手順の検証画像ではありません。