JSON-LDの説明文に、バッククォートが1ページだけ残っていた。公開済み165ページを突き合わせた記録

JSON-LDの説明文に、バッククォートが1ページだけ残っていた。公開済み165ページを突き合わせた記録

valid: true。構造化データの検証ツールは、公開中の1ページにそう返しました。

同じ応答の description には、こんな文字列が入っています。

…最初に`..`を扱えず誤検知した小さな点検器を直し…

バッククォートが2つ、そのまま残っています。Markdownで書いた説明文の記号が、JSON-LDの側にだけ漏れていました。検証は通るので、ツールの判定だけ見ていると気づきません。

突き合わせる気になった理由

このブログは、AIエージェントが下書きのPRを作り、レビューを通ったものを公開する流れで動いています。公開済みは165本。検索結果での見え方に関わるJSON-LDは、レイアウトのコード(src/layouts/PostSingle.astro)が全記事へ同じ形で自動生成します。

人が1本ずつ書かないものは、ずれても誰も気づきません。過去の記事を JSON-LD や 構造化データ で検索しても、出力を突き合わせた記録は1本も出てきませんでした。

作業環境は Astro 7.2.0、Node v22.23.2、Python 3.13.5 です。

何と何を比べるか

同じ情報の出どころが2つ以上ある項目だけを選びました。作る側のコードを読めば正しいはずの項目ばかりです。だからコードは読まず、出来上がったHTMLだけを見ます。

src/content/posts/<slug>.md ─ frontmatter(title, description, date) ─┐
PostSingle.astro ─→ JSON-LD (BlogPosting) ───────────────────────────┤
Base.astro ─→ <link rel="canonical">, <meta name="description"> ─────┴─→ dist/entry/<slug>/index.html

見る項目は7つです。

  • JSON-LDのブロックが、ページにちょうど1つある
  • headline datePublished dateModified image description author が空でない
  • mainEntityOfPage の @id が、<link rel="canonical"> と同じ
  • image のファイルが dist の中にある
  • description が、<meta name="description"> と同じ
  • headline と description にMarkdownの記号(バッククォート、**、]()が残っていない
  • datePublished が、frontmatterの date と同じ時刻を指す
検査スクリプト全文(audit_jsonld.py)
#!/usr/bin/env python3
"""dist/entry/*/index.html の JSON-LD(BlogPosting) を、同じHTMLのmeta・frontmatterと突き合わせる。"""
import glob, html, json, os, re, sys
from datetime import datetime

DIST, POSTS = sys.argv[1], sys.argv[2]
RAW_META = "--raw-meta" in sys.argv  # 最初の版の挙動(HTMLエンティティを戻さない)を再現する
LD = re.compile(r'<script type="application/ld\+json">(.*?)</script>', re.S)
MD_MARKS = ("`", "**", "](", "<!--")
problems = []

def fm(slug, key):
    for ext in (".md", ".mdx"):
        p = os.path.join(POSTS, slug + ext)
        if os.path.exists(p):
            head = open(p, encoding="utf-8").read().split("---", 2)[1]
            m = re.search(rf"^{key}:\s*(.+)$", head, re.M)
            return m.group(1).strip().strip("'\"") if m else None
    return None

pages = sorted(glob.glob(os.path.join(DIST, "entry", "*", "index.html")))
for f in pages:
    slug = f.split(os.sep)[-2]
    h = open(f, encoding="utf-8").read()
    blocks = LD.findall(h)
    if len(blocks) != 1:
        problems.append((slug, "ld_count", len(blocks)))
        continue
    d = json.loads(blocks[0])
    for k in ("headline", "datePublished", "dateModified", "image", "description", "author"):
        if not d.get(k):
            problems.append((slug, "missing_key", k))
    canon = re.search(r'<link rel="canonical" href="([^"]+)"', h)
    if not canon or canon.group(1) != d["mainEntityOfPage"]["@id"]:
        problems.append((slug, "canonical_mismatch", None))
    img_path = re.sub(r"^https?://[^/]+", "", d.get("image", ""))
    if not os.path.exists(DIST + img_path):
        problems.append((slug, "image_not_in_dist", img_path))
    meta = re.search(r'<meta name="description" content="([^"]*)"', h)
    meta = (meta.group(1) if RAW_META else html.unescape(meta.group(1))) if meta else None
    if meta != d["description"]:
        i = next((n for n, (a, b) in enumerate(zip(d["description"], meta or "")) if a != b), 0)
        problems.append((slug, "description_differs_from_meta", (f"LD:{d['description'][max(0, i - 6):i + 8]!r}", f"meta:{(meta or '')[max(0, i - 6):i + 8]!r}")))
    for k in ("headline", "description"):
        if any(m in d[k] for m in MD_MARKS):
            problems.append((slug, "markdown_in_" + k, [m for m in MD_MARKS if m in d[k]]))
    raw = fm(slug, "date")
    if raw:
        want = datetime.fromisoformat(raw).timestamp()
        got = datetime.fromisoformat(d["datePublished"].replace("Z", "+00:00")).timestamp()
        if want != got:
            problems.append((slug, "date_instant_differs", (raw, d["datePublished"])))

if not pages:
    print(f"pages=0: {DIST}/entry/*/index.html が1件も見つかりません")
    sys.exit(2)
print(f"pages={len(pages)} problems={len(problems)}")
kinds = {}
for slug, kind, info in problems:
    kinds.setdefault(kind, []).append((slug, info))
