Skip to content

docs: add guide for edit docs and preview in local #5005

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 24, 2025
Merged

docs: add guide for edit docs and preview in local #5005

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 55 additions & 3 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,58 @@
- `pnpm dev`
- Make changes to the code
- If you ran `pnpm dev` the dev watcher will automatically rebuild the code that has changed
- Changes to the docs
- Be sure that internal links are written always relative to `docs` folder.
E.g. `./guide/data-loading`
- Editing the docs locally and previewing the changes
- The documentations for all the TanStack projects are hosted on [tanstack.com](https://tanstack.com), which is a TanStack Start application (https://github.com/TanStack/tanstack.com). You need to run this app locally to preview your changes in the `TanStack/router` docs.

> [!NOTE]
> The website fetches the doc pages from GitHub in production, and searches for them at `../router/docs` in development. Your local clone of `TanStack/router` needs to be in the same directory as the local clone of `TanStack/tanstack.com`.

You can follow these steps to set up the docs for local development:

1. Make a new directory called `tanstack`.

```sh
mkdir tanstack
```

2. Enter that directory and clone the [`TanStack/router`](https://github.com/TanStack/router) and [`TanStack/tanstack.com`](https://github.com/TanStack/tanstack.com) repos.

```sh
cd tanstack
git clone git@github.com:TanStack/router.git
# We probably don't need all the branches and commit history
# from the `tanstack.com` repo, so let's just create a shallow
# clone of the latest version of the `main` branch.
# Read more about shallow clones here:
# https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/#user-content-shallow-clones
git clone git@github.com:TanStack/tanstack.com.git --depth=1 --single-branch --branch=main
```

> [!NOTE]
> Your `tanstack` directory should look like this:
>
> ```
> tanstack/
> |
> +-- router/ (<-- this directory cannot be called anything else!)
> |
> +-- tanstack.com/
> ```

3. Enter the `tanstack/tanstack.com` directory, install the dependencies and run the app in dev mode:

```sh
cd tanstack.com
pnpm i
# The app will run on https://localhost:3000 by default
pnpm dev
```

4. Now you can visit http://localhost:3000/router/latest/docs/framework/react/overview in the browser and see the changes you make in `tanstack/router/docs` there.

> [!WARNING]
> You will need to update the `docs/(router or start)config.json` file (in `TanStack/router`) if you add a new documentation page!

Comment on lines +75 to +77
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Verification agent

🧩 Analysis chain

Disambiguate the config file path for new pages.

“docs/(router or start)config.json” is unclear within this repo. Please name the exact file(s) to edit, e.g., docs/router.config.json. Use the script below to verify actual config files present.

-> You will need to update the `docs/(router or start)config.json` file (in `TanStack/router`) if you add a new documentation page!
+> If you add a new documentation page, update the appropriate docs config file (e.g., `docs/router.config.json`) in `TanStack/router`.

🏁 Script executed:

#!/bin/bash
# Locate likely docs config files to mention precisely in CONTRIBUTING.md
fd -t f '.config.json' docs -0 | xargs -0 -I {} echo "Found: {}"
rg -nP --glob 'docs/**' '(config\.json|\.config\.json)' -S

Length of output: 3713

🏁 Script executed:

#!/bin/bash
# Locate all docs directories
find . -type d -iname docs

# List JSON files directly under any docs directory
find . -type f -path "*/docs/*.json"

# Find any files ending with "config.json" anywhere in the repo
find . -type f -iname '*config.json'

Length of output: 8612

Clarify docs config file path in CONTRIBUTING.md

The placeholder docs/(router or start)config.json is ambiguous. Replace it with the exact paths to the two existing config files in the docs directory:

  • docs/router/config.json
  • docs/start/config.json

Update CONTRIBUTING.md at lines 75–77 accordingly:

> [!WARNING]
- You will need to update the `docs/(router or start)config.json` file (in `TanStack/router`) if you add a new documentation page!
+ If you add a new documentation page, update the appropriate config file in the `docs` directory:
+ - `docs/router/config.json` (for Router docs)
+ - `docs/start/config.json`  (for Start docs)
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
> [!WARNING]
> You will need to update the `docs/(router or start)config.json` file (in `TanStack/router`) if you add a new documentation page!
> [!WARNING]
> If you add a new documentation page, update the appropriate config file in the `docs` directory:
> - `docs/router/config.json` (for Router docs)
> - `docs/start/config.json` (for Start docs)
🧰 Tools
🪛 LanguageTool

[grammar] ~75-~75: There might be a mistake here.
Context: ...nstack/router/docsthere. > [!WARNING] > You will need to update thedocs/(rou...

(QB_NEW_EN)

🤖 Prompt for AI Agents 
In CONTRIBUTING.md around lines 75 to 77, the docs config path text is
ambiguous; replace the placeholder `docs/(router or start)config.json` with the
two exact config file paths `docs/router/config.json` and
`docs/start/config.json` so contributors know the precise files to update; edit
the line to list both paths separated clearly (e.g., bullet or comma) and ensure
formatting matches surrounding Markdown.

You can see the whole process in the screen capture below:

https://github.com/fulopkovacs/form/assets/43729152/9d35a3c3-8153-4e74-9cb2-af275f7a269b