Skip to content

feat: enable Coder.Semicolons Vale rule - #30787

Merged
nickvigilante merged 4 commits into
mainfrom
vigilante/docs-1261-style-guide-ban-semicolons-in-prose-and-add-codersemicolons
Oct 27, 2026
Merged

nickvigilante merged 4 commits into
mainfrom
vigilante/docs-1261-style-guide-ban-semicolons-in-prose-and-add-codersemicolons

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 14, 2026 •

Copy link
Copy Markdown
Collaborator

Depends on #30782.

Adds Coder.Semicolons, a Vale rule that flags a semicolon in prose.
It enforces No semicolons in prose.

  • Severity: warning.
  • Scope: paragraphs, list items, headings, and blockquotes in docs/** except docs/.style/style-guide/**.
    Table cells, code spans, and code blocks keep their semicolons.
  • Baseline: 137 findings.
    The cleanup commit fixes 112 of them across 61 files by splitting sentences, or by using a comma or a connecting word where a split reads badly.
  • Excluded in .vale.ini: docs/reference/{api,cli}/*.md and docs/admin/setup/configuration-reference.md.
    Their text is generated from Go source (CLI flag help, Swagger comments), and 25 findings live there.
    Fixing them means editing Go and regenerating, so I used a commented exclusion like Coder.UnitSpacing does.
    Say so if you prefer the Go fix.
  • Result: vale --output=line docs/ reports 0 Coder.Semicolons findings outside the style guide.
  • Three headings lost a semicolon, so their anchors changed.
    I updated the links in docs/.style/ and in .claude/ (DOCS_STYLE_GUIDE.md, the write-docs and doc-check skills).

Linear: DOCS-1261

Decision log
  • Scope list is paragraph, list, heading, blockquote. Without blockquote, a semicolon in a > quote goes unreported, which I checked.
    Table cells are outside those scopes, so they stay exempt without extra config.
  • Token is (?<!TL);(?!DR). TL;DR in telemetry.md is an abbreviation, not punctuation.
  • &nbsp; entities and style="a: b;" attributes don't match. Vale can report a real semicolon on the wrong line of a paragraph that contains an entity or raw HTML (for example, modules.md:69 pointed at a semicolon on line 71), so cleanup used a paragraph-wide search instead of trusting reported lines.
  • A semicolon inside a fenced block in a blockquote (ai-gateway/monitoring.md:105, a YAML comment) isn't reported and stays.
  • Cleanup default: ; x becomes . X, then I reviewed the diff and hand-fixed list fragments, parentheticals, and headings.
    Each new sentence sits on its own line, outside table cells. The hand-written part of prometheus.md is also reformatted to one sentence per line.
  • Heading rewrites: Verify against the code and document exact values, Evidence justifies a claim and does not belong in the claim, STUN returned different addresses and you may be behind a hard NAT.
  • prometheus.md is in the generated-page exclusion for Coder.UnitSpacing but not here. Its semicolon was in hand-written prose, so I fixed it.
  • Enable commit updates the footer, the checks table (scope text matches .vale.ini), the coverage counts (Capitalization and punctuation 3/7 to 4/6, total 21 to 22 tool-checked and 24 to 23 planned, on top of main's Coder.StepLength), and the "What the tooling checks" counts.

Tests (fixtures in /tmp, not committed), each run with LF and CRLF files:

  • Flagged: paragraph, list item, ordered list item, heading, blockquote.
  • Not flagged: table cell, code span, fenced block, &nbsp; and &amp;, an HTML style attribute, and TL;DR.
  • go run ./scripts/styleclaims, make lint/emdash, and the pre-commit hook (markdown, typos, style-claims) pass.

Generated by Coder Agents on behalf of @nickvigilante.


🤖 Built with AI assistance.

@linear-code

linear-code Bot commented Oct 14, 2026

Copy link
Copy Markdown

DOCS-1261

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Docs preview

Check off each page once it's been reviewed. If a page changes in a later push, its checkbox clears automatically so it gets a fresh look. Pages not yet wired into the docs navigation aren't listed here.

@nickvigilante
nickvigilante force-pushed the vigilante/docs-1261-style-guide-ban-semicolons-in-prose-and-add-codersemicolons branch from 63e69a8 to 5af7f91 Compare October 14, 2026 20:52
Base automatically changed from vigilante/docs-1282-style-guide-add-missing-rules-from-the-docs-style-guide to main October 16, 2026 13:53
@nickvigilante
nickvigilante marked this pull request as ready for review October 23, 2026 05:14

@ianjevans ianjevans left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left a lot of suggested changes to fix inconsistent one sentence per line usage in the changed files.

Comment thread docs/user-guides/user-secrets.md Resolved
Comment thread docs/user-guides/user-secrets.md Resolved
Comment thread docs/user-guides/user-secrets.md Resolved
Comment thread docs/user-guides/user-secrets.md Resolved
Comment thread docs/user-guides/user-secrets.md Resolved

@ianjevans ianjevans left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left a lot of suggested changes to fix inconsistent one sentence per line usage in the changed files.

@nickvigilante
nickvigilante force-pushed the vigilante/docs-1261-style-guide-ban-semicolons-in-prose-and-add-codersemicolons branch from fa9b6b2 to cdc0051 Compare October 24, 2026 05:34

@ianjevans ianjevans left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

Apply the review suggestions that split the sentences a removed semicolon
joined, and split the same sentence breaks on pages that main reformatted to
one sentence per line after the sweep was written. Reformat the hand-written
part of the Prometheus page to one sentence per line.

Finish the sweep on pages where the rebase kept main's text, and update the
links to the two content-guidelines headings the sweep renames.
@nickvigilante
nickvigilante force-pushed the vigilante/docs-1261-style-guide-ban-semicolons-in-prose-and-add-codersemicolons branch from cdc0051 to 3e855ff Compare October 27, 2026 00:42
@nickvigilante
nickvigilante enabled auto-merge (squash) October 27, 2026 00:42
Main's StepLength sweep split several steps that this branch had also
rewritten to drop semicolons. Keep both: main's step split, then the
semicolon-free sentences. Split the one new semicolon main added in the
Nix integration page, and recount the style guide coverage now that both
StepLength and Semicolons are tool-checked.

Assisted-by: AI
@nickvigilante
nickvigilante merged commit 21471da into main Oct 27, 2026
28 checks passed
@nickvigilante
nickvigilante deleted the vigilante/docs-1261-style-guide-ban-semicolons-in-prose-and-add-codersemicolons branch October 27, 2026 16:44
@github-actions github-actions Bot locked and limited conversation to collaborators Oct 27, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants