【共有メモ】Hugo: PaperModを使いこなす
プロジェクトページを Hugo + Github Pagesで公開する方法についての記事です. 全体的な流れは以前の記事を参考にしてください.
実際のところ, 選択したHugo のテーマによって ページの更新・公開方法, ページの全体設定が異なってくるため, ちゃんと運用するにはもう一段階詳しい説明が必要となる.
ここでは, わたしのお気に入りで実際に公開ページとして使用しているPaperModについて説明する.以下のページには Demo ページもついているので, 少しデザインを試してみたいという方でも参考にしやすいです.
(2026/02/03: 追記)
PaperModで使用されるサイトアイコンの自作記事を紹介しました
Hugo: PaperModとは
シンプルなページデザインで, 記事の一覧, アーカイブ, 検索機能をもつ
また, Home画面も３つのデザインが用意されている.
Homeinfo Mode
上部に 簡単な紹介コメント, 各SNSアカウントのリンク, 以下に最新記事が表示される.
Profile Mode
アイコンだけのホーム画面. 情報が最小限でみやすい🤩
設定項目
webページ全体の設定内容は, hugo.yamlに記載されている.いろいろな設定内容が含まれているが, ここでは最低限知っておくべきものに限定して説明する.
全体ページ情報
baseURL: "https://***.github.io/" # ページ内の基本URLを設定 大事!!
languageCode: "ja-JP"
title: "ページタイトル"
theme: ["PaperMod"] # Hugoテーマの設定
まずは全体の設定項目である. 上記のものは最低限書くようにする.
baseURLについては, Webページ内に各所に記述されているページのURL情報のベースとなるので, 公開しているGithub pagesのURLを記述するようにする.
メニュー情報
menu:
main: # ヘッダーのタブ情報
- identifier: about # Aboutページの追加(参照するmd名）
name: about # Webで表示されるページ名
url: about/ # 対応するURL
weight: 10 # タブ側の表示並びの優先順位
- identifier: member # memberページの追加
name: member
url: member/
weight: 11
- identifier: search # searchページの追加
name: search
url: search/
weight: 12
- identifier: tags
name: tags
url: tags/
weight: 13
- identifier: archives
name: archives
url: archives/
weight: 14
menuには, ページ上部にあるメニューバーにある各ページへの遷移リンクを管理できる. この設定では, about,member,search,tags,archivesのページが追加されている. about,memberは元のデザインに追加したものである.
何か新しいページを追加したい場合は, このmenuに追加することとなる.
ちなみに, 追加したいページは, /test-site/content/***.mdとして追加する.
ここで, weightは, メニューバーにある各ページ名の並びに影響を与える.
例えば, about,member,search,tags,archivesと並んでいるのは,
about(weight = 10) > member (weight = 11) > search ((weight = 12) > tags (weight = 13) > archives (weight = 14)である.
詳細設定
もう少し深くページ設定ができるようになっている
全般的なもの
env: production # to enable google analytics, opengraph, twitter-cards and schema.
title: "タイトル"
description: "ExampleSite description"
keywords: [Blog, Portfolio, PaperMod]
author: Me
# author: ["Me", "You"] # multiple authors
images: ["<link or path of image for opengraph, twitter-cards>"]
DateFormat: "January 2, 2006" # 記事作成日
defaultTheme: auto # ページのテーマ設定 "dark", "light"も決められる
disableThemeToggle: false # dark/light の変更ボタンを表示するかどうか
ShowReadingTime: true # 各記事の読み終わるまでの時間を表記するかどうか
ShowShareButtons: false # 各記事の下部に表示するshareボタンの表示の有無
ShowPostNavLinks: true # 前後のポストへのNavigationを表示するかどうか
ShowBreadCrumbs: true # 各記事の階層関係を表示するかどうか
ShowCodeCopyButtons: false # 記事内のコードをコピーするボタンを表示するかどうか
ShowWordCount: true # 各記事の文字数を表記するかどうか
ShowRssButtonInSectionTermList: true # RSSボタンの表示の有無
UseHugoToc: true #
disableSpecial1stPost: false # スペシャル記事の表示有無
disableScrollToTop: false # 最上部へのスクロールボタンの表示の有無
comments: true # コメントを記事に表示するかどうか
hidemeta: false # Search対象から各記事のmeta情報を隠すかどうか
hideSummary: false # Search対象から各記事のSummaryを隠すかどうか (個別に隠すなら各記事でどうぞ)
showtoc: true # TOCを表示するかどうか
tocopen: false # 初期で展開しておくかどうか
ここは, 各記事の表示に関わる内容が多い. 例えば, showtocは, 各Markdown記事の冒頭に, ToC(tabel of content)を表示するかどうか決める. また, ShowBreadCrumbsは, 各記事がどのようなページ階層にあるのか, その履歴を辿れるような表記を残せる.
基本的は,この設定を流用すると良いと思う...
Home設定
label: # ヘッダー上部のタイトル情報
text: "Home"
icon: /apple-touch-icon.png
iconHeight: 35
# profile-mode
profileMode:
enabled: false # needs to be explicitly set
title: ExampleSite
subtitle: "This is subtitle"
imageUrl: "<img location>"
imageWidth: 120
imageHeight: 120
imageTitle: my image
buttons:
- name: Posts
url: posts
- name: Tags
url: tags
# home-info mode
homeInfoParams:
Title: "Welcome!! \U0001F44B"
Content: >
👋 勉強共有会へようこそ！！
- 現在、サイトを準備中です 😇
- それまでは過去の議事録を参照してください！！
socialIcons: # ホーム画面に表示する各種サービスアイコン
- name: x
url: "https://x.com/"
- name: stackoverflow
url: "https://stackoverflow.com"
- name: github
url: "https://github.com/"
- name: discord
url: "https://discord.gg/"
前述した, Home画面の表示を, ProfileModeとするか, HomeinfoModeにするかの設定, 各内容の設定項目である. デフォルトはHomeinfoModeなので, ProfileModeが良いという人は,
profileMode:
enabled: true # needs to be explicitly set
とする.
socialIconsは, 保有しているサービスのアカウントとそのサービスアイコンに関するものである. nameの部分を変更したら, アイコンは勝手に変更してくれるので,以下のページを参考に, 必要なアカウントを置いておこう.
カバー画像 & 編集指示
cover:
hidden: true # カバー画像をそもそも表示するかどうか
hiddenInList: true # Home および リストページ でのカバー表示をするかどうか
hiddenInSingle: false # 記事単体ページでのカバー画像を表示するかどうか
responsiveImages: false # 画像サイズを小さくするかどうか
linkFullImages: false # 画像にハイパーリンクをつけるかどうか
editPost: # 記事への編集依頼を出すボタン
URL: "https://github.com/<path_to_repo>/content" # 当該記事のGithubpageへ飛ぶ
Text: "Suggest Changes" # edit text
appendFilePath: true # to append file path to Edit link
coverは, 各記事でカバー画像を表示するかどうかに関する設定項目である.ここでは, 記事全体に関する情報を管理する.
では,具体的にどんなカバー画像を載せるのか,という画像URLは各記事のmarkdownに記載することとなる.
例えば, memberページを作る, /content/member.mdには以下のような設定を組み込める.
---
title: "Member"
layout: "member"
url: "/member/"
summary: member
date: 2025-07-09
author: ["Akitek"]
cover:
image: "images/tn.png" # 記事にカバーをつけたい場合 [assets/imagesに配置]
hiddenInList: true
---
editpostは 対応する記事のGithubページに移動し, 編集依頼を出す？ページ遷移処理を, 各記事に組み入れるかの設定である. （どんな場面で使用するかは不明）
記事の検索機能
PaperModの魅力としては, 過去記事の検索機能だと個人的に考える.
その検索機能(search)に関する設定項目(fuseOpts)もある.
検索方法や,検索対象となる文書, 表示内容についていろいろと設定できる.
# for search
# https://fusejs.io/api/options.html
fuseOpts: # search機能に関する設定
isCaseSensitive: false # 大文字小文字を識別するかどうか
shouldSort: true # スコアで記事をソートするかどうか
location: 0 #
distance: 1000
threshold: 0.4
minMatchCharLength: 0
limit: 10 # 検索結果の最大表示数 refer: https://www.fusejs.io/api/methods.html#search
keys: ["title", "permalink", "summary", "content"] # 記事ごとの検索対象となる要素（ここに含めた要素の中の文字を検索する）
具体的なページ＆記事追加例
hugo.yamlでのページ全般の設定を見てきたので, 運用面での具体例を見ていく.
いま,フォルダ階層が以下のようになっているとする.
.
├── archetypes
│ └── default.md
├── assets # 各種カバー画像や画像を配置
│ └── images
│ └── tn.png
├── content # ページ・記事の配置
│ ├── about.md
│ ├── archives.md
│ ├── member.md
│ ├── posts
│ │ └── testpost.md
│ └── search.md
├── data
├── hugo.yaml # ページ全体の管理情報
├── i18n
├── layouts
├── public # Github PagesにPushするもの
├── static
└── themes
└── PaperMod
追加でページや記事を書きたい
まずページを追加したい場合 /contennt/以下に, test.mdのようなファイルを作る. このtestというのがページ名になる.
このページをメニューバーに表示するため hugo.yamlを編集する
menu:
main: # ヘッダーのタブ情報
- identifier: about # Aboutページの追加(参照するmd名）
name: about # Webで表示されるページ名
url: about/ # 対応するURL
weight: 10 # タブ側の表示並びの優先順位
- identifier: member # memberページの追加
name: member
url: member/
weight: 11
- identifier: search # searchページの追加
name: search
url: search/
weight: 12
- identifier: tags
name: tags
url: tags/
weight: 13
- identifier: archives
name: archives
url: archives/
weight: 14
- identiifier: test
name: test
url: test/
weight: 15
この状態で, hugo serverしてみて, http://localhost:1313/で, 反映されていれば成功
次に, 記事の追加について. 専用のページでは,記事を投稿する場合は, /content/posts/以下に***.mdを作成する. 上の例では, /content/posts/testpost.mdという記事ができている. ここに追加することで, Home画面や, archives,searchのところにも反映される.
専用のページと違い, hugo.yamlへの対処は不要
Github Pagesへの反映
さて, ローカルで作成したページ＆記事を公開するには, Github で作成したRepositoryをローカルにCloneしたローカルレポジトリに, /public/以下のフォルダをコピーし, そして, リモートにpushすればよいと説明した.
ただ, ここで個人的にはまってしまったのが, 各ページに紐づくリンク情報の反映である.
実際, みなさんのほうで確認してほしいのだが, /public/index.xmlのリンク情報は正しくなっているだろうか？
場合によっては, localhost:1313/というリンクがあちらこちらに配備されている. このままGithub Pagesにpushしても, 公開先のページ遷移が失敗する(localhost:1313/aboutとリンク情報がなっていたらページ遷移できないはず. そんなページはネットでは公開されていないっため）
そのため, 作成したwebページのリンク情報を正しくするには以下の２つのことを必ず行う
baseURLの設定
hugo.yaml内のbaseURLを公開先のhttps://***.github.io/に置き換える.
baseURL: "https://[アカウント名].github.io/"
languageCode: "ja-JP"
title: "タイトル"
theme: ["PaperMod"]
作成したwebページをビルドする
基本的に /public/以下を直接編集することはしない. /content/に追加・更新した要素は, hugoコマンドでビルドすることで, 勝手に/public/に内容が反映される.[1]
ローカルのWebページのrootディレクト(/test-site)上で, $ hugoコマンドを打つことで簡単にビルドできる.
このビルド後の/public/以下のフォルダをGithub Pagesにpushしよう.
また, リンク情報が正しくなっているかは, /public/index.xmlを確認してみるとよい.
まとめ
今回は, HugoのPaperModというテーマを用いた, ページ・記事の追加や公開方法について説明した.
Hugo にはさまざまなテーマが用意されているが, ページ・記事の追加や公開方法はそれぞれテーマごとに違ってくる.
なので, 他のテーマでやってみたいという方は, 各テーマのプロジェクトテーマをしっかりと読むようにしてください.
参考サイト
Hugoにはいろいろなテーマが公開されている. ぜひご自身の気に入ったテーマでプロジェクトページを公開しよう
リンク情報が反映されない...と思ったときの問題点を解決してもらえた記事. この記事のいうことをちゃんと聞きましょう（一敗）
追記：
HUGOでは,有名なサイト・SNSのアイコンは.yamlファイル上で自由に設定・利用することができる.
逆に, QiitaやZennなどのサービスアイコンは, デフォルトでは用意されていない.
だが, 以下の記事を参考に, 自作サービスアイコンを作成し利用することはできる, とのこと.
-
逆に, ビルドしなければ,
/public/の内容をGithub Pagesにpushしても古い情報のままなので注意が必要. ↩︎
Discussion