Hugo のインストールから、PaperMod を使った運用・細かいハマりどころまでをまとめたメモ。
「一度やったけど忘れる」前提の、自分用 HowTo。

1. 前提

  • OS: macOS / Windows / Linux（コマンド差は最小限）
  • 静的サイトジェネレータ: Hugo
  • テーマ: PaperMod
  • 設定ファイル: hugo.toml

2. Hugo のインストール

macOS（Homebrew）

brew install hugo

Windows（Scoop）

scoop install hugo-extended

Fedora

sudo dnf install hugo

バージョン確認

hugo version

3. 新規サイト作成

hugo new site myblog
cd myblog

ディレクトリ構成（初期）:

myblog/
├─ archetypes/
├─ content/
├─ layouts/
├─ static/
└─ hugo.toml（または config.toml）

4. PaperMod テーマの導入

submodule で追加（推奨）

git init
git submodule add https://github.com/adityatelange/hugo-PaperMod themes/PaperMod

hugo.toml にテーマ指定

theme = "PaperMod"

5. ローカルサーバー起動（draft 含む）

hugo server -D

draft 記事とは

+++
title = '下書き'
draft = true
+++

-D を付けないと表示されない。

6. 記事の作成

hugo new posts/2026-01-08.md

Front Matter（例）

+++
title = 'Hugo メモ'
date = '2026-01-08'
draft = true
showtoc = true
+++

ファイル名と並び順の関係

Hugo の記事一覧の並び順は、ファイル名ではなく frontmatter の date によって決まる。
そのため、ファイル名は「人間が管理しやすい形」にしてよい。

おすすめは：

  • YYYY-MM-DD-title.md

7. PaperMod の params について

設定の優先順位

  1. Front Matter（記事ごと）
  2. hugo.toml の [params]
  3. テーマ内部のデフォルト

👉 params に書かなくても false になるわけではない。
👉 PaperMod 側のデフォルト値が使われる。

8. TOC（目次）の制御

グローバル設定（hugo.toml）

[params]
showtoc = true
tocopen = false

記事ごとの設定（Front Matter）

showtoc = true

9. 見出し横の「#（アンカーリンク）」について

現象

URL:

http://localhost:1313/posts/2026-01-08/#heading-1

見出しの横に # が表示される。

正体

  • 見出しへの アンカーリンク
  • PaperMod が自動で付与
  • class 名: .anchor

アンカーリンクを消す（CSS）

カスタム CSSファイル配置（重要）

assets/css/extended/custom.css

※ static ではなく assets

NG: display:none だけでは消えない

PaperModに限定するために、.post-contentを追加。

.post-content .anchor {
  display: none;
}
  • 読み込まれている
  • でも hover / JS 制御で復活する

OK: opacity + visibility

.post-content .anchor {
    opacity: 0; 
    visibility: hidden;
}
  • DOM には存在
  • 見えない・クリック不可
  • !important 不要

dev / prod 両方で読み込まれる？

✅ Yes

  • assets/ 配下の CSS
hugo server
hugo

で有効。

よくある勘違いメモ

  • CSS が効かない = 読み込まれてない ❌

  • → PaperMod 側の制御が強いだけ

  • Front Matter は params 名をそのまま使う ❌

  • → Hugo が用意した短縮キーがある

10. この HowTo の位置づけ

  • 公式ドキュメントより 実用寄り
  • 「なぜそうなるか」を残す
  • 半年後の自分を助けるための md

11. おわりに

PaperMod は優秀だけど、

「ちゃんと理由が分かってないと気持ち悪い」

というポイントが多い。

分かった瞬間を md に封じ込めるのが一番コスパがいい。

以上。