mirror of https://github.com/coder/coder.git synced 2026-09-24 15:04:27 +08:00

Files

T

Nick Vigilante 182bdc871a docs: scaffold docs/.style for the prose style guide (#25466 )

Adds a private contributor-tooling directory at `docs/.style/` that will
host the canonical prose style guide and the custom Vale rules used to
enforce it. The directory's contents do not deploy to `coder.com/docs`.

This PR is the scaffold only. The Vale configuration, the rule set, and
the per-rule style-guide sections all land in follow-up PRs.

## What changes

- New `docs/.style/` directory with:
- `README.md` explaining the convention
- `style-guide.md` as a table-of-contents scaffold
- `styles/Coder/README.md` placeholder so Git tracks the empty Vale
rules dir
- `.github/workflows/deploy-docs.yaml`: skip the workflow on
`.style`-only pushes, and exclude `.style` paths from the
surgical-reindex git diff on mixed commits. Defense-in-depth on top of
the manifest-driven coder.com routing.
- `.github/.linkspector.yml`: add `docs/.style` to `excludedDirs`
- `AGENTS.md` and `.claude/docs/DOCS_STYLE_GUIDE.md`: cross-link to the
new style guide for agents

## Verification

- `make pre-commit-light` clean (`fmt/markdown`, `lint/markdown`,
`lint/typos`, `lint/emdash`, `lint/actions/actionlint`,
`lint/shellcheck`).
- `markdown-table-formatter --check` and `markdownlint-cli2` both
process the new files (existing globs are `find docs -name '*.md'`).
- `actionlint` clean on the modified workflow.
- coder.com exclusion works because route discovery and Algolia indexing
are manifest-driven; this directory is not in `docs/manifest.json`. The
workflow changes are defense in depth.

<details>
<summary>Implementation plan and decision log</summary>

### Decisions

- **Location**: `docs/.style/` (leading dot, mirrors `.github/`,
`.vscode/`, `.claude/`). Vale's `StylesPath` will be
`docs/.style/styles/`; `.vale.ini` lands at repo root in a follow-up.
- **Existing public page `docs/about/contributing/documentation.md`**:
untouched in this PR. Nick's separate information-architecture rework
will redirect it to GitHub at the right time.
- **Placeholder for empty `styles/Coder/`**: real `README.md`, not
`.gitkeep`. Discoverable on GitHub, lints with the existing tooling,
lists the planned starter rules.
- **CONTRIBUTING.md**: not touched. It's a 2-line redirect to
`coder.com/docs/CONTRIBUTING`; bloating it would defeat the redirect.
- **`.claude/docs/DOCS_STYLE_GUIDE.md`**: kept as the structure/research
companion. A blockquote at the top points at the new canonical prose
guide.

### coder.com exclusion mechanism (verified by inspection)

Direct inspection of `coder/coder.com`:

- Route discovery in
[`src/utils/docs/docs.ts`](https://github.com/coder/coder.com/blob/master/src/utils/docs/docs.ts)
iterates `routes` from `docs/manifest.json`. Files not in the manifest
never become routes.
- The Algolia surgical indexer at
[`src/utils/algoliaDocs/surgical.ts`](https://github.com/coder/coder.com/blob/master/src/utils/algoliaDocs/surgical.ts)
explicitly skips paths not in the manifest, incrementing `pathsSkipped`.

Net result: not adding anything from `docs/.style/` to `manifest.json`
is the only thing that has to be true for the exclusion to work. The
`deploy-docs.yaml` tweaks are defense in depth.

### deploy-docs.yaml changes (pre-mortem)

1. Trigger path negation `!docs/.style/**` skips the workflow on
`.style`-only pushes. GitHub Actions only suppresses when every changed
file matches a negation, so mixed commits still trigger.
2. The git-diff pathspec `:(exclude)docs/.style/**` drops `.style` paths
from the surgical-reindex payload on mixed commits.

Risks considered:

- **Test contract**: `.github/workflows/test-deploy-docs-diff.sh` only
exercises the downstream awk parser, not the git-diff invocation. The
exclusion happens at git-diff time; the parser sees the same
`<status>\0<path>\0` format. No test change needed.
- **First push to a brand-new branch**: the workflow falls back to
whole-branch reindex when `BEFORE_SHA` is all zeros. Whole-branch
reindex re-extracts records from the manifest, which still excludes
`.style` files because they are not in the manifest.
- **Workflow-dispatch**: takes the whole-branch path; same reasoning.
Safe.

### Why a real README in `styles/Coder/` instead of `.gitkeep`

It explains intent, lists the upcoming rules, and lints with the
existing tooling. The cost is one extra Markdown file; the upside is
that a contributor browsing GitHub sees the plan without clicking
around.

</details>

---

*Filed via [Coder Agents](https://coder.com/docs/ai-coder/agents) on
Nick's behalf.*

Linear: DOCS-180

2026-06-17 13:19:37 +00:00

styles/Coder

docs: scaffold docs/.style for the prose style guide (#25466 )

2026-06-17 13:19:37 +00:00

content-guidelines.md

docs: add canonical content guidelines, close doc-check SKILL gaps (DOCS-332) (#26352 )

2026-06-12 18:38:49 -04:00

README.md

docs: scaffold docs/.style for the prose style guide (#25466 )

2026-06-17 13:19:37 +00:00

style-guide.md

docs: scaffold docs/.style for the prose style guide (#25466 )

2026-06-17 13:19:37 +00:00

README.md

`docs/.style/`

Contributor-facing style and content guidance for the Coder documentation. Nothing under this directory is published to coder.com/docs.

What lives here

Path	Purpose
`content-guidelines.md`	Canonical content rules: what belongs in `docs/`, what doesn't, why
`style-guide.md`	Canonical prose style guide for `docs/`
`styles/Coder/`	Custom Vale rules specific to Coder (product voice, terms)

See content-guidelines.md for the canonical rules on what content belongs in docs/ and what should be routed elsewhere (blog, changelog, Support KB, etc.).

See style-guide.md 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 (added in a follow-up PR) 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. Vale and the structural Markdown linters still pick it up; coder.com's docs site does not.

How exclusion from coder.com works

coder.com/docs routes and search are manifest-driven:

Route discovery lives in coder/coder.com:src/utils/docs/docs.ts (getDocsStaticPaths). It iterates routes from docs/manifest.json and 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.ts explicitly skips paths that are not in the manifest, incrementing pathsSkipped.

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.

What still runs against this directory

make lint/markdown (markdownlint-cli2) processes every Markdown file here. The repo-root package.json invokes markdownlint-cli2 --fix $(find docs -name '*.md').
make fmt/markdown (markdown-table-formatter) reflows tables here for the same reason.
Vale, once .vale.ini lands in a follow-up PR, lints the entire docs/**/*.md set including docs/.style/style-guide.md.

What does not run against this directory

linkspector: excluded via excludedDirs in .github/.linkspector.yml. External-link checking is overkill for contributor tooling.
The deploy-docs workflow: its paths: filter negates docs/.style/**, and the surgical-reindex git-diff invocation excludes the same path. See .github/workflows/deploy-docs.yaml.
The docs-preview workflow: its paths: filter negates docs/.style/**, so .style-only PRs produce no preview comment. The selection logic also skips .style files when picking the preview target on mixed PRs. See .github/workflows/docs-preview.yaml.

Editing the content guidelines

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.

Editing the style guide

Open a PR against docs/.style/style-guide.md. Follow-up PRs add each rule and the matching style-guide section together.