Repository navigation
docs(contribute): require sentence-case headings including catalog labels - #595
Merged
Merged
Conversation
…bels Codify option A: every framework H2/H3 uses sentence case, including reserved names (Further reading, What this framework covers, Related frameworks). Update style guide, content model, checklist, template, contributing guide, AGENTS.md, and validator comments. Matching stays case-insensitive so unmigrated framework Title Case still validates until framework PRs convert.
Deploying frameworks with
|
| Latest commit: |
eb80b2f
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://549c5771.frameworks-573.pages.dev |
| Branch Preview URL: | https://docs-sentence-case-headings.frameworks-573.pages.dev |
s1ns3nz0
added a commit
to s1ns3nz0/frameworks
that referenced
this pull request
Jul 27, 2026
…standard Applies the standard introduced in security-alliance#561 and the sentence-case heading rule from security-alliance#595: - Renames 'Further Reading & Tools' to 'Further reading' on all four pages - Renames the overview's page map section to 'What this framework covers' - Moves three Rego comments into the surrounding prose The last change is a workaround rather than an improvement. utils/validate-content.cjs extracts headings without stripping fenced code, so a line-start '#' comment inside a Rego block parses as an H1 and any following H3 is reported as heading_level_skip. Noted on the PR. Claude-Session: https://claude.ai/code/session_01CPQ1FcHGiBKWPd8waT7uGx
3 of 9 tasks
9 tasks
s1ns3nz0
added a commit
to s1ns3nz0/frameworks
that referenced
this pull request
Aug 24, 2026
…standard Applies the standard introduced in security-alliance#561 and the sentence-case heading rule from security-alliance#595: - Renames 'Further Reading & Tools' to 'Further reading' on all four pages - Renames the overview's page map section to 'What this framework covers' - Moves three Rego comments into the surrounding prose The last change is a workaround rather than an improvement. utils/validate-content.cjs extracts headings without stripping fenced code, so a line-start '#' comment inside a Rego block parses as an H1 and any following H3 is reported as heading_level_skip. Noted on the PR. Claude-Session: https://claude.ai/code/session_01CPQ1FcHGiBKWPd8waT7uGx
s1ns3nz0
added a commit
to s1ns3nz0/frameworks
that referenced
this pull request
Aug 31, 2026
…standard Applies the standard introduced in security-alliance#561 and the sentence-case heading rule from security-alliance#595: - Renames 'Further Reading & Tools' to 'Further reading' on all four pages - Renames the overview's page map section to 'What this framework covers' - Moves three Rego comments into the surrounding prose The last change is a workaround rather than an improvement. utils/validate-content.cjs extracts headings without stripping fenced code, so a line-start '#' comment inside a Rego block parses as an H1 and any following H3 is reported as heading_level_skip. Noted on the PR. Claude-Session: https://claude.ai/code/session_01CPQ1FcHGiBKWPd8waT7uGx
mattaereal
pushed a commit
that referenced
this pull request
Aug 31, 2026
* Add Policy as Code section under DevSecOps Adds docs/pages/devsecops/policy-as-code/ with four pages covering how a policy engine is applied across the CI/CD pipeline, and what NIST SP 800-204D requires of it: - overview: what a policy engine decides, the two evaluation modes (pipeline artifacts versus platform configuration), and the four places the standard names a policy enforcement engine - ci-pipeline: commit, merge, and build gates - release-and-runtime: publishing identity, deployment gates, drift detection - governance: which violations block, who may override, where thresholds come from, and how rules are owned and retired Existing DevSecOps pages document which controls to enable. These cover the decision layer above them, and link out to those pages rather than restating their content. Rego examples are validated against OPA 1.4.2, including the expiring-exception behaviour the governance page relies on. They are fenced as `python` because the site's Shiki bundle has no Rego grammar and an unrecognized language fails the build; the overview page carries a note to that effect. Also: - Registers the section in vocs.config.ts as a nested group with dev: true - Updates the DevSecOps overview contents list - Adds an s1ns3nz0 entry to contributors.json - Adds Rekor to wordlist.txt for the spell check Verified: pnpm run docs:build, cspell, and markdownlint-cli2 all pass. Claude-Session: https://claude.ai/code/session_01CPQ1FcHGiBKWPd8waT7uGx * docs(devsecops): align Policy as Code with the content normalization standard Applies the standard introduced in #561 and the sentence-case heading rule from #595: - Renames 'Further Reading & Tools' to 'Further reading' on all four pages - Renames the overview's page map section to 'What this framework covers' - Moves three Rego comments into the surrounding prose The last change is a workaround rather than an improvement. utils/validate-content.cjs extracts headings without stripping fenced code, so a line-start '#' comment inside a Rego block parses as an H1 and any following H3 is reported as heading_level_skip. Noted on the PR. Claude-Session: https://claude.ai/code/session_01CPQ1FcHGiBKWPd8waT7uGx * docs(devsecops): fix bullet count in Policy as Code overview Address review nit: "Two things have to come from your organization" was followed by three bullets. Merge the trailing bullet into the rule-content item so the count matches. Claude-Session: https://claude.ai/code/session_01CPQ1FcHGiBKWPd8waT7uGx * docs(devsecops): apply review feedback on Policy as Code Address @scode2277's review on #592: - Attribute SP 800-204D precisely: it names a policy enforcement engine as one technique and OPA as an example, rather than "officially recommending" either. - Move the python-fence note off the overview, which has no code blocks, and place it once above the first Rego block on each page that does. - Rewrite the tj-actions passage with the reported figures (23,000+ repos, ~218 leaked secrets, mostly short-lived workflow tokens). - Replace the publish-stage paragraph that restated the "two stages hold by convention" section later on the same page. - Apply RFC modality to all four checklists, per the normative modality rules in docs/pages/contribute/style-and-terminology.mdx. - Trim "The basics" on the overview: fold policy-data detail into its definition, collapse the SSDF and 800-204D descriptions, and drop the bulleted restatement of the enforcement-point consequences. Claude-Session: https://claude.ai/code/session_01CPQ1FcHGiBKWPd8waT7uGx * docs(devsecops): remove second person and Rego fence notes Second round of review feedback on #592: - Drop the three python-fence notes. The fence is a Shiki/vocs grammar gap being tracked upstream by the maintainers, not something readers need explained on the page. - Replace all 24 uses of you/your with concrete subjects, per the "concrete subjects: teams, operators, signers, maintainers, responders, stewards" rule in docs/pages/contribute/style-and-terminology.mdx. Pages should not assume an individual reader rather than an organization. The overview heading "What a policy engine gives you" becomes "What a policy engine provides"; no page links to the old anchor. Claude-Session: https://claude.ai/code/session_01CPQ1FcHGiBKWPd8waT7uGx --------- Co-authored-by: Sara Russo <sararusso984@gmail.com>
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
1 participant
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.
Summary
Codifies option A from review: every framework body heading (
#/##/###) uses sentence case, including reserved catalog labels.## Further reading## Further Reading,## Further Reading & Tools## What this framework covers## What This Framework Covers## Related frameworks## Related FrameworksWhy a new PR
#561 already merged the content normalization standard. This doc fix was briefly pushed to the old
docs/content-normalization-standardbranch after merge; this PR rebase-targetsdevelopinstead.Scope
Docs / tooling comments only — no framework content recasing in this PR (framework PRs can adopt preferred spellings during normalization).
docs/pages/contribute/style-and-terminology.mdx— rule + examplesdocs/pages/contribute/content-model.mdx— catalogs + opening skeletondocs/pages/contribute/docs-normalization-checklist.mdxdocs/pages/contribute/contributing.mdxdocs/pages/config/template.mdxAGENTS.mdutils/validate-content.cjs— comments only; matchers stay case-insensitive so unmigrated Title Case still validatesTest plan
node utils/validate-content.cjs --path docs/pages/monitoringstill passes (case-insensitive catalog match)