router

router copied to clipboard

The current link to https://tanstack.com/router/v1/docs/api/core results in a 404 so I created a core.md file in docs/api. I had a few other questions as well about overall documentation contributions.

How do I doc?

I was wondering if it's possible to build and run the docs site locally? I didn't see anyway to do so by looking at the scripts in the package.json.

I wanted to fix the weird anchor link behavior for the Solid/Svelte/Vue coming soon links which result in things like:

https://tanstack.com/router/v1/docs/vue-coming-soon
https://tanstack.com/router/v1/docs/#solid-coming-soon
https://tanstack.com/router/v1/docs/vue-coming-soon#svelte-coming-soon

My intuition is that the solution would something along the lines of uncommenting these:

// scripts/config.ts

export const examplesDirs = [
  'examples/react',
  'examples/solid',
  'examples/svelte',
  'examples/vue',
]

Fixing the to routes defined under the Solid, Svelte, and Vue tutorials in config.json.

{
  "menu": [
    {
      "label": "Solid Examples",
      "children": [
        {
          "label": "Coming Soon!",
          "to": "examples/solid/basic"
        }
      ]
    },
    {
      "label": "Svelte Examples",
      "children": [
        {
          "label": "Coming Soon!",
          "to": "examples/svelte/basic"
        }
      ]
    },
    {
      "label": "Vue Examples",
      "children": [
        {
          "label": "Coming Soon!",
          "to": "examples/vue/basic"
        }
      ]
    }
  ]
}

And then create the following directories and markdown files with Todo messages in each:

mkdir -p examples/solid/basic
mkdir -p examples/svelte/basic
mkdir -p examples/vue/basic
echo '# Solid Basic Example\n\nComing soon!' > examples/solid/basic/README.md
echo '# Svelte Basic Example\n\nComing soon!' > examples/svelte/basic/README.md
echo '# Vue Basic Example\n\nComing soon!' > examples/vue/basic/README.md

Problem is, I have no idea how these markdown files are being built and packaged and I have no way of knowing whether this would break in some ways until I can test it somehow.

Possible Additions to the Quick Start

Final thought I had was, I always personally find it useful when Quick Start guides include all or at least most of the steps you'd need to get from 0 to 1. In that spirit, I'd add something like this before the primary code block:

npm create vite@latest tanstack-router-react -- --template react-ts
cd tanstack-router-react
npm i @tanstack/react-router@beta

And then this after the code block:

npm run dev

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

A member of the Team first needs to authorize it.

I'm also curious about getting the site to run locally. There is also the project for the site itself: https://github.com/TanStack/tanstack.com , which seems to pull in the docs for the various projects on the site from their repos. (Guessing at least.) The site requires some kind of credentials to run locally though, so I'm not sure if it's intended to be run by anyone who wants to?

The site requires a bunch of keys for accessing github, airtable and discord🫣

Interesting, I'm assuming that setup helps you automate a lot of things? I'd be curious what kind of functionality you are afforded specifically and whether it would be possible to either:

• Shift to a more traditional docs site built with a static site generator and markdown but without introducing a huge migration burden or loosing functionality.
• Create a mock environment with keys contributors can be given to develop the site independently from the production site.

Since it's your workflow I have no idea how easy or hard either of those options will be and the exact trade offs they'll introduce so only you'll really know what the right call is. My 2 cents is I'm a big fan of doc sites that keep things as basic as possible so new contributors can make changes without a lot of friction or onboarding.

It’s a dynamic site as opposed to a static or framework driven docs site so it can support serving up and integrating content across repos easily. None of the docs are stored in the repo, but all of docs get the same upgrades and logical sharing of the parent site. As you mentioned, there’s also integration for discord, GitHub sponsors, etc.

I think the right path forward here is to just get it working locally without the requirement of env variables. That might mean limited functionality around developing around those authenticated pieces, but that won’t be a problem for anyone since I’m the only person handling that private data anyway 😉

I’ll whip something up.

Alright, I just pushed a few changes that should allow the normal features of the site to work without credentials locally. Mainly, the Airtable and Github APIs have been mocked to empty data where necessary. This means the sponsors will not be pulled and thus the sponsor bubble pack is empty.

Carry on!

Final thought I had was, I always personally find it useful when Quick Start guides include all or at least most of the steps you'd need to get from 0 to 1. In that spirit, I'd add something like this before the primary code block:

I would be fine with this. A great addition.

As for testing, you would need to clone both the tanstack.com and the router repos down to your filesystem and ensure that the local linking is working between them. It should "just work", and show you the local markdown files you're editing in the remix dev environment of the site.

As far as fixing the coming soon links, thats exactly what would need to happen, except for the scripts/config.ts bit. That file can remain as is until the examples become "real".

Awesome, appreciate you taking the time to make those changes! I'll test out that flow and report back if anything weird happens and then I'll add the rest of the discussed changes to this PR.