Skip to content

fix(seo): add descriptions to pages leaking heading ids into search results - #4831

Open
thetaPC wants to merge 1 commit into
mainfrom
heading-id-descriptions
Open

thetaPC wants to merge 1 commit into
mainfrom
heading-id-descriptions

Conversation

@thetaPC

@thetaPC thetaPC commented Nov 5, 2026

Copy link
Copy Markdown
Contributor

Issue URL: N/A

What is the current behavior?

Six pages show text like isPlatform {/ #isplatform /} in Google results and link previews. Nothing looks wrong on the page itself, only in the <meta name="description"> tag.

Docusaurus builds a page's description from its first line of text when the frontmatter has none. On these pages that line is a heading, and Docusaurus doesn't remove the {/* #id */} heading ID syntax we adopted in #4742. It only strips the older {#id} form.

What is the new behavior?

These pages now set description in their frontmatter:

Page Before After
native/faq What is Capacitor? {/ #what-is-capacitor /} Answers to common questions about Capacitor, native permission issues, and unexpected native behavior in Ionic apps.
react/platform isPlatform {/ #isplatform /} Use isPlatform and getPlatforms to detect the platform an Ionic React app is running on, and customize how each platform is detected.
vue/platform isPlatform {/ #isplatform /} Use isPlatform and getPlatforms to detect the platform an Ionic Vue app is running on, and customize how each platform is detected.
vue/performance v-for with Ionic Components {/ #v-for-with-ionic-components /} Improve rendering performance in Ionic Vue apps by giving Ionic components a key when looping over them with v-for.
updating/4-0 Updating from Ionic 3 to 4 {/ #updating-from-ionic-3-to-4 /} Learn how to update an app to Ionic 4 from Ionic 3, or from Ionic 1 by moving from AngularJS to Angular.
react/testing/unit-testing/best-practices IonApp is required for test templates {/ #ionapp-is-required-for-test-templates /} Best practices for unit testing Ionic React apps, including wrapping test templates in IonApp, simulating user events, and waiting for components to render.

The v8 copies get the same descriptions. They don't leak today, since v8 headings aren't pinned yet, but their descriptions are the bare first heading, such as isPlatform.

Does this introduce a breaking change?

  • Yes
  • No

Other information

These are the only pages without a description whose first line after the title is a pinned heading. Other pages start with a paragraph, so their descriptions are unaffected.

The bug is still present in the Docusaurus v4 canary, so any new page that starts with a heading needs a description.

@vercel

vercel Bot commented Nov 5, 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 5, 2026 3:44am UTC

Request Review

@thetaPC
thetaPC marked this pull request as ready for review November 5, 2026 04:02
@thetaPC
thetaPC requested a review from a team as a code owner November 5, 2026 04:02
@thetaPC
thetaPC requested a review from brandyscarney November 5, 2026 04:02

This branch was successfully deployed

1 active deployment
Preview — 8978d34d Deployed Nov 5, 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