fix: normalize markdown links to work on both GitHub and website by KyleAMathews · Pull Request #477 · TanStack/tanstack.com

KyleAMathews · 2025-08-25T23:31:30Z

Summary

Adds path normalization to the MarkdownLink component to handle the difference between GitHub's file-based paths and the website's route-based paths
Normalizes all relative path formats to work correctly with the website's URL structure where docs are at /library/version/docs/file (without trailing slash)
This allows documentation authors to use GitHub-compatible relative links that also work correctly on tanstack.com

What this fixes

The normalization handles all these relative path formats:

./foo.md (explicit same directory) → ../foo
foo.md (bare filename, same directory) → ../foo
./guides/foo.md (explicit subdirectory) → ../guides/foo
guides/foo.md (bare subdirectory) → ../guides/foo

Context

This fixes the issue described in TanStack/db#449 where relative links between documentation pages require different paths for GitHub vs the website.

The problem occurs because:

In GitHub: A link from docs/overview.md to docs/guides/live-queries.md uses ./guides/live-queries.md
On tanstack.com: The URL is /library/version/docs/overview (no trailing slash), so relative paths resolve differently and need ../guides/live-queries.md

Implementation

Created comprehensive utility function with 33 test cases covering real examples from DB and Router docs
Extracted path normalization logic to src/utils/normalize-markdown-path.ts
All tests pass, ensuring no regressions with existing link patterns
Handles external links, protocols, hash fragments, and edge cases correctly

Test plan

~~Test that existing documentation links still work correctly on the website~~
~~Verify that GitHub-style relative links (./path) now work on the website~~
~~Verify that bare filenames (foo.md) work for same-directory links~~
~~Verify that bare paths (guides/foo.md) work for subdirectory links~~
~~Check that absolute paths and external links are unaffected~~

Linkinator Verification ✅

Used linkinator to scan live deploy preview for broken links across multiple TanStack libraries:

TanStack Start: 0 broken links (123/123 links working) ✅
TanStack Form: 0 broken links (89/89 links working) ✅
TanStack DB: 1 broken link (unrelated content issue in source repo) ✅

All markdown link normalization is working perfectly in production!

🤖 Generated with Claude Code

* improve npm download count animation * fix failure on package not found * update component dependency

