Add :description: to single-source stubs and lint for coverage - #664
Open
micheleRP wants to merge 2 commits into
Open
Add :description: to single-source stubs and lint for coverage#664micheleRP wants to merge 2 commits into
micheleRP wants to merge 2 commits into
Conversation
…ption Stub pages inherit nothing from their single-source includes: Antora resolves page metadata with a header-only parse, so all of these pages shipped the generic site-wide meta description. This copies each stub's description verbatim from its upstream counterpart (145 rpk stubs from the docs repo, 46 connect stubs from rp-connect-docs) into the stub header, where Antora picks it up. The 234 connect stubs whose upstream has no description yet are unchanged; they are tracked in the CI allowlist added in the next commit. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Adds hand-written descriptions for the three remaining non-stub pages (glossary and two index pages). The lint fails any page missing a :description: unless it is listed in .github/description-allowlist.txt, which tracks the 234 connect stubs whose rp-connect-docs upstream has no description yet; a non-blocking hygiene step flags allowlist entries that gain one. Over-155-char descriptions warn on changed files only. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
✅ Deploy Preview for rp-cloud ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
|
Important Review skippedToo many files! This PR contains 196 files, which is 46 over the limit of 150. To get a review, reduce the PR to 150 files or fewer by splitting it into smaller PRs or changing its base branch. Upgrade to Pro+ to raise the limit. This review couldn't start because sufficient usage credits or metered capacity aren't available. Add credits or update usage-based reviews in the billing tab, then retry. ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (196)
You can disable this status message by setting the Comment |
Contributor
|
One note for the 145 rpk backfills: these copy descriptions that regeneration rewrites (doc-tools 5.3.3 alone rewrote ~36 rpk descriptions), and unlike adp-docs there's no sync workflow here, so the copied headers will drift over time — the lint checks presence, not freshness. docs-extensions-and-macros#246 prototypes the dynamic alternative (stubs inherit the description from the included partial at build time, verified against an Antora build with the production UI bundle) and composes with this PR: backfills stay correct now, and stubs that later adopt the two-include shape stop needing them. Doesn't affect this PR's merge-readiness or the Connect allowlist. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this does
Brings
:description:coverage from 476/904 pages to 670/904 — every page that can have one today — and adds a CI lint with an allowlist ratchet so coverage only improves.Why stubs were missing descriptions
Single-source stub pages inherit nothing from their
include::...[tag=single-source]directives: Antora resolves page metadata with a header-only parse that stops at the stub's first blank line, so the include is never evaluated for attributes. Every affected stub ships the generic site-wide meta description (check anyrpk clusterpage's<meta name="description">on the live site). The single-sourcing standard already calls for stubs to carry their ownTitle + :description: + include— this PR brings 191 stubs into that shape.Changes
page$, andpartial$include families.reference/glossary,develop/connect/cookbooks/index,develop/connect/guides/index..github/workflows/lint-metadata.yml: fails any PR that leaves a page without:description:unless the page is listed in.github/description-allowlist.txt; warns (non-blocking) when an allowlisted page gains a description (remove the entry) and when a changed page's description exceeds the 155-char style-guide recommendation..github/description-allowlist.txt: the 234 connect stubs whose rp-connect-docs upstream has no description yet. The fix path is upstream (docs-data/overrides.jsonin rp-connect-docs); as descriptions land there, re-copy into these stub headers and shrink the list.Notes
:description:on newly created stubs).🤖 Generated with Claude Code
Preview pages
194 pages updated (one
:description:header line each; no visible body changes — check<meta name="description">in page source). Representative samples: