Skip to content

Correct NextJS link URL #5488

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 2 commits into from
Oct 15, 2025
Merged

Correct NextJS link URL #5488

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
373cbee
correct nextjs link url
aaronjordan Oct 15, 2025
da30416
add link for quick-start
aaronjordan Oct 15, 2025
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
2 changes: 1 addition & 1 deletion docs/start/framework/react/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ title: Getting Started

- [Start a new project from scratch](#start-a-new-project-from-scratch) to quickly learn how Start works (see below)
- Refer to a migration guide for your specific framework:
- [Next.js](../guide/migrate-from-next-js)
- [Next.js](../migrate-from-next-js)
Copy link
Contributor

@coderabbitai coderabbitai bot Oct 15, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟠 Major

Broken relative path to Next.js migration guide

Using ../migrate-from-next-js climbs out of the react/ directory, landing on a non-existent framework/migrate-from-next-js page. Switch to the local ./migrate-from-next-js path so the link resolves to framework/react/migrate-from-next-js.

-  - [Next.js](../migrate-from-next-js)
+  - [Next.js](./migrate-from-next-js)
📝 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
- [Next.js](../migrate-from-next-js)
- [Next.js](./migrate-from-next-js)
🧰 Tools
🪛 LanguageTool

[grammar] ~10-~10: There might be a mistake here.
Context: ...or your specific framework: - Next.js - Remix 2 / React Router 7 "Framework Mode...

(QB_NEW_EN)

🤖 Prompt for AI Agents 
In docs/start/framework/react/getting-started.md around line 10, the link to the
Next.js migration guide uses a broken relative path "../migrate-from-next-js"
which climbs out of the react/ directory; change it to the local relative path
"./migrate-from-next-js" so the link resolves to
framework/react/migrate-from-next-js (update the Markdown link target
accordingly).

Copy link
Contributor Author

@aaronjordan aaronjordan Oct 15, 2025

Choose a reason for hiding this comment

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

This and the other link change follow the precedent in the file of links that work properly. I'm not close enough to the project to know why they're all beginning with ../.

Would be interested to learn if there's an easy explanation 🙂

Copy link
Contributor

@coderabbitai coderabbitai bot Oct 15, 2025

Choose a reason for hiding this comment

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

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Explore the directory structure around the getting-started.md file
echo "=== Directory structure of docs/start/framework ==="
fd . docs/start/framework --type d --max-depth 3 | sort

echo -e "\n=== Finding the migrate-from-next-js file ==="
fd migrate-from-next-js docs/start/framework

echo -e "\n=== List all markdown files in docs/start/framework/react ==="
fd . docs/start/framework/react --type f -e md | sort

echo -e "\n=== Check if there's a guide directory ==="
if [ -d "docs/start/framework/guide" ]; then
    echo "guide directory exists"
    fd . docs/start/framework/guide --type f -e md | sort
else
    echo "No guide directory found"
fi

echo -e "\n=== List all markdown files directly under docs/start/framework ==="
fd . docs/start/framework --type f -e md --max-depth 1 | sort

Length of output: 2032

🏁 Script executed:

#!/bin/bash
# Find documentation framework configuration files
echo "=== Looking for documentation framework config files ==="
fd -e json -e js -e ts config docs/ --max-depth 3 2>/dev/null || echo "No config in docs/"

echo -e "\n=== Checking root for common doc framework configs ==="
ls -la | grep -E "(docusaurus|vitepress|nextra|vocs|astro)" || echo "No obvious framework config in root"

echo -e "\n=== Looking for package.json to identify framework ==="
if [ -f "package.json" ]; then
    echo "Found package.json, checking for doc frameworks..."
    cat package.json | jq -r '.dependencies, .devDependencies | to_entries[] | select(.key | contains("docs") or contains("docusaurus") or contains("vitepress") or contains("nextra") or contains("vocs") or contains("astro")) | "\(.key): \(.value)"' 2>/dev/null || echo "Using jq failed, trying grep..."
    grep -E "\"(docusaurus|vitepress|nextra|vocs|astro|@tanstack)" package.json | head -20
fi

echo -e "\n=== Looking for vocs config specifically ==="
fd vocs.config -e ts -e js --max-depth 2

echo -e "\n=== Checking the docs directory structure ==="
ls -la docs/ 2>/dev/null | head -20

Length of output: 1634

🏁 Script executed:

#!/bin/bash
# Check the docs config files
echo "=== Content of docs/start/config.json ==="
cat docs/start/config.json

echo -e "\n=== Content of docs/router/config.json ==="
cat docs/router/config.json

echo -e "\n=== Checking for TanStack config ==="
fd tanstack.config -e ts -e js --max-depth 2

echo -e "\n=== Look at the URL structure in production ==="
echo "Production URL from PR: https://tanstack.com/start/latest/docs/framework/react/getting-started"
echo "File location: docs/start/framework/react/getting-started.md"
echo ""
echo "This suggests the URL pattern:"
echo "- /start/ -> maps to docs/start/"
echo "- /latest/docs/ -> seems to be injected by the framework"
echo "- /framework/react/getting-started -> matches the file path after docs/start/"

Length of output: 29100

@aaronjordan Great question! 🙂

The ../ pattern works here because TanStack uses a custom documentation framework that handles link resolution differently from standard filesystem relative paths. Looking at the docs/start/config.json file, I can see how the routing structure is defined.

Here's what's happening:

From the file system perspective:

  • Your file: docs/start/framework/react/getting-started.md
  • Links like ../quick-start would normally resolve to docs/start/framework/quick-start.md (which doesn't exist!)

But from the documentation framework's perspective:

  • The framework uses the routing configuration in config.json where routes are defined as:
    • "to": "framework/react/getting-started"
    • "to": "framework/react/quick-start"
    • "to": "framework/react/migrate-from-next-js"

How the framework resolves ../ links:

The documentation build system treats ../ as a special prefix that gets intelligently resolved against the routing structure. When you're on a page at framework/react/getting-started and use:

  • ../quick-start → resolves to framework/react/quick-start
  • ../guide/routing → resolves to framework/react/guide/routing
  • ../migrate-from-next-js → resolves to framework/react/migrate-from-next-js

This is why your change from ../guide/migrate-from-next-js to ../migrate-from-next-js is correct—it matches the actual route structure defined in the config, where the migration guide is at framework/react/migrate-from-next-js, not framework/react/guide/migrate-from-next-js.

The ../ prefix is essentially a convention used by the TanStack docs framework to indicate "resolve this relative to the current page's context" rather than performing literal directory traversal.

- Remix 2 / React Router 7 "Framework Mode" (coming soon!)

## Start a new project from scratch
Expand Down