json-schema-org / json-schema-org/website

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

Open
#2,267 3 comments 0 reactions 1 assignee View on GitHub

@h30s is already working on this.

Since Feb 22, 2026.

🐛 Bug Status: Stale Status: Triage
Dominant language
HTML
Stars
169
Forks
484
Avg merge
2d 2h
Merged PRs (30d)
6

Description

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.