TanStack / TanStack/tanstack.com

feat(seo): add semantic breadcrumbs and BreadcrumbList structured data

Open
#1,151 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
TypeScript
Stars
1.1k
Forks
401
Avg merge
18h 14m
Merged PRs (30d)
56

Description

Context

TanStack has a deep, meaningful content hierarchy, especially across library landing pages, documentation, blog posts, chart examples, and partner pages. These pages currently do not emit BreadcrumbList JSON-LD.

The shared src/components/Breadcrumbs.tsx component is currently a section label plus an on-page table-of-contents control. It renders div elements rather than a complete semantic breadcrumb trail, so it cannot serve as the source of truth for either accessible navigation or structured data.

Google documentation: https://developers.google.com/search/docs/appearance/structured-data/breadcrumb

Proposed scope

  • Define a shared breadcrumb item model with a label and optional absolute or site-relative URL.
  • Render visible breadcrumbs as nav with aria-label="Breadcrumb".
  • Generate an SSR-visible BreadcrumbList JSON-LD object from the same breadcrumb items.
  • Use representative user paths rather than mechanically mirroring URL segments.
  • Cover at least:
    • Library landing pages: Libraries → Query
    • Docs: Libraries → Query → React Docs → Guides → Query Keys
    • Blog posts: Blog → Post title
    • Charts catalog examples: Charts → Catalog → Example title
    • Partner detail pages: Partners → Partner name
  • Do not emit breadcrumb markup on the homepage, errors, or non-indexable pages.

Acceptance criteria

  • Visible breadcrumbs and JSON-LD are derived from one shared data model.
  • BreadcrumbList is present in the raw SSR response, not added only after hydration.
  • Every BreadcrumbList contains at least two ListItem entries with contiguous positions.
  • Linked breadcrumb items use absolute canonical HTTPS URLs in JSON-LD.
  • The current page name matches the visible page heading/title.
  • Representative routes pass Google Rich Results Test validation.
  • Automated tests cover ordering, URL generation, escaping, and routes that should not emit breadcrumbs.

Notes

The current UI component can retain its on-this-page control, but that control should be separate from the hierarchical breadcrumb data.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with src/components/Breadcrumbs.tsx and the Google Breadcrumb structured-data guidance, then trace the representative library, docs, blog, charts, and partner routes named in the issue. Done means shared breadcrumb data drives accessible visible navigation and SSR-visible JSON-LD, with the listed validation and automated coverage for ordering, URLs, escaping, and excluded routes.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation, web-dev
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.