Skip to content

🐛 Bug: Internal Markdown links break client-side routing and prefetching in StyledMarkdownBlock #2267

@h30s

Description

@h30s

Describe the bug

There is a significant misconfiguration in the StyledMarkdownBlock.tsx component that affects how internal links are handled within Markdown content. Currently, any link starting with / (internal links) is forced to open in a new tab (target="_blank") and is incorrectly mapped to href="/".

This implementation causes three primary issues:

  1. Broken SPA transitions: Every internal link opens a new tab and triggers a full page reload, losing the benefits of Next.js client-side navigation.
  2. Incorrect Prefetching: Since the <Link> component is hardcoded with href="/", Next.js prefetches the data for the homepage instance instead of the actual target documentation page.
  3. UX anti-pattern: Forcing internal documentation links to open in new tabs creates unnecessary tab clutter and deviates from standard web navigation expectations.

Steps To Reproduce

  1. Start the development server (yarn dev) or visit a page with markdown content like /learn/getting-started-step-by-step.
  2. Open the browser's Network tab.
  3. Hover over internal links and observe that Next.js prefetches / (the homepage) data rather than the linked page.
  4. Click an internal link.
  5. Notice it opens in a new tab and performs a full browser reload.

Expected Behavior

Internal links should navigate within the same tab, use the correct path for SPA routing, and prefetch the actual target content for instant navigation.

Screenshots

No response

Device Information [optional]

- OS:
- Browser:
- version:

Are you working on this issue?

Yes

Do you think this work might require an [Architectural Decision Record (ADR)]? (significant or noteworthy)

No

Metadata

Metadata

Assignees

Labels

Status: TriageThis is the initial status for an issue that requires triage.🐛 BugIndicates that the issue is a bug or defect.

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions