Sync docs config schema with what the site reads

[tombeckenham]

tanstack-docs-config.schema.json is the schema every library repo references from its docs/config.json. It had drifted from the valibot schema in src/utils/config.ts and from the code that actually consumes the config. Three fixes, all to the JSON Schema only — no runtime behaviour changes.

Add tab

Missing since #904 introduced the tabbed docs nav. valibot accepts tab on sections, section children, and framework children (config.ts:26), and getDocsNavTabId reads child.tab ?? group.tab before falling back to inference — but because the JSON Schema sets additionalProperties: false, a maintainer who set tab got a validation error in their editor for using a supported feature.

Added in all three positions via a shared $defs/tab enum, sourced from docsNavTabIds in src/utils/docsNavTabs.ts. Not added to the framework group object: useMenuConfig flattens framework children into the parent section, so a tab there would never be read.

Deprecate docSearch instead of requiring it

Nothing reads it. There is no reference to docSearch anywhere in src, and valibot doesn't declare it — it survives parsing only because v.object strips unknown keys. Search is wired to constants in the component:

// SearchModal.tsx:217-221
const searchClient = liteClient('FQ0DQ6MA3C', '10c34d6a5c89f6048cf644d601e65172')
const searchIndexName = 'tanstack-test'

The values don't even match what the configs declare — same Algolia app, different search-only key, and the site queries tanstack-test while every library config claims tanstack. So the schema was requiring maintainers to keep a credential block current for a feature that stopped consuming it.

Note: this drops docSearch from required and marks it deprecated, rather than deleting the property. With top-level additionalProperties: false, deleting it outright would make every currently-valid config invalid in its editor until that repo removed the block. Deprecating shows a strikethrough and lets each repo delete at its own pace. Happy to do the hard removal instead once the library repos have dropped it — say the word.

Describe badge

badge was undocumented and doesn't do what it looks like it does. useMenuConfig overwrites it with the page's framework provenance before it reaches the sidebar:

// LibraryLayout.tsx:754-760
...section.children.map((d) => ({ ...d, badge: 'core' })),
...frameworkItems.map((d) => ({ ...d, badge: currentFramework.framework })),

and the sidebar no longer renders it at all — that pill was removed in 9bdc880. It is still read for real in llms.ts:317, which walks the raw config and appends it to the generated llms.txt entry. The new description says exactly that, so nobody expects a sidebar pill from it.

Verification

Validated with ajv against the schema:

ai config (docSearch present)      VALID    # no regression on existing configs
ai config (docSearch deleted)      VALID    # repos can now drop the block
tab on section/child/framework     VALID
bogus tab value rejected           yes

pnpm test passes (136 pass, 0 fail, lint clean).

Summary by CodeRabbit

• New Features
  • Added optional tab navigation for documentation sections and pages, including Home, Get Started, Tutorials, Guides, API, and Examples.
• Bug Fixes
  • Documentation configuration no longer requires the docSearch setting.
• Documentation
  • Clarified that docSearch is deprecated and ignored.
  • Documented how page badges affect generated llms.txt content.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e662c27f-472d-4b67-9c97-4394d0319caf

📥 Commits

Reviewing files that changed from the base of the PR and between c4687bf and 97be690.

📒 Files selected for processing (1)

• tanstack-docs-config.schema.json

---

📝 Walkthrough

Walkthrough

The documentation configuration schema now treats docSearch as deprecated and ignored, documents badge output in generated llms.txt files, and supports validated tab navigation values at section and page levels.

Changes

Documentation configuration schema

Layer / File(s)	Summary
Schema contract and documentation updates tanstack-docs-config.schema.json	docSearch is optional, deprecated, and documented as ignored. Page badge descriptions now document generated llms.txt entries for framework-agnostic and framework-specific pages.
Tab navigation properties tanstack-docs-config.schema.json	Sections and page variants accept optional tab values. The shared definition allows home, get-started, tutorial, guides, api, and examples.
Estimated code review effort: 2 (Simple)	~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: synchronizing the documentation configuration schema with the site's consumption requirements.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs-config-schema-sync

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	tanstack-com	97be690	Commit Preview URL Branch Preview URL	Jul 31 2026, 02:31 AM