Skip to content

docs: link to docs by relative file path instead of full URLs - #4882

Merged
thetaPC merged 3 commits into
mainfrom
doc-links-no-full-urls
Nov 20, 2026
Merged

thetaPC merged 3 commits into
mainfrom
doc-links-no-full-urls

Conversation

@thetaPC

@thetaPC thetaPC commented Nov 20, 2026

Copy link
Copy Markdown
Contributor

Issue URL: N/A

What is the current behavior?

  • 29 links in docs/ use a full ionicframework.com/docs URL. A full URL always opens the current version, so once v10 ships, these links on the v9 pages send readers to v10.
  • The link lint skips any URL with a scheme, so nothing stops new ones.

What is the new behavior?

  • The 29 links are relative file paths, so they stay in the reader's version. They're on the Angular and React overlays pages, the 7.0 migration guide, the Icon accessibility link on input, select and textarea, and the glossary.
  • npm run lint fails on a Markdown link to a doc by its full ionicframework.com/docs URL. Archived versions such as /docs/v3/ and static files are still allowed.
  • CONTRIBUTING mentions the rule.

Does this introduce a breaking change?

  • Yes
  • No

Other information

v8 got the same fix in #4879. The next sync into major-10.0 carries this into v9, which makes #4881 unnecessary.

How to test

  1. On the preview's Angular Overlays page, click Modal in the list at the bottom: it stays on the preview instead of opening production.
  2. Locally, change any relative link in docs/ to its full https://ionicframework.com/docs/... URL. npm run lint fails on that line.

@vercel

vercel Bot commented Nov 20, 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 20, 2026 6:13pm UTC

Request Review

@thetaPC
thetaPC marked this pull request as ready for review November 20, 2026 01:09
@thetaPC
thetaPC requested a review from a team as a code owner November 20, 2026 01:09
@thetaPC
thetaPC requested a review from ShaneK November 20, 2026 01:09

@ShaneK ShaneK left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me, great work! Just a couple of small wording nits, feel free to take or leave them.

Comment thread CONTRIBUTING.md Outdated
- [`<Heading>`](https://docusaurus.io/docs/api/misc/@docusaurus/eslint-plugin/prefer-docusaurus-heading) from `@theme/Heading` instead of `<h2>` to `<h6>`.

Link to another doc by its relative file path, with the extension, such as `[Accordion](./accordion.mdx)` or `[Config](../developing/config.mdx)`. Docusaurus resolves it to the page in the same version, the build fails if the file doesn't exist, and editors can follow it to the file. A JSX prop such as `href` skips that step, so use the URL path without `/docs` or an extension instead: `/api/accordion`, or `/v8/api/accordion` on a v8 page. `npm run lint` flags a link in either form that doesn't follow this.
Link to another doc by its relative file path, with the extension, such as `[Accordion](./accordion.mdx)` or `[Config](../developing/config.mdx)`. Docusaurus resolves it to the page in the same version, the build fails if the file doesn't exist, and editors can follow it to the file. Don't link to a doc by its full `ionicframework.com/docs` URL, which always opens the current version. A JSX prop such as `href` skips that step, so use the URL path without `/docs` or an extension instead: `/api/accordion`, or `/v8/api/accordion` on a v8 page. `npm run lint` flags a link in either form that doesn't follow this.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Link to another doc by its relative file path, with the extension, such as `[Accordion](./accordion.mdx)` or `[Config](../developing/config.mdx)`. Docusaurus resolves it to the page in the same version, the build fails if the file doesn't exist, and editors can follow it to the file. Don't link to a doc by its full `ionicframework.com/docs` URL, which always opens the current version. A JSX prop such as `href` skips that step, so use the URL path without `/docs` or an extension instead: `/api/accordion`, or `/v8/api/accordion` on a v8 page. `npm run lint` flags a link in either form that doesn't follow this.
Link to another doc by its relative file path, with the extension, such as `[Accordion](./accordion.mdx)` or `[Config](../developing/config.mdx)`. Docusaurus resolves it to the page in the same version, the build fails if the file doesn't exist, and editors can follow it to the file. A JSX prop such as `href` skips that step, so use the URL path without `/docs` or an extension instead: `/api/accordion`, or `/v8/api/accordion` on a v8 page. In either form, don't link to a doc by its full `ionicframework.com/docs` URL, which always opens the current version. `npm run lint` flags a link that doesn't follow this, though it only catches a full URL in a Markdown link.

Moving the full-URL sentence after the JSX one, since right now "that step" reads like it points back at the full-URL rule instead of Docusaurus resolving the file. The lint claim also needed scoping, because checkJsxLink returns early for anything with a scheme, so a full docs URL in an href or to prop passes while the same URL in a Markdown link gets flagged. I didn't go the other way and add the check to checkJsxLink since it would trip on the canonical and alternate <link> tags in the <head> of docs/index.mdx. This is just a nit though, up to you!

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applied in be510c6, thanks!

Comment thread .remarkrc.mjs Outdated
Comment on lines +13 to +15
// A page on this site by its full URL. Archived versions such as `/docs/v3/`
// are not built from this repo, so they stay full URLs.
const DOCS_SITE_URL = /^https?:\/\/(www\.)?ionicframework\.com\/docs(?!\/v\d+(\/|$))(\/|$|[?#])/i;

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
// A page on this site by its full URL. Archived versions such as `/docs/v3/`
// are not built from this repo, so they stay full URLs.
const DOCS_SITE_URL = /^https?:\/\/(www\.)?ionicframework\.com\/docs(?!\/v\d+(\/|$))(\/|$|[?#])/i;
// A page on this site by its full URL. A versioned URL such as `/docs/v3/` or
// `/docs/v8/` opens that version rather than the current one, so it is allowed.
const DOCS_SITE_URL = /^https?:\/\/(www\.)?ionicframework\.com\/docs(?!\/v\d+(\/|$|[?#]))(\/|$|[?#])/i;

The reason in this comment doesn't cover /docs/v8/, which we do build from this repo, though exempting it is right since a /docs/vN URL opens that version anyway. While I was poking at it I noticed a URL like https://ionicframework.com/docs/v8#something gets flagged with "A full URL always opens the current version", which isn't true for that one, so I added ? and # to the lookahead too. With this change, a v9 page and a v8 page still flag /docs/api/modal and nothing else. Up to you!

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applied in 22d7a7d, good catch on the # and ? case!

@thetaPC
thetaPC merged commit e56f821 into main Nov 20, 2026
7 checks passed
@thetaPC
thetaPC deleted the doc-links-no-full-urls branch November 20, 2026 18:18

This branch was successfully deployed

1 active deployment
Preview — 22d7a7d4 Deployed Nov 20, 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.

2 participants