fix(docs): broken internal links in the query docs

[fulopkovacs]

I found 100+ broken links starting with /query/v5/docs with broken-link-checker. This PR fixes them.

Most of these come from moving the core pages away from the framework-related pages.

TODO

Fix the links for:

• React
• Angular
• Vue
• Solid
• Svelte

How I tested the links

1. Started the docs site locally on http://localhost:3000 (https://github.com/TanStack/tanstack.com)
2. Ran the following commands for each framework in the local clone of this repo (this example is for angular):

# Check the site for broken links: print the results in the terminal and save them to this file: `broken-links-angular.txt`
broken-link-checker http://localhost:3000/query/v5/docs/framework/angular/overview  -roe --filter-level 0 --requests 20 | tee broken-links-angular.txt
# Find all the relevant broken links in the `broken-links-angular.txt` file
grep -E '.*BROKEN.*http://localhost:3000/query/v5' broken-links-angular.txt

These commands can be chained if you don't need the output in the terminal. For Angular, this is how the output should look like when all the links are fixed (the injectQuery.md page is supposed to be missing, since it'll be added in the future):

Testing the broken links with a script

#!/usr/bin/env bash
# Check all the broken links for the React Query docs (v5)
# NOTE: You must install the `broken-link-checker` package from npm
# NOTE: You must run the `tanstack/tanstack.com` site locally on port 3000
# NOTE: This script will run for a loooong time :'(, but in the end it should
# print all the links that are broken in the `v5` docs

# 1. React
broken-link-checker http://localhost:3000/query/v5/docs/framework/react/overview  -roe --filter-level 0 --requests 20 | grep -E '.*BROKEN.*http://localhost:3000/query/v5'

# 2. Vue
broken-link-checker http://localhost:3000/query/v5/docs/framework/vue/overview  -roe --filter-level 0 --requests 20 | grep -E '.*BROKEN.*http://localhost:3000/query/v5'

# 3. Angular
broken-link-checker http://localhost:3000/query/v5/docs/framework/angular/overview  -roe --filter-level 0 --requests 20 | grep -E '.*BROKEN.*http://localhost:3000/query/v5'

# 4. Solid
broken-link-checker http://localhost:3000/query/v5/docs/framework/solid/overview  -roe --filter-level 0 --requests 20 | grep -E '.*BROKEN.*http://localhost:3000/query/v5'

# 5. Svelte
broken-link-checker http://localhost:3000/query/v5/docs/framework/svelte/overview  -roe --filter-level 0 --requests 20 | grep -E '.*BROKEN.*http://localhost:3000/query/v5'

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

1 Ignored Deployment

Name	Status	Preview	Comments	Updated (UTC)
query	⬜️ Ignored (Inspect)	Visit Preview		Apr 22, 2024 8:37am

[nx-cloud]

☁️ Nx Cloud Report

CI is running/has finished running commands for commit baf7313. As they complete they will appear below. Click to see the status, the terminal output, and the build insights.

📂 See all runs for this CI Pipeline Execution

---

✅ Successfully ran 1 target

• nx affected --targets=test:format,test:sherif,test:knip,test:eslint,test:lib,test:types,test:build,build,test:attw --parallel=3

---

Sent with 💌 from NxCloud.

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit baf7313:

Sandbox	Source
@tanstack/query-example-angular-basic	Configuration
@tanstack/query-example-react-basic-typescript	Configuration
@tanstack/query-example-solid-basic-typescript	Configuration
@tanstack/query-example-svelte-basic	Configuration
@tanstack/query-example-vue-basic	Configuration

[codecov-commenter]

Codecov Report

Merging #7247 (85ccfa4) into main (93674fe) will decrease coverage by 0.41%.
Report is 71 commits behind head on main.
The diff coverage is n/a.

❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7247      +/-   ##
==========================================
- Coverage   41.42%   41.02%   -0.41%     
==========================================
  Files         184      183       -1     
  Lines        7331     7362      +31     
  Branches     1531     1541      +10     
==========================================
- Hits         3037     3020      -17     
- Misses       3889     3933      +44     
- Partials      405      409       +4     

