Repository navigation
docs: require a frontmatter description on every page - #4865
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
632189e to
7f11a82
Compare
brandyscarney
left a comment
There was a problem hiding this comment.
Looks good! Left a few suggestions. 👍
| message.source = 'ionic-docs'; | ||
| message.ruleId = 'page-description'; | ||
| }; | ||
| if (file.path?.split(/[\\/]/).some((segment) => segment.startsWith('_'))) return; |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
| 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)) { |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
| } | ||
|
|
||
| for (const node of tree.children) { | ||
| if (node.type !== 'mdxJsxFlowElement' || node.name !== 'head') continue; |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Done in 43cd63e. The tag name is compared case-insensitively, so <Head> from @docusaurus/Head is flagged too.
7f11a82 to
a18f890
Compare
a18f890 to
b1c7387
Compare
b1c7387 to
393baf4
Compare
393baf4 to
43cd63e
Compare
43cd63e to
57e0944
Compare
Issue URL: N/A
What is the current behavior?
<head>meta tag. Docusaurus doesn't read it, soog:descriptionand llms.txt fall back to an excerpt of the page, the path that leaked{/* #id */}comments into descriptions.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 bydeveloping/config.mdxare published as stray pages titled "index", in docs and v8.What is the new behavior?
descriptionin its frontmatter: 384 moved from<head>and 66 new.npm run lintfails on a page without a frontmatter description, or with one in<head>. Generated native and cli pages, and_files, are skipped.remark-frontmatter, so a<in a description no longer breaks it._<name>.mdx, removing the 10 stray pages.<title>still belongs in<head>.Does this introduce a breaking change?
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
og:descriptionnow matchesdescription, where on main it repeats the title.descriptionline from any page indocs/, or move it into a<head>meta tag.npm run lintfails on that page.Stacked on #4864.