Next.jsブログのカテゴリーページを、ガイド本文つきのピラーページにする【Markdownで本文を置き、無ければ従来表示にフォールバック】
- この記事で分かること
- content/categories/{slug}.md にガイド本文を置き、記事と同じ変換パイプラインでHTML化してカテゴリーページに出す構成。本文が無いカテゴリーは従来の一覧表示に戻り、リンク漏れはビルド時に警告する
- 実際に使った環境
- Next.js 16.3.1(App Router、SSG + ISR)/ TypeScript / gray-matter。カテゴリーページ(/category/[slug])として、このブログで実際に動いている実装です
- 筆者の結論
- 一覧だけのカテゴリーページは、読む理由が薄い。ガイド本文を足す仕組み自体は記事の仕組みの使い回しで済んだ。むしろ運用で困るのは、記事が増えたときのリンク追加漏れだった
カテゴリーページは、そのカテゴリーの記事カードを新しい順に並べるのが、ブログの最も素朴な作りです。このブログも、最初はそうでした。しかし、一覧だけのページは、読者がそこにたどり着いたとき、「このカテゴリーで何が分かるのか」を伝えられません。
そこで、カテゴリーページの冒頭にガイド本文を置き、記事への案内役にするようにしました。この記事では、その実装を紹介します。
🛠 実装してみて分かったこと
ガイド本文の表示そのものは、記事の変換処理を使い回すだけで済みました。むしろ、仕組みを作ってから気づいたのは、運用の面でした。ガイド本文は記事へのリンクで成り立っているので、新しい記事が公開されたのにリンクを足し忘れると、そのページから案内されない記事ができてしまいます。その漏れを、人間の注意ではなくビルド時のチェックで拾うようにしました。
全体の構成
| 役割 | ファイル |
|---|---|
| ガイド本文(Markdown) | content/categories/{slug}.md |
| 本文の読み込み・HTML化 | src/lib/categories.ts |
| Markdown→HTMLの変換 | src/lib/markdown.ts(記事と共通) |
| カテゴリーページ | src/app/category/[slug]/page.tsx |
ガイド本文は、記事と同じように、frontmatterとMarkdown本文でできています。
---
title: "個人開発サイトの公開先の選び方"
description: "このブログが実際に選んだ公開先と、他の選択肢の検討状況を整理するガイドです。"
heading: "個人開発サイトの公開先の選び方"
updated: "2026-09-08"
faq:
- question: "..."
answer: "..."
---
(ここからガイド本文。記事と同じMarkdownで書く)frontmatterの型は、次のとおりです。
export type CategoryFrontmatter = {
title: string; // <title>・meta descriptionのタイトル部分に使う
description: string; // meta descriptionに使う
heading?: string; // H1に使う見出し。省略時はカテゴリー名
updated?: string; // 最終更新日。sitemapのlastModified算出に使う
faq?: FaqItem[]; // 構造化データ(FAQPage)用
};本文の読み込み: 記事と同じ変換を通す
export async function getCategoryContent(slug: CategorySlug): Promise<CategoryContent | null> {
const file = readCategoryFile(slug);
if (!file) return null;
const { contentHtml, headings } = await renderMarkdown(file.content);
return { ...file.data, slug, contentHtml, headings };
}ファイルが無ければnullを返します。あれば、記事本文と同じrenderMarkdownでHTMLにします。以前は記事の読み込み処理の内部にあった変換処理を、記事とカテゴリーの両方から呼べるよう独立した関数に切り出しました。
そのおかげで、記事で使える機能が、そのままカテゴリーページでも使えます。コードブロックのハイライトとコピーボタン、見出しへのid付与、目次データの生成などです。ページ側でも、記事ページと同じTableOfContents・TocSticky・CodeCopyButtonsを使い回しています。
本文があるかどうかで、表示を切り替える
カテゴリーページは、本文の有無で見え方を変えています。
const content = await getCategoryContent(slug as CategorySlug);
const heading = content?.heading ?? category.name;
// ...
<h1 className="text-2xl font-extrabold">{heading}</h1>
{/* ガイド本文が無いカテゴリーは、従来通りここに一行説明だけを出す */}
{!content && <p className="opacity-70 mt-2">{category.description}</p>}{content && (
<>
<TableOfContents headings={content.headings} />
<div
className="prose mb-12"
dangerouslySetInnerHTML={{ __html: content.contentHtml }}
/>
<CodeCopyButtons />
<h2 className="text-lg font-bold mb-5">この分野の記事一覧</h2>
</>
)}| 状態 | 表示 |
|---|---|
| 本文あり | パンくず → H1 → 本文(目次付き) → 「この分野の記事一覧」見出し → 記事カード |
| 本文なし | パンくず → H1 → 説明1行 → 記事カード |
全カテゴリーに本文を用意してから切り替える必要はありません。書けたカテゴリーから順に、本文のファイルを置くだけで、そのカテゴリーがピラーページになります。
構造化データも、本文の有無で変える
本文があるカテゴリーでだけ、構造化データにCollectionPageを出力します。配下の記事のURLを一覧にして、そのカテゴリーが記事群のハブであることを伝えます。ガイド本文のfrontmatterにfaqがあれば、FAQPageも加わります。構造化データの実装は、JSON-LDの実装記事で解説しています。
リンク漏れを、ビルド時に警告する
ガイド本文は、記事へのリンクで成り立っています。そのため、新しい記事が公開されたときに、本文へのリンクを足し忘れると、案内されない記事が生まれます。特にこのブログは予約投稿を使っているので、公開日を迎えた記事のリンクを足し忘れやすい状況です。
そこで、ビルドのたびにチェックする関数を用意しました。
function extractLinkedSlugs(content: string): Set<string> {
const slugs = new Set<string>();
const linkRe = /\]\(\/blog\/([a-z0-9-]+)\)/g;
let match;
while ((match = linkRe.exec(content))) {
slugs.add(match[1]);
}
return slugs;
}
export function checkCategoryLinkCoverage(): void {
for (const category of categories) {
const file = readCategoryFile(category.slug);
if (!file) continue;
const linkedSlugs = extractLinkedSlugs(file.content);
const publishedSlugs = getPostSummariesByCategory(category.slug).map((p) => p.slug);
const unlinked = publishedSlugs.filter((slug) => !linkedSlugs.has(slug));
if (unlinked.length > 0) {
console.warn(
`[categories] content/categories/${category.slug}.md からリンクされていない公開済み記事があります: ${unlinked.join(", ")}`
);
}
}
}extractLinkedSlugsは、Markdownの[文字](/blog/slug)という形のリンクから、slugだけを正規表現で集めます。HTMLに変換する前の文字列に対する検査なので、処理は軽いです。
checkCategoryLinkCoverageは、カテゴリーごとに、公開済みの記事のslugとリンク済みのslugを突き合わせ、足りないものがあれば警告します。
- 本文が無いカテゴリーは対象外: そもそもリンクを書く場所がありません
- 予約投稿中の記事は対象外: 公開判定は記事の一覧を取る関数に任せているので、公開日を迎えるまでは警告されません
- 自動でリンクは足さない: どの見出しの下に、どんな説明でリンクするかは、書き手が決めるべきことです。警告で知らせるだけにとどめています
この関数は、generateStaticParamsの中で呼んでいます。
export function generateStaticParams() {
// ビルドごとに1回だけ実行される場所なので、カテゴリー数だけ重複警告が
// 出ないよう、このチェックはここ(generateMetadata/ページ本体ではなく)に置く。
checkCategoryLinkCoverage();
return categories.map((c) => ({ slug: c.slug }));
}generateMetadataやページ本体は、1回のビルドでカテゴリーごとに呼ばれたり、複数回呼ばれたりします。そこに置くと、同じ警告が何度も出てしまいます。ビルドごとに1回だけ実行されるgenerateStaticParamsに置くことで、警告を1回にしています。
検索結果に出さないカテゴリー
カテゴリーによっては、ナビゲーションからは外したいが、URL自体は残しておきたい場合があります。そのカテゴリーは、ページは200で返しつつ、メタデータでrobots: { index: false, follow: true }を指定しています。検索結果には出ませんが、配下の記事へのリンクはたどってよい、という指定です。
よくある質問
Q. ピラーページとは何ですか? A. あるテーマの全体像をまとめ、関連する個別の記事へリンクで案内するページのことです。このブログでは、カテゴリーページの冒頭にガイド本文を置き、各見出しから配下の記事に案内する形でこれを作っています。
Q. ガイド本文を書いていないカテゴリーは、どう表示されますか? A. 本文のファイルが無いカテゴリーは、従来どおり「見出し+説明1行+記事カード」の表示に戻ります。全カテゴリーに一度に本文を書かなくても、書けたカテゴリーから順に切り替えられます。
Q. ガイド本文からのリンク漏れは、どうやって防いでいますか? A. ビルドのたびに、各カテゴリーの公開済み記事のうち、ガイド本文からリンクされていないものを調べ、あればコンソールに警告を出します。自動でリンクを足すことはせず、どこにどう書き足すかは書き手が決めます。
まとめ
カテゴリーページに必要だったのは、新しい仕組みではなく、記事の仕組みの使い回しでした。ガイド本文をcontent/categories/にMarkdownで置き、記事と同じ変換処理を通すことで、目次・コードのハイライト・構造化データが、そのまま使えました。本文が無いカテゴリーは従来の表示に戻るので、段階的に移行できます。
運用面では、記事が増えたときのリンク漏れが課題でした。人間が毎回確認するのは続かないので、ビルド時に警告する仕組みにしています。