Components	Coverage Δ
@tanstack/angular-query-devtools-experimental	∅ <ø> (∅)
@tanstack/angular-query-experimental	86.46% <0.00%> (ø)
@tanstack/eslint-plugin-query	85.29% <100.00%> (ø)
@tanstack/query-async-storage-persister	43.85% <100.00%> (-5.35%)	⬇️
@tanstack/query-broadcast-client-experimental	∅ <ø> (∅)
@tanstack/query-codemods	0.00% <0.00%> (ø)
@tanstack/query-core	92.86% <79.59%> (-0.40%)	⬇️
@tanstack/query-devtools	3.92% <0.00%> (-0.02%)	⬇️
@tanstack/query-persist-client-core	57.73% <ø> (ø)
@tanstack/query-sync-storage-persister	82.50% <ø> (ø)
@tanstack/react-query	92.77% <100.00%> (ø)
@tanstack/react-query-devtools	10.71% <ø> (ø)
@tanstack/react-query-next-experimental	∅ <ø> (∅)
@tanstack/react-query-persist-client	100.00% <ø> (ø)
@tanstack/solid-query	81.31% <56.25%> (-0.96%)	⬇️
@tanstack/solid-query-devtools	∅ <ø> (∅)
@tanstack/solid-query-persist-client	100.00% <ø> (ø)
@tanstack/svelte-query	62.68% <100.00%> (ø)
@tanstack/svelte-query-devtools	∅ <ø> (∅)
@tanstack/svelte-query-persist-client	100.00% <100.00%> (ø)
@tanstack/vue-query	71.04% <90.47%> (+0.23%)	⬆️
@tanstack/vue-query-devtools	∅ <ø> (∅)

[SeanCassiere]

@fulopkovacs Found some other ones in #7248, do you mind including them in yours?

[fulopkovacs]

@fulopkovacs Found some other ones in #7248, do you mind including them in yours?

Oh yeah, sure, thanks for your work! This PR contains like <10% of all the broken links, so I still have a lot more links to fix! 😢

[fulopkovacs]

@TkDodo I couldn't figure out where should the ../injectQuery link go to here:

query/docs/framework/angular/guides/caching.md

Line 26 in b11c876

- Note that regardless of whether both `fetchTodos` query functions are identical or not, both queries' [`status`](../injectQuery) are updated (including `isFetching`, `isPending`, and other related values) because they have the same query key.

So that one is still broken.

[TkDodo]

@fulopkovacs in the react docs, this links to the useQuery reference:

https://tanstack.com/query/v5/docs/framework/react/reference/useQuery

in angular, useQuery is injectQuery. However, there don't seem to be dedicated API docs for angular (yet?)

I think we can either remove the link or point it towards the same location as useQuery, but named injectQuery so that it will work once the site is created.

@arnoud-dv FYI

[arnoud-dv]

or point it towards the same location as useQuery, but named injectQuery so that it will work once the site is created.

That would be my preference, I certainly plan to add the API reference.

[fulopkovacs]

or point it towards the same location as useQuery, but named injectQuery so that it will work once the site is created.

That would be my preference, I certainly plan to add the API reference.

Awesome, thanks for the responses. I updated the link to point at https://tanstack.com/query/v5/docs/framework/angular/reference/injectQuery.

https://github.com/fulopkovacs/query/blob/b8547375b8844c6b607386f7723a4db536f915ef/docs/framework/angular/guides/caching.md?plain=1#L26

[fulopkovacs]

Edit: And it's all done.

😅 Ugh, I checked back on this PR, and it looks like I only checked the links for react, so I'll fix the links for the rest of the frameworks too.

After that, I'll update the description of this PR with the terminal commands I used (spoiler: broken-link-checker and grep), and that'll enable others to review this work properly.

[fulopkovacs]

@TkDodo I think I'm ready with this PR, could you check it please? (The script I used to check the broken links is in the description, under the accordion.)

Feel free to tell me if something is missing.

[TkDodo]

looking at the file structure, we are in:

docs/framework/react/guides/important-defaults.md

and we want to link towards

docs/framework/react/community/tkdodos-blog.md

so imo the correct link should be one level up:

../community/tkdodos-blog

this is also what my editor would auto-complete. So why are two levels up (../../ ) needed ?

[fulopkovacs]

I'm not sure why the two ..-s are needed. I just assumed that it's related to the conversation in the in the #router-maintainers channel in Discord about trailing slashes, and VSCode improperly flagging links with errors, because it did not work the VSCode-way. 🤣 (Still doesn't, I checked.)

I'll ask around in Discord, and come back with the answer.

[fulopkovacs]

Here's my question on Discord with my most recent theory on why this solution works... 😅

[fulopkovacs]

Okay, I presented this theory to Tanner, and he said it's correct:

1. the file is docs/framework/react/guides/important-defaults.md
2. we want to link to docs/framework/react/community/tkdodos-blog.md
3. the relative link that works is ../../community/tkdods.md

My theory on why we need two ..-s here:

• somewhere along the way the original markdown gets interpreted as the docs/framework/react/guides/important-defaults/ route
• . parent is important-defaults
• .. grandparent is guides
• ../.. great-grandparent is react

Hence ./../../community takes us to the community route in the current path's great-grandparent route.

[TkDodo]

I can't keep up with all the PRs sending fixes for a single broken link so I'll just merge this 😅