Contributor-facing style and content guidance for the Coder documentation. Nothing under this directory is published to coder.com/docs.
| Path | Purpose |
|---|---|
content-guidelines.md |
Canonical content rules: what belongs in docs/, what doesn't, why |
style-guide/ |
Canonical prose style guide for docs/ |
styles/Coder/ |
Custom Vale rules specific to Coder (product voice, terms) |
Refer to content-guidelines.md for the canonical rules on what content belongs in docs/ and what to route elsewhere (blog, changelog, Support KB, and so on).
Visit style-guide/ for the prose style guide.
The styles/Coder/ directory holds the custom Vale rules that enforce parts of the guide.
Vale's StylesPath in the repo-root .vale.ini points at docs/.style/styles/.
Why a hidden directory
The leading dot mirrors the .github/, .vscode/, and .claude/ convention already used in this repo for tooling-internal directories.
The structural Markdown linters and Vale still pick it up (except the style guide's own prose under style-guide/, which is exempt).
Coder.com's docs site does not.
Refer to "What does not run against this directory" below for that exemption.
coder.com/docs routes and search are manifest-driven:
- Route discovery lives in
coder/coder.com:src/utils/docs/docs.ts(getDocsStaticPaths). It iteratesroutesfromdocs/manifest.jsonand emits one Next.js static path per entry. Files not in the manifest do not become routes. - The Algolia surgical indexer at
coder/coder.com:src/utils/algoliaDocs/surgical.tsexplicitly skips paths that are not in the manifest, incrementingpathsSkipped.
Net result: not adding anything from docs/.style/ to docs/manifest.json gives us no route, no Algolia record, and no sidebar entry.
Two defense-in-depth changes in .github/workflows/deploy-docs.yaml keep the deploy workflow from running on .style-only commits and exclude the directory from the surgical-reindex payload on mixed commits.
make lint/markdown(markdownlint-cli2) processes every Markdown file here. The repo-rootpackage.jsoninvokesmarkdownlint-cli2 --fix $(find docs -name '*.md').make fmt/markdown(markdown-table-formatter) reflows tables here for the same reason.- Vale (
make lint/prose) lints everything here except the style guide's own prose understyle-guide/: the landing page,content-guidelines.md, the annotation demo (whoseCoder.Demo*rules are meant to fire), and the Coder rule docs. Refer to the repo-root.vale.inifor the active configuration, and to "What does not run against this directory" below for the one exemption.
linkspector: excluded viaexcludedDirsin.github/.linkspector.yml. External-link checking is overkill for contributor tooling.- The
deploy-docsworkflow: itspaths:filter negatesdocs/.style/**, and the surgical-reindex git-diff invocation excludes the same path. See.github/workflows/deploy-docs.yaml. - The
docs-previewworkflow: itspaths:filter negatesdocs/.style/**, so.style-only PRs produce no preview comment. The selection logic also skips.stylefiles when picking the preview target on mixed PRs. See.github/workflows/docs-preview.yaml. - Vale's
Coderrules on the style guide's own prose underdocs/.style/style-guide/. The guide deliberately contains the constructs the rules ban, such as Don't examples and banned terms named in headings and prose, so the repo-root.vale.iniclearsBasedOnStylesfordocs/.style/style-guide/**. Nothing else underdocs/.style/is exempt: the landing page,content-guidelines.md, the annotation demo, and the Coder rule docs are all linted. Zero-baseline is therefore measured overdocs/excludingdocs/.style/style-guide/. The exemption applies only when the path resolves todocs/.style/style-guide/...from the working directory, which is whatmake lint/proseand continuous integration (CI) pass (repo-root-relativedocs/...). Other invocation forms bypass the glob and still flag the guide's intentional examples: absolute paths (what editors and Language Server Protocol (LSP) integrations pass) and subdirectory-relative paths (for examplevale .style/style-guide/...run fromdocs/). Treat those in-editor and subdirectory findings on the guide as expected.
Open a PR against docs/.style/content-guidelines.md.
The rules in that file apply to humans and AI-assisted workflows alike.
When it conflicts with another style or contributing doc in the repo, it governs.
Open a PR against the appropriate subpage of docs/.style/style-guide/.
Follow-up PRs add each rule and the matching style-guide section together.
The doc-check skill reviews docs changes through several personas, each focused on one kind of problem, such as accuracy or word choice.
Each rule page lists the personas that apply its rules in a review-personas front matter field:
---
review-personas: [language, consistency, accuracy]
---The skill finds a persona's rules by reading this field, not by file path, so pages can move or split without breaking the review.
When you add a rule page, add the field.
When you move a rule to a different page, check that the new page lists every persona that applied it.
The persona IDs and what each one reviews are in .claude/skills/doc-check/personas/.
The CI review of a PR runs only the accuracy, coverage, and learner personas, so it applies only the rule pages that list one of them.
The other personas run when an author uses the skill on their own branch.
Each rule in the repo-root .vale.ini at warning or error severity ships clean: zero baseline findings against the current docs/ corpus, excluding docs/.style/style-guide/, which is exempt because the style guide demonstrates the violations the rules ban.
A suggestion rule can ship with existing findings, as the severity notes below describe.
The PR that adds a rule is the rule's complete unit:
-
Cleanup commit: fix every existing-content violation of the new rule so
make lint/prosereports zero findings for it.The cleanup ships in the same PR as the enable, ordered first. For a
suggestionrule, the cleanup is optional. -
Enable commit: enable the rule in
.vale.ini, document it in the style guide, and add its YAML if applicable.Set the rule's chosen severity in
.vale.ini. Write a corresponding section under the matching subpage ofdocs/.style/style-guide/, and add the custom rule YAML underdocs/.style/styles/Coder/. The rule'smessage:field points at the relevant style-guide subpage anchor. Update the coverage tables onstyle-guide/README.mdin the same commit.make lint/style-claimsfails when a rule lands without its section, when the tables disagree with.vale.ini, or when an annotation claims enforcement that doesn't exist. Refer toscripts/styleclaims/README.mdfor the annotation format the checker reads, including how to mark a planned rule.
Severity is a deliberate per-rule choice:
errorblocks merge. Use for hard policy where any violation is wrong: brand-name casing, first-person pronouns we ban outright, em-dash bans.warningsurfaces an annotation without failing CI. Use for strong guidance with legitimate human-judgment exceptions: terms that need context (disabledas a technical state vs. ableist usage), judgment-bound style preferences.suggestionsurfaces anoticeannotation. Use for soft guidance where the right fix is contextual: noun-as-adjective patterns likedesired state, wordiness, optional sentence reshaping.
The severity choice and the cleanup discipline are independent, with one exception.
A rule landing at warning or error ships with zero baseline findings.
The rule's purpose is to catch new violations, not to surface a backlog of existing ones.
A rule that surfaces a standing backlog at those severities teaches contributors to ignore the annotation channel, which erodes trust in CI regardless of the severity at which the noise arrives.
A rule at suggestion severity can land while existing findings remain.
A suggestion is a soft nudge that a writer can accept or ignore, so a standing count doesn't mean the docs break a rule.
The PR that adds a suggestion rule states its baseline count, and it can fix existing findings in the same PR.
PR title: feat(docs/.style): enable <RuleName>.
False-positive policy: one confirmed false positive after enable, either refine the rule or revert. We do not maintain rules that occasionally cry wolf, regardless of severity.
If a policy is judgment-bound (passive voice, weasel words, sentence-case headings on a corpus with many proper nouns), write a Coder-authored rule with the precision the situation needs instead of accepting an imprecise third-party rule at any severity.
This applies equally to Coder-authored rules (under docs/.style/styles/Coder/) and third-party rules from Google, alex, and write-good.
Third-party rules are not loaded by default.
Each returns through the same per-rule PR pattern after its corpus is clean.