Skip to content

chore(links): use Docusaurus Link and Heading instead of raw HTML - #4825

Merged
thetaPC merged 2 commits into
mainfrom
docusaurus-link-heading
Nov 4, 2026
Merged

thetaPC merged 2 commits into
mainfrom
docusaurus-link-heading

Conversation

@thetaPC

@thetaPC thetaPC commented Nov 4, 2026

Copy link
Copy Markdown
Contributor

Issue URL: N/A

What is the current behavior?

The build's broken link and anchor checks only see Markdown links and Docusaurus components. A raw <a href> to a page that doesn't exist builds without errors, and a raw <h2> to <h4> can't be a checked link target. src/ and a few docs pages still use raw tags.

In v8, the Item page links go to the v9 pages, and the Angular testing page has two links with an empty href.

What is the new behavior?

  • Internal links use <Link>, so the build checks them: the Item page (current and v8) and APIList
  • External links use <Link> for consistency, which adds target="_blank" and rel="noopener noreferrer". DocsCard drops its own external-link branch for the same reason
  • Raw headings use <Heading>: ReleaseNotes, SteppedColorGenerator, DeveloperExperts, and the TOC
  • v8 Item page links point to the v8 pages, and the v8 Angular testing page links to Protractor and Jasmine
  • CONTRIBUTING.md has a new "Links and Headings" section saying to use these components first

Does this introduce a breaking change?

  • Yes
  • No

Other information

The App Wizard link now opens in a new tab, like every other external link.

Markup inside code samples is unchanged, since it's example code rather than part of the page.

Preview: v8 Item page, Playground ("Report an issue" in the tooltip)

@vercel

vercel Bot commented Nov 4, 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 4, 2026 9:52pm UTC

Request Review

@thetaPC
thetaPC marked this pull request as ready for review November 4, 2026 00:37
@thetaPC
thetaPC requested a review from a team as a code owner November 4, 2026 00:37
@thetaPC
thetaPC requested a review from brandyscarney November 4, 2026 00:37

@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!

The Install and Docs links on the VS Code extension page and its v8 copy are the last raw <a> tags outside code samples. Could we switch them to <Link> so the page matches the new CONTRIBUTING section? The import can go right under the frontmatter.

import Link from '@docusaurus/Link';

<Link to="vscode:extension/webnative.webnative" target="_self">
  <button className="install-button">Install</button>
</Link>
<Link to="https://webnative.dev/introduction/getting-started/" target="_self">
  <button className="docs-button">Docs</button>
</Link>

I'd keep target="_self" on both, since Link opens them in a new tab otherwise. With this change the page renders the same HTML as before, apart from the added rel="noopener noreferrer".

@thetaPC
thetaPC merged commit 9c84110 into main Nov 4, 2026
7 checks passed
@thetaPC
thetaPC deleted the docusaurus-link-heading branch November 4, 2026 22:01

This branch was successfully deployed

1 active deployment
Preview — 62dfcc92 Deployed Nov 4, 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