Commit Graph
9 Commits
Author SHA1 Message Date
Nick Vigilante 16551fd67f feat: enable Coder.AbbreviationFirstUse (#30878)
Adds `Coder.AbbreviationFirstUse`, a Vale rule that requires each
abbreviation to be expanded on its first use on a page, in the form
"Expanded Form (ABBR)". It supports [WCAG 2.2 Level AAA Success
Criterion 3.1.4
(Abbreviations)](https://www.w3.org/TR/WCAG22/#abbreviations). Following
the "Adding a Vale rule" pattern in `docs/.style/README.md`, the PR has
two commits: the cleanup first, then the enable.

## Cleanup commit

431 first uses expanded across 167 pages, so the rule ships with zero
findings across `docs/`, excluding `docs/.style/style-guide/`. The
branch was rebuilt on current `main`, so pages added or moved since the
first draft are covered.

- Where the first use is a bold UI label (**CA Path**, **Add redirect
URI**, **Redirect URI**), the label stays as the UI shows it and the
expansion goes elsewhere in the same paragraph or list item.
- Reversed forms such as "PKCE (Proof Key for Code Exchange)" are
flipped to the expanded-first form.
- A few sentences took a small rewording to fit the expansion: list
steps that would pass the 20-word limit (`Coder.StepLength`), and spots
where the expansion would nest parentheses.
- MITM is expanded as "machine-in-the-middle" rather than
"man-in-the-middle". Every use describes the AI Gateway Proxy
intercepting traffic on purpose, so "on-path attacker" doesn't fit. The
inclusive-language table on `accessibility-and-inclusion.md` gains the
substitution: "on-path attacker" for the attack, "machine-in-the-middle"
for the feature.
- Unrelated fixes on lines already being edited: `DERP MAP` → `DERP
map`, and `ENV` → "environment variable" in `faqs.md`.

## Enable commit

**Rule design.** The rule is a `conditional`. `first` matches 2 to 6
capitals, each optionally followed by digits (`EC2`, `P2P`), and a
lookahead lets a plural `s` count as a use of the singular. `second`
captures the abbreviation in `word (ABBR)`, including `(CI/CD)` and
`(PCI DSS)` pairs. Vale collects the captures across the page's blocks
in document order, so a later expansion doesn't cover an earlier use.
Within a single paragraph, list item, or table cell, an expansion
anywhere in the block counts.

**Scope.** `scope: ~heading` skips headings, because a page title often
names an abbreviation that the first paragraph then expands. Vale
already skips front matter, code blocks, inline code, and link URLs.
`.vale.ini` turns the rule off for the pages generated from Go source
that `Coder.UnitSpacing` already skips: `docs/reference/{api,cli}/*.md`,
`configuration-reference.md`, and `prometheus.md`.

**Severity: `warning`.** Whether an abbreviation is familiar enough to
skip is a judgment call, so this is guidance with legitimate exceptions,
not hard policy.

**Exceptions**, each group commented in the rule file:

| Group | Entries | Reason |
| --- | --- | --- |
| Known to every reader | AI, API, AWS, CLI, CPU, DNS, GCP, HTTP(S), ID,
IDE, IP, JSON, OS, PR, RAM, SDK, SQL, SSH, TLS, UI, URL, VM, YAML |
Abbreviations every reader of the docs knows. Plurals such as VMs and
SDKs pass too |
| Units, clock times, file and package formats | GB, KB, MB, AM, PM,
CSV, GIF, JPEG, PDF, PNG, RPM, SVG, VSIX, ZIP | Readers know these by
the abbreviation, not the expansion |
| Not abbreviations | NOTE, TIP, OK, README, SKILL, ALL, AND, ANY,
ERROR, MUST, NOT, ON, OR, DELETE, GET, POST, PUT, ILIKE, VACUUM, LOGIN,
PLAIN, NUL, CRON, TERM, DOCS, `DOC\d+`, `RFC\d+`, TL, DR | Alert labels,
file names, emphasis in capitals, HTTP methods, SQL keywords, SMTP auth
mechanisms, rule labels in `docs/AGENTS.md`, RFC numbers, TL;DR |
| Names written in capitals | VS, IDEA, IU, NGINX, SUSE, GNU, XFCE, DX,
IBM, DCV, TRAMP, MSYS2, NET, VSX, ARM, AMD, GPT, AES, GCM, HMAC, HS256,
RSA, SHA, SHA256 | The capitals are the product, company, or algorithm
name (VS Code, IntelliJ IDEA, .NET, Open VSX, Amazon DCV, AMD) |

The "known to every reader" group is the list that needs judgment, and
it's the one to push back on. The other groups only stop the regex from
treating words and names as abbreviations.

**Documentation.** A new "Expand abbreviations on first use" section on
`accessibility-and-inclusion.md`, and the style guide README's checks
table, coverage table, and rule counts (90 → 91 rules, 22 → 23
tool-checked).

## Known limits

- The rule checks that an expansion exists, not that it's correct: any
word followed by `(ABBR)` satisfies it.
- An abbreviation in an image's alt text is checked before the paragraph
around it, so one alt text (`aws-marketplace.md`) carries its own
expansion.
- Some expansions read heavily in dense table cells and inline lists,
for example the four Kubernetes services in `docker-in-workspaces.md`.
They're correct, but a reviewer may prefer adding a specific
abbreviation to the exceptions instead.

## Testing

- `vale docs/` (Vale 3.7.1 through mise): zero
`Coder.AbbreviationFirstUse` findings. Findings from every other rule
match `main` file for file.
- `pnpm run format-docs`, `pnpm run lint-docs`,
`scripts/check_emdash.sh`, and `make lint/prose` run clean, and the
repository pre-commit hooks (including `lint/style-claims`) pass on both
commits.

Linear: DOCS-1311

Generated by Coder Agents on behalf of @nickvigilante.
2026-11-02 14:41:15 -05:00
Nick Vigilante 81c40579dc feat: enable Coder.StepLength Vale rule (#30791)
Adds `Coder.StepLength`, a Vale `script` rule for [Keep steps
short](https://github.com/coder/coder/blob/main/docs/.style/style-guide/procedural-writing.md#keep-steps-short).
It flags an ordered-list step whose instruction, the step's first
paragraph, has more than 20 words, counted as [How to count
words](https://github.com/coder/coder/blob/main/docs/.style/style-guide/voice-and-tone.md#how-to-count-words)
describes.
Paragraphs below the instruction explain the step and aren't counted.

- Severity: `warning`.
- Scope: `docs/**` except `docs/.style/style-guide/**`.
- Baseline: 124 findings in 60 hand-written files.
The cleanup shortens each long instruction, moves its explanation into
one paragraph below it, or splits a step that holds several actions.
After cleanup `vale docs/` reports 0 `Coder.StepLength` findings, and
the other rules report no new findings on the changed files.
- The guide section now says the limit covers the instruction, and that
one action or one explanation must not be broken across paragraphs to
meet it.
- Generated pages (`docs/reference/{api,cli,agent-api}`,
`configuration-reference.md`, `prometheus.md`): no findings, so no
`.vale.ini` exclusion is needed.

Linear: DOCS-1272

<details><summary>Decision log</summary>

**Review change (Ian's review)**

- The first version limited every paragraph of a step to 20 words.
The cleanup for it chopped explanations into several short paragraphs,
which made steps harder to read and sometimes changed their meaning.
- The rule now counts only the first paragraph segment of each step.
The content files were reset to `main` and the cleanup was redone
against the narrower rule.
- Cleanup preferences, in order: shorten the instruction; keep a short
instruction and put the explanation, with its original wording, in one
paragraph below it; split a step into one step for each action; for
descriptive lists (such as "How it works"), keep each item one
statement.
- `docs/admin/users/oidc-auth/microsoft.md` keeps the split into
separate steps, with Ian's wording suggestions applied.
"click" became "select" in step 16 because `Coder.SelectClick` flags it.

**Rule shape**

- A `script` rule (Tengo) with `scope: raw`, because the count depends
on Markdown structure that per-paragraph scopes hide.
- A step is an ordered-list item with a `1.` or `1)` marker.
  A nested ordered item is its own step.
  Bullets, even under a step, are not steps.
- The instruction ends at a blank line, a fence, a nested list, a table
row, a blockquote, block-level HTML, or an explicit hard break (`<br>`,
a trailing backslash, or two trailing spaces).
- Fenced code blocks, HTML comments, tables, images, and nested bullets
add no words.
- CRLF: `\r` counts as whitespace, and offsets come from the raw text.

**Counting approximations (also in the rule header)**

- A code span and a `**bold**` or `__bold__` span are one word each.
- Words split on whitespace, so a hyphenated compound and
`30&nbsp;seconds` are one word.
- Link text counts word by word, destinations are skipped, images add no
words, and `<https://...>` autolinks are one word.
- A token with no letter or digit, such as the `>` in `**A** > **B**`,
is not a word.
- Tengo indexes strings by rune but measures them in bytes, so the
script rewrites each non-ASCII rune to ASCII of the same byte length
first.

**Tests** (fixtures under `/tmp/sltest/`, not committed; run with the
repo `.vale.ini`, LF and CRLF)

- Flagged: a long instruction, a short action and a long result in one
paragraph, a long nested ordered step.
- Not flagged: a long paragraph below a short instruction, text after a
`<br>` hard break, a long paragraph after a code block, a long nested
bullet.
- LF and CRLF output is identical.
- Pre-commit hooks (`fmt/markdown`, `lint/markdown`, `lint/emdash`,
`lint/style-claims`, `lint/typos`) pass.
- Not run on Windows or macOS.
The rule is plain text processing, and the CRLF cases simulate Windows
line endings on Linux.

</details>

*Generated by [Coder Agents](https://coder.com/docs/ai-coder/agents) on
behalf of @nickvigilante.*
2026-10-26 20:43:38 -04:00
Nick Vigilante c58ac71ca3 docs(docs/tutorials): reformat to one sentence per line (#30703)
Reformats the tutorials under `docs/tutorials` to one sentence per line,
as the [docs style
guide](https://github.com/coder/coder/blob/main/docs/.style/style-guide/formatting.md#one-sentence-per-line)
requires. Hard-wrapped paragraphs are unwrapped and lines holding
several sentences are split, so a later edit to one sentence shows up as
a one-line diff.

Apart from the exception below, only whitespace inside paragraphs and
list items changes, and the rendered pages are the same. Comparing the
changed files against `main` word for word, ignoring whitespace and
blockquote `>` markers, finds differences only on the reworded lines.
`git diff --word-diff` is easier to read than the line diff.

9 lines that already contained an em or en dash were reworded by hand,
because `lint/emdash` treats every reflowed line as newly added. Each
uses a parenthetical, a separate sentence, or a colon after a lead-in.
Dashes on lines the reflow did not touch are left alone. The two reverse
proxy tutorials also write `*.coder.example.com` in backticks instead of
escaping the asterisk, which the formatter would otherwise drop.

Applied with an in-progress formatter, limited to pages listed in
`docs/manifest.json` and excluding generated reference docs. This is one
of a batch of PRs that split the docs by area (19 files changed, 656
insertions(+), 1265 deletions(-)).

---
🤖 Built with AI assistance.
2026-10-15 11:24:40 -04:00
Nick Vigilante 7846490770 docs: reconcile H1/label mismatches into front-matter titles (Phase 3) (#28036)
## Summary

**Batch B of Phase 3** of the H1 → front-matter migration (`DOCS-484`;
parent `DOCS-477`), the editorial follow-up to Batch A (#28030). For the
**124** hand-authored pages whose leading body H1 differed from the
manifest nav label, this promotes the richer body H1 to the front-matter
**page title** and drops the duplicate H1, while keeping the short
manifest **label** as the sidebar entry.

Policy agreed with the docs owner:
- Short sidebar labels win. Duplicate sidebar labels are acceptable.
- Identical **page titles** across two pages are not. On a collision,
rename the non-generated page's title.

## Page-title collisions resolved

Promoting the H1 created 4 page-title collisions; each is disambiguated
by renaming the non-generated / secondary page (sidebar labels left
unchanged):

| page | sidebar label | body H1 | → page title |
|------|---------------|---------|--------------|
| `install/index.md` | Install | Installing Coder | **Install Coder in
your infrastructure** |
| `install/cli.md` | Coder CLI | Installing Coder | **Install the Coder
CLI** |
| `ai-gateway/clients/jetbrains.md` | JetBrains | JetBrains IDEs |
**JetBrains** |
| `workspace-access/web-ides.md` | Web IDEs and Coder Apps | Web IDEs |
Web IDEs *(kept — primary user guide)* |
| `extending-templates/web-ides.md` | Web IDEs and Coder Apps | Web IDEs
| **Web IDEs in templates** |
| `workspace-management.md` | Workspace Management | Workspaces |
**Manage workspaces** *(vs generated `api/workspaces.md`)* |

These titles are the only non-mechanical editorial calls in this PR.

## Deliberately excluded: generated pages

`admin/security/audit-logs.md` and
`admin/setup/configuration-reference.md` are `make gen` outputs
(`auditdocgen` / `configdocgen`) that Phase 2 did **not** update, so a
hand-added title would be reverted on the next generation. They're
excluded here and need their generators taught to emit front matter
first (Phase 2 pattern), tracked as `DOCS-631`. Batch A (#28030) had the
same issue for three other generated pages; it has been corrected there
too.

## Verification

AI was the primary author of this PR (see disclosure below); per the [AI
Contribution
Guidelines](https://coder.com/docs/about/contributing/AI_CONTRIBUTING)
here is the manual verification.

- Promote = set front-matter `title` to the body H1 (or the
disambiguated title above) and remove that one duplicate H1. No other
body prose is reflowed.
- Every added front-matter block parses as YAML; all files pass `pnpm
check-docs` (markdownlint-cli2 + table formatter): `Summary: 0
error(s)`.
- Removing the H1 orphaned one in-page fragment (`[MCP](#mcp)` in
`ai-gateway/mcp.md`), now repointed. A cross-file fragment audit into
the retitled pages found no real breakage.


Anchor-change note

Unlike Batch A (title unchanged, a rendered no-op), Batch B changes each
page's effective title from the manifest label to the body H1, so the
rendered H1 **anchor slug changes**. An audit of cross-file
`.md#fragment` links into these pages surfaced no links that break as a
result (the only hits were false positives against a still-present `##
TLS & Reverse Proxy` heading). Same-file fragments are enforced by
markdownlint MD051, which is green.

## Title casing (follow-up, DOCS-742)

A follow-up commit puts the promoted titles into sentence case and
removes leading gerunds (for example, `Managing workspace schedules` →
`Manage workspace schedules`): 57 of the 120 titles changed, the other
63 were already compliant. Proper nouns and branded names (Coder
Validated Architecture, JetBrains, File Browser, Dev Containers,
Island), acronyms (API, CLI, IDE, MCP, OIDC, URL, UI, CI/CD), the
Premium license tier, and maturity labels (Beta, Experimental) are
preserved. The four `Nk-users` pages become `Reference architecture: up
to N users` (lowercase, matching the CVA landing page's own usage); the
CVA landing page keeps its branded title. `pnpm check-docs`: `Summary: 0
error(s)`.

Linear: DOCS-484, DOCS-742

> This PR was created with AI assistance (Coder Agents).
2026-09-08 16:34:00 +00:00
Nick Vigilante c84aa564ba docs: normalize code-fence languages for Shiki compatibility (#27161)
Normalizes non-standard code-fence language tags across `docs/**` so a
strict highlighter (Shiki, used by Fumadocs) won't fail the build on an
unrecognized language, and unifies redundant synonym tags onto one
canonical form per language. The current renderer (Speed-Highlight)
detects the language from the code content, not the fence label, so this
drift wasn't visible until now.

## Changes

- `hcl` -> `tf` (199 fences, including indented ones nested in
numbered/bulleted lists). Shiki ships `hcl` and `terraform` as two
distinct grammars (not aliases); every `hcl`-tagged fence in `docs/**`
is actually Terraform resource/data/provider syntax, so the more
specific `terraform` grammar is correct for all of them. `tf` is Shiki's
own alias for that grammar, and it's also what GitHub's own markdown
renderer resolves to the same HCL/Terraform highlighting.
- `pwsh`/`powershell` -> `ps1`. Both `ps` and `ps1` are registered
PowerShell aliases in Shiki, but on GitHub's renderer only `.ps1` is a
registered file extension (`.ps` isn't), so `ps1` renders identically to
`powershell` there today while bare `ps` would silently lose
highlighting.
- `env` -> `dotenv` (a dedicated Shiki grammar for `KEY=VALUE` files)
- `text`/`output`/`none`/`url` -> `txt`. Same built-in plain-text
fallback either way, just shorter.
- `Dockerfile` -> `dockerfile` (lowercase)
- `bash`/`shell` -> `sh` (732 fences). Shiki and GitHub both alias all
three to a single shell grammar; this was already the style guide's
stated preference, just not enforced across the existing corpus until
now.
- `markdown` -> `md` (4 fences). Alias of the same grammar in both Shiki
and GitHub.
- `jsonc` -> `json` (1 fence). The block has no comments or trailing
commas, so it doesn't need the comments-capable grammar.
- `ts` -> `tsx` (2 fences, `docs/about/contributing/frontend.md`).
Verified the actual content tokenizes identically under both grammars,
and a sibling block in the same file already needs `tsx` for real JSX,
so unifying to one tag is safe for this file. Documented a caveat: `tsx`
mis-tokenizes the legacy angle-bracket type-assertion syntax
(`<Type>value`), which is invalid in real `.tsx` files anyway, so use
`value as Type` instead.
- `yml` -> `yaml` (1 fence)
- Updated `docs/.style/style-guide/formatting.md` to document all
canonical tags

`promql` (2 fences) and `caddyfile` (2 fences) are left as-is. Shiki
doesn't bundle a grammar for either, so they need a custom grammar
registration when the site adopts Shiki, rather than degrading to `txt`.
Tracked as follow-up work under DOCS-118 and
[DOCS-544](https://linear.app/codercom/issue/DOCS-544/vendor-a-local-promql-grammar-for-shiki-syntax-highlighting)
(promql).

Does not touch `offlinedocs/`.

Linear:
[DOCS-476](https://linear.app/codercom/issue/DOCS-476/normalize-docs-code-fence-languages-de-risk-shikifumadocs)

<details>
<summary>How the fence tags were verified</summary>

Each tag was tested against a real `shiki@latest` highlighter instance
(`codeToHtml`/`codeToTokens`) and cross-checked against GitHub's
`@wooorm/starry-night` grammar sources (the renderer that actually
displays these `.md` files today, in repo browsing and PR diffs), since
that's what determines whether brevity is safe before Shiki adoption:

```text
FAIL  env        -- Language `env` is not included in this bundle.
FAIL  Dockerfile -- Language `Dockerfile` is not included in this bundle.
FAIL  promql     -- Language `promql` is not included in this bundle.
FAIL  caddyfile  -- Language `caddyfile` is not included in this bundle.
FAIL  pwsh       -- Language `pwsh` is not included in this bundle.
FAIL  output     -- Language `output` is not included in this bundle.
```

`hcl` doesn't error in Shiki, since it's a real grammar, but that's
exactly the trap: it was silently rendering every fence with the generic
HCL grammar instead of the Terraform-specific one. Every `hcl`-tagged
fence in `docs/**` was manually checked against `origin/main` and is
genuinely Terraform content.

For `ts`/`tsx`, tokenizing the actual doc content confirmed identical
output under both grammars; a synthetic test with the legacy
angle-bracket cast syntax confirmed `tsx` degrades on that specific
construct, which the style guide now calls out.

The first normalization pass only matched fence tags at column 0
(`^```tag$`), missing tags indented inside numbered/bulleted lists. A
follow-up pass caught the remaining occurrences at any indentation
level.

</details>


---

*This PR description and the underlying changes were prepared with Coder
Agents assistance.*
2026-07-15 14:07:09 -04:00
Edward AngertandEdwardAngert f4600652c3 docs: remove github avatars (#18338)
the site is making the pictures big, so I'm just removing them in this
PR and then maybe we can investigate it some other time

- [live site](https://coder.com/docs/admin/integrations/island)
-
[preview](https://coder.com/docs/@remove-github-avatars/admin/integrations/island)

cc @aqandrew 

#bring-back-the-hotfix-label

Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
2025-06-12 00:52:21 +00:00
101b62dc3e docs: convert alerts to use GitHub Flavored Markdown (GFM) (#16850)
followup to #16761 

thanks @lucasmelin !

+ thanks: @ethanndickson @Parkreiner @matifali @aqandrew 

- [x] update snippet
- [x] find/replace
- [x] spot-check


[preview](https://coder.com/docs/@16761-gfm-callouts/admin/templates/managing-templates/schedule)
(and others)

---------

Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Co-authored-by: M Atif Ali <atif@coder.com>
2025-03-10 16:58:20 -04:00
Muhammad Atif AliandEdward Angert 94f5d52fdc chore: adopt markdownlint and markdown-table-formatter for *.md (#15831)
Co-authored-by: Edward Angert <EdwardAngert@users.noreply.github.com>
2025-01-03 13:12:59 +00:00
419eba5fb6 docs: restructure docs (#14421)
Closes #13434 
Supersedes #14182

---------

Co-authored-by: Ethan <39577870+ethanndickson@users.noreply.github.com>
Co-authored-by: Ethan Dickson <ethan@coder.com>
Co-authored-by: Ben Potter <ben@coder.com>
Co-authored-by: Stephen Kirby <58410745+stirby@users.noreply.github.com>
Co-authored-by: Stephen Kirby <me@skirby.dev>
Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Co-authored-by: Edward Angert <EdwardAngert@users.noreply.github.com>
2024-10-05 10:52:04 -05:00