Skip to content

docs: require a frontmatter description on every page - #4865

Merged
thetaPC merged 3 commits into
mainfrom
chore/require-descriptions
Nov 19, 2026
Merged

thetaPC merged 3 commits into
mainfrom
chore/require-descriptions

Conversation

@thetaPC

@thetaPC thetaPC commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Issue URL: N/A

What is the current behavior?

  • 384 pages set their description in a <head> meta tag. Docusaurus doesn't read it, so og:description and llms.txt fall back to an excerpt of the page, the path that leaked {/* #id */} comments into descriptions.
  • 66 pages have no description at all.
  • exclude: ['README.md'] in the docs config replaces Docusaurus's default excludes, so files starting with _ are built as pages. The five config examples imported by developing/config.mdx are published as stray pages titled "index", in docs and v8.

What is the new behavior?

  • Every page in docs and v8 has a description in its frontmatter: 384 moved from <head> and 66 new.
  • npm run lint fails on a page without a frontmatter description, or with one in <head>. Generated native and cli pages, and _ files, are skipped.
  • The lint parses frontmatter with remark-frontmatter, so a < in a description no longer breaks it.
  • The docs config restores Docusaurus's default excludes, and the five config examples become _<name>.mdx, removing the 10 stray pages.
  • CONTRIBUTING describes both rules, and why a longer <title> still belongs in <head>.

Does this introduce a breaking change?

  • Yes
  • No

Other information

Compared with a build of #4862, the 384 moved pages change only og:description, which now matches the unchanged meta description. The 66 new ones change both tags, and the stray pages are gone. Every other page and Markdown version is identical.

How to test

  1. View the source of the preview's Button page. og:description now matches description, where on main it repeats the title.
  2. View the source of the preview's Backdrop page, which had no description. Both tags now hold the new one.
  3. Open the preview's stray Global page. It's a 404 now, while production still serves it.
  4. Locally, delete the description line from any page in docs/, or move it into a <head> meta tag. npm run lint fails on that page.

Stacked on #4864.

@thetaPC
thetaPC added this pull request to stack #4861 November 18, 2026 01:35
@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 19, 2026 11:41pm UTC

Request Review

@brandyscarney brandyscarney 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! Left a few suggestions. 👍

Comment thread .remarkrc.mjs Outdated
message.source = 'ionic-docs';
message.ruleId = 'page-description';
};
if (file.path?.split(/[\\/]/).some((segment) => segment.startsWith('_'))) return;

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.

This tests every folder in the absolute path, not just the part under docs/. On a runner whose workspace sits in a _ folder (self-hosted runners use _work/), or a clone inside one, every page is skipped and the rule silently passes. I reproduced it by putting the repo under a _t/ folder. Testing the path relative to the docs root (or process.cwd()) would avoid it.

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.

Good catch, done in 43cd63e. The rule now tests the path relative to the working directory. I reproduced the silent pass under a _t/ folder, and it now flags the page.

Comment thread .remarkrc.mjs Outdated
if (file.path?.split(/[\\/]/).some((segment) => segment.startsWith('_'))) return;

const frontmatter = tree.children[0]?.type === 'yaml' ? tree.children[0].value : '';
if (!/^description:\s*\S/m.test(frontmatter)) {

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.

Edge case: description: '' passes, because the quote counts as \S. Nothing in the repo does this today. Parsing the frontmatter, or excluding an empty quoted string, would catch it.

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.

Done in 43cd63e. An empty quoted string, '' or "", now fails. I kept it a regex instead of parsing the YAML, since every description in the repo is on the key's line and parsing would mean a new dependency.

Comment thread .remarkrc.mjs Outdated
}

for (const node of tree.children) {
if (node.type !== 'mdxJsxFlowElement' || node.name !== 'head') continue;

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.

Edge case: this only matches lowercase <head>, so a description added through <Head> from @docusaurus/Head wouldn't be flagged. That doesn't happen today, since this PR removes those imports, but node.name?.toLowerCase() !== 'head' would cover it.

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.

Done in 43cd63e. The tag name is compared case-insensitively, so <Head> from @docusaurus/Head is flagged too.

@thetaPC
thetaPC merged commit 95f9eca into main Nov 19, 2026
7 checks passed
@thetaPC
thetaPC deleted the chore/require-descriptions branch November 19, 2026 23:54

This branch was successfully deployed

1 active deployment
Preview — 57e09444 Deployed Nov 19, 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.

3 participants