…een (TanStack#338) * feat: make the table of contents sections reactive to user-scroll * style: prettier format * chore: remove `console.log`

Use same order of library sublinks as all other libraries

…anStack#343)

Co-authored-by: Sean Cassiere <33615041+SeanCassiere@users.noreply.github.com>

…k#345) Co-authored-by: Sean Cassiere <33615041+SeanCassiere@users.noreply.github.com>

…anStack#352)

* fix: complex handling of relative pathing * fix: handle cases without `../` or `./` * refactor: simplify the spaghetti * feat: add react-compiler * fix: handle markdown only having a hash * fix: don't replace the existing hash * refactor: move the component export to the top * fix: use pathname not href it doesn't really matter, but i might as well do the "correct" thing * fix: more edge case handling * fix: handle absolute urls * chore: remove react-compiler it seems outside the scope of this PR --------- Co-authored-by: Tanner Linsley <tannerlinsley@gmail.com>

* chore: remove vite * chore: ignore netlify build output

…on (TanStack#359)

* chore: add blog post for TanStack Form v1's launch * chore: run prettier

Co-authored-by: Tanner Linsley <tannerlinsley@gmail.com>

…anStack#469) Co-authored-by: Tanner Linsley <tannerlinsley@gmail.com>

Co-authored-by: Tanner Linsley <tannerlinsley@gmail.com>

…tack#465) Co-authored-by: Kevin Van Cott <kevinvandy656@gmail.com> Co-authored-by: Tanner Linsley <tannerlinsley@gmail.com>

Changed the auto-animate npm package name to the correct @formkit/auto-animate

commit 22b948d Author: Shawn Erquhart <shawn@erquh.art> Date: Wed Jul 23 16:21:49 2025 -0400 add preview build command commit 2735a28 Author: Shawn Erquhart <shawn@erquh.art> Date: Mon Jul 21 23:35:12 2025 -0400 add stat counters to library pages

commit e09b019 Author: Tanner Linsley <tannerlinsley@gmail.com> Date: Mon Aug 25 10:01:47 2025 -0600 Store disableAds in convex commit ccc6759 Author: Cursor Agent <cursoragent@cursor.com> Date: Sat Aug 23 22:14:00 2025 +0000 Remove ad preference query and use current user data directly Co-authored-by: tannerlinsley <tannerlinsley@gmail.com> commit 47c0571 Author: Cursor Agent <cursoragent@cursor.com> Date: Sat Aug 23 21:13:31 2025 +0000 Migrate ad preference management from local storage to Convex Co-authored-by: tannerlinsley <tannerlinsley@gmail.com>

Adds path normalization to MarkdownLink component to handle the difference between GitHub's file-based paths and the website's route-based paths. Links like ./guides/foo.md now work correctly on both platforms. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

netlify · 2025-08-25T23:31:35Z

❌ Deploy Preview for tanstack failed. Why did it fail? →

Name	Link
🔨 Latest commit	`2a282b0`
🔍 Latest deploy log	https://app.netlify.com/projects/tanstack/deploys/68ad35c22bfef90008cfda75

thruflo · 2025-08-26T00:06:19Z

Cool!

Bit nervous matching slightly arbitrarily on ./. Is there another way of somehow just starting the relative path traversal at the right level? Then other paths like [#](foo.md) and [#](../foo.md) can work too.

Also, whilst on this, the other relative links in GitHub are the file links like ../packages/db/src/foo.ts — I wonder if there’s a sensible way of detecting relative source file links and adding the right tree/blob GitHub URL prefix? Maybe too complex to be worth it.

Extends the normalization to handle paths like "guides/foo.md" (without ./) that should be treated as sibling directories. This ensures compatibility with various markdown link styles used in documentation. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

Extends normalization to handle all relative path formats: - "./foo.md" (explicit same directory) -> "../foo" - "foo.md" (bare filename, same directory) -> "../foo" - "./guides/foo.md" (explicit subdirectory) -> "../guides/foo" - "guides/foo.md" (bare subdirectory) -> "../guides/foo" This ensures all GitHub-compatible relative link formats work correctly on the website's routing structure. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

KyleAMathews · 2025-08-26T00:23:02Z

yeah, supporting relative links that aren't on the website seem like too much.

- Resolved merge conflict in db.$version.index.tsx by keeping upstream LibraryHero component - Removed accidentally committed .claude folder 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

- Extracted path normalization logic to separate utility function - Added comprehensive test suite with 33 test cases covering real examples from DB and Router docs - Handles all patterns: ./, ../, bare paths, external links, hash fragments - All tests pass, ensuring no regressions 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

erquhart and others added 30 commits January 22, 2025 10:35

fix: improve npm download count animation (TanStack#329)

09b5001

* improve npm download count animation * fix failure on package not found * update component dependency

fix repo link for start

38e1001

upgrade tanstack start

35c904c

fix: Separate Start Docs

03b8973

updated og image

1ed0762

Faster Start demo

4a7fbbd

devinxi

748b2e4

Add speakeasy as partner

9faa26f

feat: make the links in the TOC reactive to the visibility on the scr…

59d02bd

…een (TanStack#338) * feat: make the table of contents sections reactive to user-scroll * style: prettier format * chore: remove `console.log`

refactor: Reorder TSS links (TanStack#340)

0f4fe85

Use same order of library sublinks as all other libraries

Add ethos page

ed95724

Merge branch 'main' of https://github.com/TanStack/tanstack.com

e496eb4

update ethos

becbb04

update ethods

f150580

fix: use codesandbox for start embeds

dde7cb9

fix: keep the empty space besides headings out of the clickable area (T…

711c1c0

…anStack#343)

solid-router adaptations (TanStack#346)

0b7f31b

feat(router): add solid to router docs dropdown (TanStack#348)

ecf2d97

Give default monospace priority over Courier New (TanStack#350)

61428f8

fix: start header redirects to start doc (TanStack#339)

d04f879

Co-authored-by: Sean Cassiere <33615041+SeanCassiere@users.noreply.github.com>

chore(tanstack.com): upgrade vinxi, tanstack start, and vite (TanStac…

082a8ba

…k#345) Co-authored-by: Sean Cassiere <33615041+SeanCassiere@users.noreply.github.com>

fix(layout): doc container width not taking up all available space (T…

e1caa92

…anStack#352)

Remove react-cross-context (TanStack#355)

4c0fcf8

chore: remove vite (TanStack#356)

144b2bf

* chore: remove vite * chore: ignore netlify build output

disable header caching temporarily

7eae74c

bring back function caching, but vary by query=payload

baae710

feat: disable background animations for users preferring reduced moti…

59751c5

…on (TanStack#359)

chore: Update Form label to v1 (TanStack#363)

358f9b1

chore: add blog post for TanStack Form v1's launch (TanStack#364)

70d7547

* chore: add blog post for TanStack Form v1's launch * chore: run prettier

tannerlinsley and others added 20 commits August 22, 2025 10:14

builder perms

5fdbfbd

Auth

ff37f09

auth

0258339

Safer Auth

e65c8bd

fix auth

caafe21

fix auth

cc89e0a

no log

1891597

fix: prevent horizontal overflow on mobile devices (TanStack#474)

575114d

Co-authored-by: Tanner Linsley <tannerlinsley@gmail.com>

chore: github action to auto update tanstack dependencies (TanStack#473)

deb56ed

docs: added a CopyMarkdownButton component to copy page contents (T…

f4346b7

…anStack#469) Co-authored-by: Tanner Linsley <tannerlinsley@gmail.com>

fix: close details panel on link click in LibrariesLayout (TanStack#467)

db63753

Co-authored-by: Tanner Linsley <tannerlinsley@gmail.com>

fix: counters in the homepage no longer disappear on first load (TanS…

23bdaba

…tack#465) Co-authored-by: Kevin Van Cott <kevinvandy656@gmail.com> Co-authored-by: Tanner Linsley <tannerlinsley@gmail.com>

Fix auto-animate npm package name (TanStack#454)

af7c96b

Changed the auto-animate npm package name to the correct @formkit/auto-animate

Squashed commit of the following:

8e9dd1e

commit 22b948d Author: Shawn Erquhart <shawn@erquh.art> Date: Wed Jul 23 16:21:49 2025 -0400 add preview build command commit 2735a28 Author: Shawn Erquhart <shawn@erquh.art> Date: Mon Jul 21 23:35:12 2025 -0400 add stat counters to library pages

Add counters to config, db, and devtools

3689791

twitter => x, no logs

16bf411

better admin pagnination

90812e9

fix admin

eecb250

KyleAMathews and others added 2 commits August 25, 2025 18:08

KyleAMathews and others added 3 commits August 25, 2025 19:43

prettier

7981a52

tannerlinsley closed this Jan 11, 2026

tannerlinsley force-pushed the main branch from 2900b16 to 5d77284 Compare January 11, 2026 09:07

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix: normalize markdown links to work on both GitHub and website#477

fix: normalize markdown links to work on both GitHub and website#477
KyleAMathews wants to merge 1146 commits intoTanStack:mainfrom
KyleAMathews:github-style-links

KyleAMathews commented Aug 25, 2025 •

edited

Loading

Uh oh!

netlify bot commented Aug 25, 2025 •

edited

Loading

Uh oh!

thruflo commented Aug 26, 2025

Uh oh!

KyleAMathews commented Aug 26, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

20 participants

Uh oh!

Conversation

KyleAMathews commented Aug 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What this fixes

Context

Implementation

Test plan

Linkinator Verification ✅

Uh oh!

netlify bot commented Aug 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

❌ Deploy Preview for tanstack failed. Why did it fail? →

Uh oh!

thruflo commented Aug 26, 2025

Uh oh!

KyleAMathews commented Aug 26, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

20 participants

KyleAMathews commented Aug 25, 2025 •

edited

Loading

netlify bot commented Aug 25, 2025 •

edited

Loading