Next.jsのブログに構造化データ(JSON-LD)を実装する【純粋関数に集約して、XSS対策つきで埋め込む】
- この記事で分かること
- JSON-LDの生成を src/lib/jsonld.ts の純粋関数に集め、各ページはデータを渡して<script>に埋め込むだけにする構成と、埋め込み時のエスケープ処理
- 実際に使った環境
- Next.js 16.3.1(App Router)/ TypeScript。記事ページ・カテゴリーページ・トップ・運営者ページで実際に出力している実装です
- 筆者の結論
- 構造化データそのものは決まった形のオブジェクトを作るだけ。ページごとに散らばらせず関数に集約したこと、そしてscriptに埋め込むときの文字のエスケープを忘れないことの2点が、実装上のポイントだった
検索エンジンは、ページの文章を読んで内容を推測しています。それに加えて、ページが何であるか(記事なのか、パンくずなのか、質問と回答なのか)を、構造化データという決まった形式で明示的に伝えることができます。その書き方の一つが、JSON-LDです。
このブログでは、記事ページ、カテゴリーページ、トップ、運営者ページに構造化データを出力しています。この記事では、その実装の構成を紹介します。
🛠 実装してみて分かったこと
構造化データの中身は、仕様で決まった形のオブジェクトを作るだけです。悩んだのは、どこに書くかでした。最初は各ページのコンポーネントに直接オブジェクトを書くことも考えられますが、似た形のものがページごとに散らばると、後で直すときに探し回ることになります。そこで、生成ロジックはすべて1つのファイルに集め、各ページは「データを渡して、結果を埋め込む」だけにしました。
出力しているデータの種類
| 種類 | 出力しているページ | 材料 |
|---|---|---|
BlogPosting | 記事ページ | 記事のfrontmatter(タイトル・説明・日付など) |
BreadcrumbList | 記事ページ・カテゴリーページ・運営者ページ | パンくずの名前とURLの配列 |
FAQPage | frontmatterにfaqがある記事、ガイド本文にfaqがあるカテゴリーページ | 質問と回答の配列 |
CollectionPage | ガイド本文のあるカテゴリーページ | 配下の記事のURL一覧 |
Person | 運営者ページ | サイト設定の著者名・X(旧Twitter)のURL |
WebSite | トップページ | サイト名・URL・説明 |
生成ロジックを、純粋関数に集約する
生成ロジックは、src/lib/jsonld.tsに集めています。ここに置く関数は、副作用のない純粋関数だけです。データを受け取って、JSON-LDのオブジェクトを返すだけで、ファイルを読んだりDOMを触ったりはしません。
export function breadcrumbJsonLd(items: BreadcrumbItem[]) {
return {
"@context": "https://schema.org",
"@type": "BreadcrumbList",
itemListElement: items.map((item, i) => ({
"@type": "ListItem",
position: i + 1,
name: item.name,
item: item.url,
})),
};
}パンくずのpositionは、配列の並び順から1始まりで自動採番しています。呼び出し側が番号を管理する必要はありません。
純粋関数にしておくと、同じ入力には必ず同じ出力が返るので、動作の確認や、将来のテストが簡単になります。<script>タグへの埋め込みは、呼び出し側(各ページ)の責務として切り離してあります。
記事ページのBlogPosting
export function blogPostingJsonLd(post: Post) {
const url = `${siteConfig.url}/blog/${post.slug}`;
return {
"@context": "https://schema.org",
"@type": "BlogPosting",
headline: post.title,
description: post.description,
image: `${siteConfig.url}/blog/${post.slug}/opengraph-image`,
datePublished: post.date,
dateModified: post.updated ?? post.date,
author: {
"@type": "Person",
name: siteConfig.author,
url: `${siteConfig.url}/about`,
},
// ...publisher、mainEntityOfPage
};
}いくつか、意図のある部分があります。
dateModifiedは、updatedがなければdateと同じ値にする: frontmatterのupdatedは省略可能で、省略時は公開日と同じ扱いにしています。構造化データも同じ規則に合わせています- URLはすべて絶対URLにする:
siteConfig.urlを先頭に付けて、https://から始まる完全なURLにしています。構造化データは、ページの外から読まれることがあるため、相対パスだと解釈できません - 画像は、記事ごとのOGP画像のURL: 自動生成しているOGP画像のルートをそのまま使っています
FAQPageは、frontmatterのfaqから作る
export function faqPageJsonLd(faqs: FaqItem[]) {
return {
"@context": "https://schema.org",
"@type": "FAQPage",
mainEntity: faqs.map((faq) => ({
"@type": "Question",
name: faq.question,
acceptedAnswer: {
"@type": "Answer",
text: faq.answer,
},
})),
};
}記事のfrontmatterに書いたfaqを、そのままQuestionとAnswerの形に並べ替えています。この関数を呼ぶのは、faqが空でないことを確認した後だけです。
FAQPageは、本文にある「よくある質問」と同じ内容を、frontmatterに転記して作る運用にしています。構造化データだけに存在する質問を作ることはしません。画面に見えている内容と、検索エンジンに伝える内容がずれないようにするためです。
ページへの埋め込みと、エスケープ
各ページは、関数の結果を<script type="application/ld+json">に埋め込みます。
<script
type="application/ld+json"
dangerouslySetInnerHTML={{ __html: jsonLdScript(blogPostingJsonLd(post)) }}
/>{post.faq && post.faq.length > 0 && (
<script
type="application/ld+json"
dangerouslySetInnerHTML={{ __html: jsonLdScript(faqPageJsonLd(post.faq)) }}
/>
)}faqがある記事にだけFAQPageを出力しているのは、この条件分岐です。
「<」「>」「&」をエスケープする
ここで使っているjsonLdScriptが、もう一つのポイントです。
export function jsonLdScript(data: unknown): string {
return JSON.stringify(data)
.replace(/</g, "\\u003c")
.replace(/>/g, "\\u003e")
.replace(/&/g, "\\u0026");
}dangerouslySetInnerHTMLは、渡した文字列をそのままHTMLとして出力します。ここに、記事のタイトルや説明文などの文字列が入ったJSONを渡すと、問題が起きうる場合があります。値の中に</script>という文字列があると、ブラウザがそこで<script>タグを閉じてしまい、続きの内容がHTMLとして解釈されてしまいます。
そこで、<・>・&の3文字を、JSONの文字列エスケープである<・>・&に置き換えています。JSONとして読むと元の文字に戻るので、データの意味は変わりません。一方で、HTMLとしては<や>が存在しなくなるので、タグとして解釈される余地がなくなります。
このブログでは、記事のタイトルや説明は自分で書いているため、現実に</script>が混ざる可能性は低いです。それでも、「外から来る文字列を、出力先に合わせて処理する」というのは、癖として毎回やっておきたい処理です。1か所の関数に閉じ込めてあるので、使う側が意識しなくても、必ず通ります。
よくある質問
Q. 構造化データを入れると、検索順位は上がりますか? A. 構造化データ自体が順位を直接上げるわけではありません。ページの内容を検索エンジンに機械的に伝えるためのもので、パンくずリストの表示などのリッチリザルトの対象になりやすくなる、という位置づけです。このブログでも、順位を上げる目的ではなく、内容を正確に伝える目的で入れています。
Q. FAQPageの構造化データは、どの記事にも付けているのですか?
A. いいえ。記事のfrontmatterにfaqを書いた記事にだけ出力しています。本文の「よくある質問」と同じ内容を転記する運用で、本文に無い質問を構造化データにだけ書くことはしていません。
Q. JSON-LDを埋め込むとき、なぜエスケープが必要なのですか?
A. scriptタグの中に</script>という文字列が紛れ込むと、HTMLとして解釈されたときにタグがそこで閉じられてしまいます。記事のタイトルや説明文など、外から来る文字列がJSONに入る以上、<・>・&をUnicodeエスケープしておくことで、JSONとしての意味を変えずに、HTMLとして解釈される余地を潰しています。
まとめ
構造化データの実装は、決まった形のオブジェクトを作る作業です。このブログでは、生成ロジックをsrc/lib/jsonld.tsの純粋関数に集約し、各ページはそれを呼んで<script>に埋め込むだけにしました。埋め込み時の文字のエスケープも、1つの関数に閉じ込めています。
OGP画像やメタデータの設定はメタデータAPIの解説記事で扱っています。構造化データは、それとは別に「ページの中身が何であるか」を伝える役割です。