Docsbook
概要

ドキュメントのためのJSON-LD

JSON-LDは、検索エンジンやAIエージェントにページ上のコンテンツの種類を伝えるHTMLに埋め込まれた構造化データです。特にドキュメントの場合、適切なスキーマタイプはGoogleでのリッチ結果を解放し、AIによる引用の可能性を高め、さまざまな場所での発見性を向上させます。

この記事では、重要なスキーマタイプをリストし、動作する例を提供します。

要点#

スキーマ 使用される場所 重要な理由
TechArticle ハウツーおよびチュートリアルページ Googleに「これは技術的なコンテンツです」と伝える
FAQPage Q&Aを含む任意のページ 検索結果のリッチスニペット、AI引用
HowTo ステップバイステップガイド Googleでのステップバイステップリッチ結果
SoftwareApplication 製品概要ページ 価格、評価、OSが表示される
Article ブログ投稿および発表 標準記事のリッチ結果
BreadcrumbList すべてのドキュメントページ 検索結果のパンくずリスト
WebSite サイトルート SiteSearchActionがGoogle検索ボックスを有効にする

1つだけ行う場合は、TechArticleとBreadcrumbListを行ってください。Docsbookはこれらを自動的に追加します。

なぜMicrodataやRDFaではなくJSON-LDなのか#

JSON-LDが勝る理由：

  1. HTMLマークアップから切り離された別の <script> ブロックである
  2. Googleが明示的に好む（彼らのドキュメントで「推奨」とされている）
  3. メンテナンスが容易 — レイアウトに触れずにスキーマを変更できる
  4. AIエージェントがインラインマークアップよりも信頼性高く解析する

MicrodataとRDFaはまだ機能しますが、2026年にはレガシーとなります。

TechArticle: ドキュメントのデフォルト#

ほとんどのドキュメントページでは、 TechArticle が適切なスキーマです：

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "How to authenticate with OAuth",
  "description": "Step-by-step guide to authenticating users with OAuth 2.0",
  "author": {
    "@type": "Organization",
    "name": "Acme",
    "url": "https://acme.com"
  },
  "datePublished": "2026-01-15",
  "dateModified": "2026-03-20",
  "publisher": {
    "@type": "Organization",
    "name": "Acme",
    "logo": {
      "@type": "ImageObject",
      "url": "https://acme.com/logo.png"
    }
  },
  "mainEntityOfPage": "https://docs.acme.com/auth/oauth"
}
</script>

これにより得られるもの：

  • Googleはページを権威ある技術コンテンツとしてフラグ付けします
  • AIエージェントは TechArticle タグ付きページを引用でより高く評価する傾向があります
  • dateModified はクローラーにページが新しいことを伝えます

FAQPage: rich snippets gold#

ページにQ&A構造がある場合、 FAQPage スキーマにより、Googleは検索結果に直接Q&Aを表示します。

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [{
    "@type": "Question",
    "name": "How do I revoke an API key?",
    "acceptedAnswer": {
      "@type": "Answer",
      "text": "Open the dashboard, navigate to API Keys, find the key, click Revoke. Revocation is immediate."
    }
  }, {
    "@type": "Question",
    "name": "Can I have multiple API keys?",
    "acceptedAnswer": {
      "@type": "Answer",
      "text": "Yes. Up to 50 keys per project on the Pro plan, unlimited on Enterprise."
    }
  }]
}
</script>

Googleでの結果: あなたのFAQ項目は、メインの結果の下に展開可能な行として表示されます。FAQリッチスニペットを持つページのクリック率は20〜40％増加します。

また、AIエージェントは、事前に構造化されているため、FAQタグ付きコンテンツを不均衡に引用します。

方法: ステップバイステップガイド#

番号付きのステップバイステップガイドがある場合は、HowToを使用してください:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "HowTo",
  "name": "Set up a custom domain for documentation",
  "step": [{
    "@type": "HowToStep",
    "text": "Open the dashboard and go to Settings → Domain"
  }, {
    "@type": "HowToStep",
    "text": "Enter your subdomain (docs.yourcompany.com)"
  }, {
    "@type": "HowToStep",
    "text": "Add a CNAME record in DNS pointing to cname.vercel-dns.com"
  }, {
    "@type": "HowToStep",
    "text": "Wait for SSL to provision (under 5 minutes)"
  }]
}
</script>

結果: Googleは各ステップが展開されたステップバイステップのリッチ結果を表示する場合があります。

SoftwareApplication: 製品ページ#

あなたの製品概要ページは SoftwareApplication としてタグ付けされるべきです:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "SoftwareApplication",
  "name": "Acme",
  "applicationCategory": "DeveloperApplication",
  "operatingSystem": "Web",
  "offers": {
    "@type": "Offer",
    "price": "150",
    "priceCurrency": "USD"
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.8",
    "ratingCount": "247"
  }
}
</script>

これにより、Googleのリッチリザルトに価格と評価が表示されます。評価については正直であるべきです — Googleは誇張された aggregateRating に対してペナルティを課します。

BreadcrumbList: すべてのページ#

すべてのページにはJSON-LD形式のパンくずリストが必要です。Googleは検索結果に表示し、AIエージェントはそれを使用して階層を理解します：

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [{
    "@type": "ListItem",
    "position": 1,
    "name": "Docs",
    "item": "https://docs.acme.com"
  }, {
    "@type": "ListItem",
    "position": 2,
    "name": "Authentication",
    "item": "https://docs.acme.com/auth"
  }, {
    "@type": "ListItem",
    "position": 3,
    "name": "OAuth",
    "item": "https://docs.acme.com/auth/oauth"
  }]
}
</script>

ホームページでサイト検索を宣言します:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "url": "https://docs.acme.com",
  "potentialAction": {
    "@type": "SearchAction",
    "target": "https://docs.acme.com/search?q={search_term_string}",
    "query-input": "required name=search_term_string"
  }
}
</script>

これにより、Googleの結果のすぐ下に検索ボックスが表示されます。

1ページに複数のスキーマ#

スキーマを重ねることができます。ドキュメントページには次のものが含まれる場合があります：

  • TechArticle コンテンツタイプ用
  • BreadcrumbList ナビゲーション用
  • FAQPage Q&Aセクションがある場合

すべて3つの別々の <script type="application/ld+json"> ブロックにあります。Googleはそれらすべてを読み取ります。

AIエージェントがJSON-LDで行うこと#

観察された3つの行動：

  1. タイプフィルタリング — チュートリアルを探しているエージェントは TechArticle と HowTo を Article よりも好む
  2. 抽出ショートカット — FAQPage スキーマはほぼそのまま抽出される
  3. 信頼信号 — 適切な Organization と publisher を持つスキーマはより高く評価される

DocsbookがJSON-LDを提供する方法#

Docsbookは自動的に以下を追加します：

  • TechArticle すべてのドキュメントページに
  • BreadcrumbList すべてのページに
  • FAQPage Q&Aパターンを検出したページに
  • SoftwareApplication メタデータが提供されている場合、ホームページに
  • WebSite SearchActionをサイトのルートに

設定は不要です。スキーマは既存のマークダウンとフロントマターから構築されます。

検証#

2つのツール：

  • Googleリッチリザルトテスト — https://search.google.com/test/rich-results
  • Schema.orgバリデーター — https://validator.schema.org/

両方をドキュメントページで実行してください。警告を修正してください。エラーはブロックされますが、警告はブロックされません。

DocsbookはすべてのページにJSON-LDを自動的に追加します。 ドキュメントを公開する →

Updated

提供： Docsbook