fix: normalize markdown links to work on both GitHub and website #477
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 <[email protected]>
❌ Deploy Preview for tanstack failed. Why did it fail? →
|
|
Cool! Bit nervous matching slightly arbitrarily on 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 <[email protected]>
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 <[email protected]>
|
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 <[email protected]>
- 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 <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
MarkdownLinkcomponent to handle the difference between GitHub's file-based paths and the website's route-based paths/library/version/docs/file(without trailing slash)What this fixes
The normalization handles all these relative path formats:
./foo.md(explicit same directory) →../foofoo.md(bare filename, same directory) →../foo./guides/foo.md(explicit subdirectory) →../guides/fooguides/foo.md(bare subdirectory) →../guides/fooContext
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:
docs/overview.mdtodocs/guides/live-queries.mduses./guides/live-queries.md/library/version/docs/overview(no trailing slash), so relative paths resolve differently and need../guides/live-queries.mdImplementation
src/utils/normalize-markdown-path.tsTest plan
Test that existing documentation links still work correctly on the websiteVerify that GitHub-style relative links (./path) now work on the websiteVerify that bare filenames (foo.md) work for same-directory linksVerify that bare paths (guides/foo.md) work for subdirectory linksCheck that absolute paths and external links are unaffectedLinkinator Verification ✅
Used linkinator to scan live deploy preview for broken links across multiple TanStack libraries:
All markdown link normalization is working perfectly in production!
🤖 Generated with Claude Code