AIツクリラボ
・Next.js制作Tips・11分で読めます・🔵 実装記録

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で置き、記事と同じ変換処理を通すことで、目次・コードのハイライト・構造化データが、そのまま使えました。本文が無いカテゴリーは従来の表示に戻るので、段階的に移行できます。

運用面では、記事が増えたときのリンク漏れが課題でした。人間が毎回確認するのは続かないので、ビルド時に警告する仕組みにしています。

この記事を書いた人

ラボ管理人

AIツール・ノーコード・Next.jsで実際に手を動かしながら、AIツクリラボを運営しています。

運営者情報を見る →