Repository navigation
Make capabilities/diataxis frontmatter a failing check - #5394
Merged
Jeremy Rose (jeremyrose-viam) merged 1 commit intoOct 7, 2026
Merged
Conversation
The docs-health daily metrics build failed seven times in two incidents (Sep 26-28, Oct 3-6) because PRs merged pages missing capabilities: or diataxis:. The docs check flagged both, but only as warnings. - Replace check-capabilities.py and check-diataxis.py with one importable scripts/frontmatter_rules.py that exits 1 on any missing or invalid value and annotates each failing file. docs-health will import its exclusion rules instead of keeping its own copy. - Align exclusions with docs-health: draft: true replaces the hardcoded template list, and glossary is detected by tag rather than path. The unexcluded corpus is 422 pages, matching docs-health's last good run. - Fail on unreadable frontmatter (missing, unclosed, invalid YAML) and on a non-list capabilities: instead of skipping or misreporting. - Drop the workflow's paths: filter so it can be a required check. - Add placeholder fields to the tutorial templates. - Document the rules in CLAUDE.md, including that new capability tags or Diataxis modes need a matching docs-health PR. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
✅ Deploy Preview for viam-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
viambot
added
the
safe to build
Jeremy Rose (jeremyrose-viam)
approved these changes
Oct 6, 2026
Jeremy Rose (jeremyrose-viam)
deleted the
claude/docs-health-guardrails-4ecf23
branch
October 7, 2026 20:53
|
🔎💬 Inkeep AI search and chat service is syncing content for source 'Viam Docs' |
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
3 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.
Why
The docs-health metrics build fails its sanity check, leaving the dashboard stale, whenever a published page is missing
capabilities:ordiataxis:. That happened twice recently:docs/reference/components/_index.mdfrom a redirect stub into a real page without addingdiataxis:(fixed in Declare diataxis: overview on reference/components index #5368).The docs check caught both, but only as warnings.
What changes
scripts/frontmatter_rules.pyreplacescheck-capabilities.pyandcheck-diataxis.py. It exits 1 on any missing or invalid value and puts an::errorannotation on each failing file, with a fix hint in the message.draft: trueinstead of a hardcoded template list, and glossary pages by theglossarytag instead of their path, matching docs-health'spartition_corpus. The unexcluded set is 422 pages, the same count as docs-health's last good run. A follow-up docs-health PR will import this module instead of keeping its own copy.capabilities:now fail with a clear message.paths:filter so the job can be a required status check, and so edits todata/*.yamlare checked too.capabilities:/diataxis:fields, so copied pages start with both fields.viamrobotics/docs-healthPR, merged together.Testing
capabilities:, listdiataxis:, unclosed frontmatter,draft: "false". CRLF frontmatter is accepted.make build-prodall pass.After merge
A repo admin needs to mark Check docs/ capability and Diataxis frontmatter as a required status check on
main. Without that, a failing check still doesn't block a merge.🤖 Generated with Claude Code