ブログ記事をテーマ別に整理したドキュメントページを作った話

ブログを書き続けていると、記事が増えてきたときに「あの記事どこだっけ？」となるのが悩みでした。 とくにSvelteKitやCloudflare関連の記事は、シリーズとして順番に読んでほしいものが多く、ブログの新着順一覧では体系がわかりにくい状態になっていました。

そこで、既存のブログはそのままに、テーマ別に整理したドキュメントページを追加しました。

どんなページを作ったか

/docs/ 以下に、技術テーマ別のシリーズページを作りました。

各シリーズページには記事へのリンクが並んでいて、そこから直接ブログ記事に飛べます。

Hugoでの実装方法

1. content/docs/ 以下にコンテンツを作る

Hugoはディレクトリ構造がそのままセクションになります。 content/docs/_index.md がトップの目次ページ、content/docs/sveltekit-basics/_index.md が各シリーズページです。

各 _index.md にリンクをMarkdownで書くだけなので、管理がシンプルです。

content/
  docs/
    _index.md              ← /docs/ （シリーズ一覧）
    sveltekit-basics/
      _index.md            ← /docs/sveltekit-basics/
    svelte5/
      _index.md            ← /docs/svelte5/
    ...

2. docs用のレイアウトテンプレートを作る

通常のブログ一覧ページにはページネーションがありますが、ドキュメントページには不要です。 layouts/docs/list.html を作成して、Markdownの内容をそのまま表示するシンプルなレイアウトにしました。

{{ define "main" }}
<main class="main" role="main">
  <article class="post">
    <header class="post__header">
      <h1 class="post__title">{{ .Title }}</h1>
    </header>
    <div class="content post__content clearfix docs__content">
      {{ .Content }}
    </div>
    ...
  </article>
</main>
{{ end }}

3. ナビメニューに追加する

hugo.toml にメニュー項目を追加するだけです。

[[menus.main]]
  name = "ドキュメント"
  url = "/docs/"
  weight = 35
  [menus.main.params]
    subtitle = "DOCS"

よかった点

• 既存記事のURLが変わらない — ブログ記事はそのまま、ドキュメントは目次として上に乗せただけです
• 管理が一か所 — 同じリポジトリ・同じHugoで完結するので、別サービスを使う必要がありません
• コストゼロ — Cloudflare Pagesの静的ファイルとして配信されるので追加費用もなし

記事数が増えてきたタイミングで、こういった整理を一度やっておくと読んでもらいやすくなると感じました。