Skip to content

Add local Vale KB style rules (NetwrixKB)#759

Merged
hilram7 merged 1 commit intodevfrom
feature/vale-kb-styles
Apr 14, 2026
Merged

Add local Vale KB style rules (NetwrixKB)#759
hilram7 merged 1 commit intodevfrom
feature/vale-kb-styles

Conversation

@hilram7
Copy link
Copy Markdown
Collaborator

@hilram7 hilram7 commented Apr 14, 2026

Summary

  • Creates a new Vale style, NetwrixKB, scoped exclusively to docs/kb/**/*.md
  • Activates the style in .vale.ini, replacing the previous empty BasedOnStyles = that disabled all Vale checking on KB files
  • KB files now receive KB-specific rules only — the Netwrix style is intentionally excluded to avoid a direct conflict (Netwrix promotes contractions; KB requires writing them out in full)

Changes

  • .vale.ini — updated [docs/kb/**/*.md] section from BasedOnStyles = to BasedOnStyles = NetwrixKB
  • .vale/styles/NetwrixKB/Contractions.yml — flags contractions (don't, can't, it's, etc.) and prompts writing them out in full; opposite direction from Netwrix.Contractions
  • .vale/styles/NetwrixKB/HeadingCase.yml — enforces Chicago-style title case for all headings
  • .vale/styles/NetwrixKB/FirstPersonPlural.yml — adapted from Netwrix style
  • .vale/styles/NetwrixKB/Please.yml — adapted from Netwrix style
  • .vale/styles/NetwrixKB/NoteThat.yml — adapted from Netwrix style; message updated to reference KB blockquote callouts (> NOTE:) instead of Docusaurus admonitions
  • .vale/styles/NetwrixKB/WeakLinkText.yml — adapted from Netwrix style
  • .vale/styles/NetwrixKB/ImpersonalFiller.yml — adapted from Netwrix style
  • .vale/styles/NetwrixKB/Utilize.yml — adapted from Netwrix style

Testing

All tests sucessful and run locally with Vale 3.14.1.

  • Contractions fires on KB file — NetwrixKB.Contractions flagged it's in docs/kb/threatmanager/integration-and-event-collection/no-threats-detected-despite-web-console-reporting-events.md
  • HeadingCase fires on KB file — NetwrixKB.HeadingCase flagged a lowercase heading in docs/kb/privilegesecurediscovery/authentication-and-access/saml-assertion-not-yet-valid.md
  • WeakLinkText fires on KB file — NetwrixKB.WeakLinkText flagged Learn more in the WinRM troubleshooting article (note: one known false positive — rule catches "Learn more" in body text, not just link text; same limitation exists in Netwrix.WeakLinkText)
  • Netwrix rules do NOT fire on KB files — no Netwrix.Contractions warning appeared on the WinRM article despite containing "do not"; KB files are correctly isolated to NetwrixKB only
  • NetwrixKB rules do NOT fire on docs files — docs/privilegesecure/4.2/admin/configuration/integrationconnector/integrationbyov/byovconnectorconfig.md
    returned 17 Netwrix.* warnings and zero NetwrixKB.* warnings

Notes

  • This PR covers local usage only — CI autofix for KB files (vale-autofix-kb.yml) is a separate follow-up
  • Contributors can run vale from the repo root after installing Vale (brew install vale + vale sync)

Create .vale/styles/NetwrixKB/ with eight rules scoped to KB articles,
and activate the style for docs/kb/**/*.md in .vale.ini.

Two rules are KB-specific:
- Contractions: flags contractions (don't, can't, it's, etc.) and prompts
  writing them out in full, the opposite of the existing Netwrix.Contractions rule
- HeadingCase: enforces Chicago-style title case for headings

Six rules are adapted from the Netwrix style: FirstPersonPlural, Please,
NoteThat, WeakLinkText, ImpersonalFiller, Utilize.

The docs/kb/**/*.md section previously had BasedOnStyles = (empty), which
disabled all Vale checking on KB files. KB files now receive NetwrixKB rules
only — the Netwrix style is intentionally excluded to avoid the contractions
conflict (Netwrix promotes contractions; KB requires writing them out in full).

TSEs can run 'vale <kb-file>' locally for KB-specific feedback.
@hilram7 hilram7 merged commit a4f6184 into dev Apr 14, 2026
7 checks passed
@hilram7 hilram7 deleted the feature/vale-kb-styles branch April 14, 2026 20:30
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.

1 participant