feat: Standardize the config format of TanStack project docs

[fulopkovacs]

The idea was proposed here by Tanner: #131 (comment)

TL;DR

Currently the docs of the TanStack projects use different config.json formats, causing a bit of a mess. The format of TanStack Form can fit all the other projects if we add a users key to it (for TanStack Query).

The new config format

See the zod schema here: https://github.com/fulopkovacs/tanstack.com/blob/3426fc7df794e5de381903a1ee7bfb81baf0148b/app/utils/config.ts#L33

✨ JSON Schema ✨

I wrote a fancy JSON Schema that our editors can use to validate docs/config.json files, and in the future we could use this to validate the schemas in the CI of the projects.

Here's a demo of installing the schema in VSCode, and using it for validation:

02-json-schema-correct.mp4

This is the code snippet I copy-paste into settings.json in the video:

  "json.schemas": [
    {
      "fileMatch": [
        "docs/config.json"
      ],
      "url": "https://raw.githubusercontent.com/fulopkovacs/tanstack.com/tanstack-docs-config/tanstack-docs-config.schema.json"
    }
  ]

Comparing the current doc configs of the TanStack projects

Note

I didn't want to spam the projects with PR-s, so I linked the new config files from my forks. When you test this PR you can copy the each new config file from there to docs/tanstack-docs-config.json. Edit: I opened up PR-s where they were necessary.

project	top-level keys of the old format	changes
TanStack Query	docSearch, menu(only framework-specific pages, no core docs),users	v3, v4, v5
TanStack Table (v8)	docSearch, menu (mixes core and framework-specific docs)	✅ no changes
TanStack Virtual	docSearch, menu (mixes core and framework-specific docs)	✅ no changes
TanStack Ranger	docSearch, menu (mixes core and framework-specific docs)	✅ no changes
TanStack Router	docSearch, menu (currently only React docs)	✅ no changes
TanStack Form	docSearch, menu (core docs), frameworkMenus (framework-specific)	✅ no changes
TanStack Store	docSearch, menu (core docs), frameworkMenus (framework-specific)	✅ no changes
React Charts	doesn't use a config.json file, docs are not in the Remix app	-

[vercel]

@fulopkovacs is attempting to deploy a commit to the Tanstack Team on Vercel.

A member of the Team first needs to authorize it.

[crutchcorn]

Don't wanna "Approve" the PR since there's still a few TODOs and this a draft PR, but WOW I love the work you've done here. This looks good to me - I vote we move forward with it!

[crutchcorn]

Also, please do open PRs to all of the related projects. I'll coordinate with the other maintainers to make sure that this is going through on each project in time.

[lachlancollins]

@fulopkovacs what can I do to help get this merged? (Sorry about all the conflicts)

[fulopkovacs]

@lachlancollins haha, there are now quite a few conflicts, but I think it'll be fine. I'll look at them later today, and ask for help/clarification if needed. Thanks for offering your help! ☺️

Originally I was planning to open PR-s for migrating to the new config format in all the TanStack repos today, and after that, this PR would've been ready for review. Resolving the conflicts and testing the PR locally again will cause some delay, but I'll try really hard to get everything done this weekend and pass it to review!

(Sorry for being slow with this one: it involved a lot of tedious work/testing, and I was asked to solve/voluntarily started debugging some other issues in this project and form while I was working on it. 😅 )

[lachlancollins]

@fulopkovacs looking great! Please feel free to submit the PRs to the other projects, I'll merge them all simultaneously when everything is ready to go

[fulopkovacs]

@fulopkovacs looking great! Please feel free to submit the PRs to the other projects, I'll merge them all simultaneously when everything is ready to go

@lachlancollins Awesome! I'm ready with my work (unless you request more changes).

Turns out, that if we don't rename the config.json files as I originally wanted to, then only the tanstack/query config-s need to be updated (for all 3 versions). Here are the PR-s:

• docs: Use the new config format (v3) query#6741
• docs: Use the new config format (v4) query#6742
• chore: Use the new docs config format query#6740

[lachlancollins]

Thanks so much for your work on this @fulopkovacs !