Skip to content

docs: link to other docs by relative file path - #4862

Draft
thetaPC wants to merge 3 commits into
nvmrcfrom
absolute-md-links
Draft

thetaPC wants to merge 3 commits into
nvmrcfrom
absolute-md-links

Conversation

@thetaPC

@thetaPC thetaPC commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

Issue URL: N/A

What is the current behavior?

  • Internal links use four styles: ../x.mdx, ./x, x.mdx, and /x.mdx.
  • A link without an extension is a URL, not a file, so Docusaurus can't check that the page exists or map it to the right version. Four links on v8's grid and tabs pages point at the current docs instead of v8.
  • Editors and GitHub can't follow a link without an extension, or one starting with /, which they read from the repo root.

What is the new behavior?

  • Every Markdown link is a relative file path with its extension, such as ./accordion.mdx or ../layout/css-utilities.mdx: 1,191 links across docs and v8.
  • Relative JSX hrefs become absolute URLs without an extension, such as /angular/navigation, or /v8/angular/navigation on v8 pages.
  • The four v8 links now point at v8's own pages.
  • The Links and Headings section in CONTRIBUTING describes the rule.

Does this introduce a breaking change?

  • Yes
  • No

Other information

A build of this branch matches #4860 on 11,695 of 11,699 pages and Markdown versions. The other 4 are the v8 grid and tabs pages and their Markdown versions, and only the four links differ.

@thetaPC
thetaPC added this pull request to stack #4861 November 18, 2026 00:43
@vercel

vercel Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
ionic-docs Ready Ready Preview Nov 18, 2026 3:46am UTC

Request Review

This branch was successfully deployed

1 active deployment
Preview — 1859a5d8 Deployed Nov 18, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant