feat(seo): add h1 + BreadcrumbList and enrich BlogPosting schema on blog posts / 博客文章增加 h1 与 BreadcrumbList 并丰富 BlogPosting 结构化数据 (#599)

* feat(seo): add h1 + BreadcrumbList and enrich BlogPosting schema on blog posts

Render the post title as a real <h1> (was <h2>) so each post carries a single
top-level heading with its primary keyword; MDX body content keeps mapping
markdown headings to <h2>, guaranteeing exactly one <h1> per page.

Extract the BlogPosting JSON-LD into a pure, unit-testable builder and enrich it
with the recommended Article fields: image (post OG image URL), inLanguage,
mainEntityOfPage, and publisher.logo (ImageObject). Add a separate
BreadcrumbList JSON-LD (Home -> Blog -> post) to posts, mirroring the compare
pages. All applied to both the English and /zh post pages, with translated
breadcrumb labels and zh-CN language/URLs on the Chinese side.

中文：将博客文章标题渲染为真正的 <h1>（原为 <h2>），使每篇文章拥有唯一的顶级标题并承载主关键词；
MDX 正文标题仍映射为 <h2>，从而保证每页只有一个 <h1>。将 BlogPosting 结构化数据抽取为纯函数、
可单元测试的构建器，并补齐推荐的 Article 字段：image（文章 OG 图片 URL）、inLanguage、
mainEntityOfPage 与 publisher.logo（ImageObject）。同时为文章新增独立的 BreadcrumbList
结构化数据（首页 -> 博客 -> 文章），与 compare 页面保持一致。以上改动同时应用于英文与 /zh 文章页，
中文侧使用翻译后的面包屑标签及 zh-CN 语言标记与 URL。

* fix(seo): drop conflicting publisher.logo dimensions in blog JSON-LD

Cursor Bugbot flagged the BlogPosting publisher.logo height (675) as
inconsistent with the codebase. The OG_IMAGE asset is genuinely 1200×675
(verified via sips), but the root layout declares it 1200×630 and its
Organization logo omits dimensions entirely. Rather than assert a number
that conflicts with the root layout, omit the optional width/height and
match the existing Organization-logo precedent in layout.tsx.

中文：修复博客 JSON-LD 中 publisher.logo 尺寸不一致的问题。Cursor Bugbot 指出
logo 声明的高度（675）与代码库其他处不一致：OG_IMAGE 实际为 1200×675（经 sips
验证），但根布局声明为 1200×630，且其 Organization logo 未声明尺寸。为避免与根布局
冲突，这里省略可选的 width/height，与 layout.tsx 中 Organization logo 的既有做法保持一致。

Author: Oseltamivir

packages/app/cypress/e2e/blog.cy.ts

@@ -31,8 +31,10 @@ describe('Blog', () => {
       cy.visit('/blog/inferencemax-open-source-inference-benchmarking');
     });
 
-    it('renders the post title', () => {
-      cy.get('h2').should('contain.text', 'InferenceMAX');
+    it('renders the post title as the one and only h1', () => {
+      // The title is the page's single <h1> (primary-keyword top heading);
+      // MDX body sections map to <h2>, so there must be exactly one h1.
+      cy.get('h1').should('have.length', 1).and('contain.text', 'InferenceMAX');
     });
 
     it('displays post metadata', () => {

packages/app/src/app/blog/[slug]/page.tsx

@@ -19,6 +19,8 @@ import {
   blogDescription,
   getAllPosts,
   getAdjacentPosts,
+  buildBlogBreadcrumbJsonLd,
+  buildBlogPostingJsonLd,
   extractHeadings,
   getPostBySlug,
   hasZhTranslation,
@@ -136,34 +138,21 @@ export default async function BlogPostPage({ params }: Props) {
     },
   });
 
-  const jsonLd = {
-    '@context': 'https://schema.org',
-    '@type': 'BlogPosting',
-    headline: meta.title,
-    author: { '@type': 'Person', name: AUTHOR_NAME },
-    publisher: { '@type': 'Organization', name: AUTHOR_NAME },
-    datePublished: `${meta.date}T00:00:00Z`,
-    ...(meta.modifiedDate && { dateModified: `${meta.modifiedDate}T00:00:00Z` }),
-    // Keep structured-data description in sync with the SERP/OG/Twitter meta
-    // (both go through blogDescription) so they never diverge for posts with a
-    // seoDescription or a long subtitle.
-    description: blogDescription(meta),
-    url: `${SITE_URL}/blog/${slug}`,
-    wordCount: raw.trim().split(/\s+/u).length,
-    timeRequired: `PT${meta.readingTime}M`,
-  };
+  const jsonLd = buildBlogPostingJsonLd(meta, raw);
+  const breadcrumbJsonLd = buildBlogBreadcrumbJsonLd(slug, meta.title);
 
   return (
     <main className="relative">
       <HashScroll />
       <ReadingProgressBar slug={slug} />
       <JsonLd data={jsonLd} />
+      <JsonLd data={breadcrumbJsonLd} />
       <div className="container mx-auto px-4 lg:px-8 flex flex-col gap-4">
         <section data-blog-section="true" className="flex flex-col gap-4">
           <Card>
             <BlogBackLink />
             <header>
-              <h2 className="text-2xl lg:text-4xl font-bold tracking-tight">{meta.title}</h2>
+              <h1 className="text-2xl lg:text-4xl font-bold tracking-tight">{meta.title}</h1>
               <p className="mt-3 text-base lg:text-lg text-muted-foreground">{meta.subtitle}</p>
               <div className="flex flex-wrap items-center gap-3 text-sm text-muted-foreground mt-3">
                 <span>{AUTHOR_NAME}</span>

packages/app/src/app/zh/blog/[slug]/page.tsx

@@ -20,10 +20,12 @@ import {
   blogDescription,
   getAllPosts,
   getAdjacentPosts,
+  buildBlogBreadcrumbJsonLdZh,
+  buildBlogPostingJsonLd,
   extractHeadings,
   getPostBySlug,
 } from '@/lib/blog';
-import { ZH_LANG_TAG, ZH_OG_LOCALE, zhAlternates } from '@/lib/i18n';
+import { ZH_OG_LOCALE, zhAlternates } from '@/lib/i18n';
 import {
   AUTHOR_HANDLE,
   AUTHOR_NAME,
@@ -132,35 +134,21 @@ export default async function ZhBlogPostPage({ params }: Props) {
     },
   });
 
-  const jsonLd = {
-    '@context': 'https://schema.org',
-    '@type': 'BlogPosting',
-    headline: meta.title,
-    author: { '@type': 'Person', name: AUTHOR_NAME },
-    publisher: { '@type': 'Organization', name: AUTHOR_NAME },
-    datePublished: `${meta.date}T00:00:00Z`,
-    ...(meta.modifiedDate && { dateModified: `${meta.modifiedDate}T00:00:00Z` }),
-    // Keep structured-data description in sync with the SERP/OG/Twitter meta
-    // (both go through blogDescription) so they never diverge for posts with a
-    // seoDescription or a long subtitle.
-    description: blogDescription(meta),
-    url: `${SITE_URL}/zh/blog/${slug}`,
-    inLanguage: ZH_LANG_TAG,
-    wordCount: raw.trim().split(/\s+/u).length,
-    timeRequired: `PT${meta.readingTime}M`,
-  };
+  const jsonLd = buildBlogPostingJsonLd(meta, raw, 'zh');
+  const breadcrumbJsonLd = buildBlogBreadcrumbJsonLdZh(slug, meta.title);
 
   return (
     <main className="relative">
       <HashScroll />
       <ReadingProgressBar slug={slug} />
       <JsonLd data={jsonLd} />
+      <JsonLd data={breadcrumbJsonLd} />
       <div className="container mx-auto px-4 lg:px-8 flex flex-col gap-4">
         <section data-blog-section="true" className="flex flex-col gap-4">
           <Card>
             <BlogBackLink href="/zh/blog" label="返回文章列表" />
             <header>
-              <h2 className="text-2xl lg:text-4xl font-bold tracking-tight">{meta.title}</h2>
+              <h1 className="text-2xl lg:text-4xl font-bold tracking-tight">{meta.title}</h1>
               <p className="mt-3 text-base lg:text-lg text-muted-foreground">{meta.subtitle}</p>
               <div className="flex flex-wrap items-center gap-3 text-sm text-muted-foreground mt-3">
                 <span>{AUTHOR_NAME}</span>

packages/app/src/lib/blog.test.ts

@@ -1,8 +1,15 @@
 import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
 import fs from 'node:fs';
 
+import { OG_IMAGE, SITE_URL } from '@semianalysisai/inferencex-constants';
+
 import {
+  type BlogPostMeta,
   blogDescription,
+  blogOgImageUrl,
+  buildBlogBreadcrumbJsonLd,
+  buildBlogBreadcrumbJsonLdZh,
+  buildBlogPostingJsonLd,
   extractHeadings,
   getAdjacentPosts,
   getAllPosts,
@@ -592,3 +599,168 @@ describe('extractHeadings', () => {
     expect(headings[1].id).toBe('intro-2');
   });
 });
+
+// ---------------------------------------------------------------------------
+// Structured data (JSON-LD) builders — pure, no fs access.
+// ---------------------------------------------------------------------------
+
+const SAMPLE_META: BlogPostMeta = {
+  title: 'GB200 vs MI355X Inference Benchmark',
+  subtitle: 'Head-to-head throughput and latency.',
+  date: '2026-03-01',
+  slug: 'gb200-vs-mi355x',
+  readingTime: 7,
+  tags: ['gpu', 'benchmark'],
+};
+
+const SAMPLE_META_MODIFIED: BlogPostMeta = {
+  ...SAMPLE_META,
+  modifiedDate: '2026-04-10',
+};
+
+describe('blogOgImageUrl', () => {
+  it('builds an absolute URL to the English post opengraph-image route', () => {
+    expect(blogOgImageUrl('gb200-vs-mi355x')).toBe(
+      `${SITE_URL}/blog/gb200-vs-mi355x/opengraph-image`,
+    );
+  });
+
+  it('builds an absolute URL to the /zh post opengraph-image route', () => {
+    expect(blogOgImageUrl('gb200-vs-mi355x', 'zh')).toBe(
+      `${SITE_URL}/zh/blog/gb200-vs-mi355x/opengraph-image`,
+    );
+  });
+});
+
+describe('buildBlogPostingJsonLd', () => {
+  it('emits a BlogPosting with the recommended Article fields (en)', () => {
+    const jsonLd = buildBlogPostingJsonLd(SAMPLE_META, 'one two three four five', 'en') as Record<
+      string,
+      any
+    >;
+
+    expect(jsonLd['@context']).toBe('https://schema.org');
+    expect(jsonLd['@type']).toBe('BlogPosting');
+    expect(jsonLd.headline).toBe(SAMPLE_META.title);
+
+    // image — absolute OG image URL for the post.
+    expect(jsonLd.image).toBe(`${SITE_URL}/blog/gb200-vs-mi355x/opengraph-image`);
+
+    // inLanguage — English tag on the English page.
+    expect(jsonLd.inLanguage).toBe('en-US');
+
+    // mainEntityOfPage — WebPage pointing at the canonical post URL.
+    expect(jsonLd.mainEntityOfPage).toEqual({
+      '@type': 'WebPage',
+      '@id': `${SITE_URL}/blog/gb200-vs-mi355x`,
+    });
+
+    // publisher.logo — ImageObject with an absolute URL. Dimensions are
+    // intentionally omitted (optional in schema.org) because the asset's real
+    // size conflicts with the root layout's OG declaration; see blog.ts.
+    expect(jsonLd.publisher['@type']).toBe('Organization');
+    expect(jsonLd.publisher.logo).toEqual({
+      '@type': 'ImageObject',
+      url: OG_IMAGE,
+    });
+    expect(jsonLd.publisher.logo.width).toBeUndefined();
+    expect(String(jsonLd.publisher.logo.url)).toMatch(/^https:\/\//u);
+
+    // Existing required fields are preserved.
+    expect(jsonLd.author).toEqual({ '@type': 'Person', name: 'SemiAnalysis' });
+    expect(jsonLd.datePublished).toBe('2026-03-01T00:00:00Z');
+    // Description routes through blogDescription (same helper as the meta/OG
+    // tags) so structured data and SERP snippet never diverge.
+    expect(jsonLd.description).toBe(blogDescription(SAMPLE_META));
+    expect(jsonLd.url).toBe(`${SITE_URL}/blog/gb200-vs-mi355x`);
+    expect(jsonLd.wordCount).toBe(5);
+    expect(jsonLd.timeRequired).toBe('PT7M');
+  });
+
+  it('omits dateModified when no modifiedDate, includes it when present', () => {
+    const withoutMod = buildBlogPostingJsonLd(SAMPLE_META, 'a b c') as Record<string, any>;
+    expect(withoutMod.dateModified).toBeUndefined();
+
+    const withMod = buildBlogPostingJsonLd(SAMPLE_META_MODIFIED, 'a b c') as Record<string, any>;
+    expect(withMod.dateModified).toBe('2026-04-10T00:00:00Z');
+  });
+
+  it('uses the zh language tag and /zh canonical URL for the Chinese page', () => {
+    const jsonLd = buildBlogPostingJsonLd(SAMPLE_META, 'a b c', 'zh') as Record<string, any>;
+    expect(jsonLd.inLanguage).toBe('zh-CN');
+    expect(jsonLd.url).toBe(`${SITE_URL}/zh/blog/gb200-vs-mi355x`);
+    expect(jsonLd.mainEntityOfPage['@id']).toBe(`${SITE_URL}/zh/blog/gb200-vs-mi355x`);
+    expect(jsonLd.image).toBe(`${SITE_URL}/zh/blog/gb200-vs-mi355x/opengraph-image`);
+  });
+});
+
+describe('buildBlogBreadcrumbJsonLd', () => {
+  it('builds a 3-item BreadcrumbList with correct positions and absolute URLs (en)', () => {
+    const crumb = buildBlogBreadcrumbJsonLd('gb200-vs-mi355x', SAMPLE_META.title) as Record<
+      string,
+      any
+    >;
+
+    expect(crumb['@context']).toBe('https://schema.org');
+    expect(crumb['@type']).toBe('BreadcrumbList');
+    expect(crumb.itemListElement).toHaveLength(3);
+
+    const [home, blog, post] = crumb.itemListElement;
+    expect(home).toEqual({ '@type': 'ListItem', position: 1, name: 'Home', item: SITE_URL });
+    expect(blog).toEqual({
+      '@type': 'ListItem',
+      position: 2,
+      name: 'Blog',
+      item: `${SITE_URL}/blog`,
+    });
+    expect(post).toEqual({
+      '@type': 'ListItem',
+      position: 3,
+      name: SAMPLE_META.title,
+      item: `${SITE_URL}/blog/gb200-vs-mi355x`,
+    });
+
+    for (const el of crumb.itemListElement) {
+      expect(el['@type']).toBe('ListItem');
+      expect(String(el.item)).toMatch(/^https:\/\//u);
+    }
+    expect(crumb.itemListElement.map((el: any) => el.position)).toEqual([1, 2, 3]);
+  });
+});
+
+describe('buildBlogBreadcrumbJsonLdZh', () => {
+  it('mirrors the English breadcrumb with translated labels and /zh URLs', () => {
+    const crumb = buildBlogBreadcrumbJsonLdZh('gb200-vs-mi355x', SAMPLE_META.title) as Record<
+      string,
+      any
+    >;
+
+    expect(crumb['@type']).toBe('BreadcrumbList');
+    expect(crumb.itemListElement).toHaveLength(3);
+
+    const [home, blog, post] = crumb.itemListElement;
+    expect(home).toEqual({
+      '@type': 'ListItem',
+      position: 1,
+      name: '首页',
+      item: `${SITE_URL}/zh`,
+    });
+    expect(blog).toEqual({
+      '@type': 'ListItem',
+      position: 2,
+      name: '博客',
+      item: `${SITE_URL}/zh/blog`,
+    });
+    expect(post).toEqual({
+      '@type': 'ListItem',
+      position: 3,
+      name: SAMPLE_META.title,
+      item: `${SITE_URL}/zh/blog/gb200-vs-mi355x`,
+    });
+
+    for (const el of crumb.itemListElement) {
+      expect(String(el.item)).toMatch(/^https:\/\/[^/]+\/zh/u);
+    }
+    expect(crumb.itemListElement.map((el: any) => el.position)).toEqual([1, 2, 3]);
+  });
+});