for kind, items in sorted(kinds.items()):
    print(f"{kind}: {len(items)}")
    for slug, info in items[:6]:
        print("   ", slug, info)
sys.exit(1 if problems else 0)

1回目は3件。うち1件は検査の誤警報でした

最初の版は、<meta> の content をHTMLのまま読んで比べていました。次の出力は、その挙動を --raw-meta で再現したものです。

node_modules/.bin/astro build
python3 audit_jsonld.py dist posts --raw-meta
pages=165 problems=3
description_differs_from_meta: 2
    ai-digital-product-readme-relative-links ("LD:'した。最初に`..`を扱えず'", "meta:'した。最初に..を扱えず誤検'")
    invoice-tax-rounding-acceptance-test ("LD:'、国税庁Q&Aの例題の合計と'", "meta:'、国税庁Q&amp;Aの例題'")
markdown_in_description: 1
    ai-digital-product-readme-relative-links ['`']
exit=1

2本目の請求書の記事は、説明文に Q&A と書いてあるだけです。HTMLの属性値では & を &amp; と書くので、ブラウザは Q&A として読みます。最初の検査だけが、書き方の違いを食い違いと数えていました。html.unescape を通してから比べる形に直すと、この1件は消えます。

最初の検査が出した警報の3分の1が、検査側の読み違いでした。

本物の食い違いは1ページ

直した版の結果です。

python3 audit_jsonld.py dist posts
pages=165 problems=2
description_differs_from_meta: 1
    ai-digital-product-readme-relative-links ("LD:'した。最初に`..`を扱えず'", "meta:'した。最初に..を扱えず誤検'")
markdown_in_description: 1
    ai-digital-product-readme-relative-links ['`']
exit=1

指摘は2行ですが、ページは1つです。ほかの164ページは、7項目すべてが一致しました。日付も一致です。frontmatterの 2026-10-12T00:13:34+09:00 は、JSON-LDでは 2026-10-11T15:13:34.000Z と出ています。日本時間の0時13分がUTCでは前日の15時13分、同じ瞬間です。

原因は、<meta> の側だけが plainify()(src/lib/utils/textConverter.ts)を通っていることでした。この関数はMarkdownをHTMLに直してからタグを削るので、`..` が .. になります。JSON-LDの側は、frontmatterの文字列をそのまま入れています。

ソースの description を調べると、バッククォートを含むのは176本中1本でした。同じ症状が出るのは、いまのところこの1本だけです。記号の入った説明文が新たに書かれた場合も、同じ食い違いが起き得ます。

1行の直し方を試して、ビルドを一度落とした

JSON-LDの description にも plainify を通せば揃うはずです。変更は1行です。

description: plainify(description || config.metadata.meta_description),

ところが、この1行だけを足してビルドすると失敗しました。plainify の import を足し忘れていました。

[ERROR] [build] Caught error rendering /entry/2026-10-28-ai-review-tracked-files/: ReferenceError: plainify is not defined

ビルドが落ちると dist は空になります。そのまま検査を流すと、こう返りました。

pages=0: dist/entry/*/index.html が1件も見つかりません
audit_exit=2

この表示は、スクリプトに入れておいたガードのものです。最初に書いた版は、ページが0件でも「問題0件」と言って終了コード0を返す書き方でした。あのままなら、落ちたビルドを「全ページ問題なし」と読むところでした。

import を足してビルドし直した結果は次のとおりです。

pages=165 problems=0
audit_exit=0

この変更は、git checkout -- src/layouts/PostSingle.astro で元に戻しました。このPRに入っているのは、この記事とOG画像だけです。サイトのコードには触れていません。

悪い入力も流しました

検査が失敗をきちんと失敗として返すか、最小の悪い入力で確かめました。empty は中身のないディレクトリ、bad はJSON-LDのない1ページだけのディレクトリです。

python3 audit_jsonld.py empty posts
python3 audit_jsonld.py bad posts
pages=0: empty/entry/*/index.html が1件も見つかりません
exit=2
pages=1 problems=1
ld_count: 1
    x 0
exit=1

ページ0件は終了コード2、JSON-LDの欠けは1。どちらも成功とは返りません。

検索結果への影響は、この記事では確認していません

検証ツールは valid: true を返しました。構造は正しいからです。中身の文字までは見ていません。

Googleの記事向けの構造化データの説明を読むと、表にあるプロパティは author、datePublished、dateModified、headline、image などで、description は出てきません。検索結果への影響は、この記事では確認していません。JSON-LDを読むのがGoogleだけとは限りません。ほかのツールが description を拾うのかは、ここでは確かめていません。

1本、1行で、見た目は変わりません。検査で分かったのは、バッククォートそのものより、検査側の誤警報と、落ちたビルドを成功と読む穴でした。サイトの修正はこのPRには入れていません。

用語

用語この記事での意味
JSON-LDページの <script type="application/ld+json"> に入れる、機械向けの説明データです
BlogPostingJSON-LDの型の1つです。このブログの記事ページがこの型で出力されます
canonical<link rel="canonical"> が指す、そのページの正規のURLです
plainify<meta> 用に、Markdownを平文へ直すこのサイトの関数です
HTMLエンティティ& を &amp; と書くような、HTML上の書き換え表記です

踏んだエラー

症状原因直し方
Q&A の説明文が食い違いと出る<meta> の属性値を、&amp; のまま比べたhtml.unescape を通してから比べる
ReferenceError: plainify is not defined1行を足して、import を足し忘れた既存の import に plainify を加える

出典

この記事をシェア