mirror of
https://github.com/coder/coder.git
synced 2026-11-22 11:28:40 +08:00
feea5ab959f59cd2135443ed2a0c19bf7643db8f
6
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
d91aa1bebd |
docs: replace may with can or might per the Vale spike review (#31878)
Replaces `may` with `can` (ability or permission) or `might` (possibility), following `word-choice.md#choose-words-that-have-one-meaning`. The Vale findings spike review marked every `may` row valid. - 247 lines in 110 files: 75 became `can` and 162 became `might`. The rest are small rewordings, such as "may wish" becoming "might want". - Applied the reviewer notes: - `.style/content-guidelines.md`: "docs may be written ahead" is now "you can write docs ahead", which also drops the passive voice. - `admin/external-auth.md`: now "You can grant access to a subset of repositories.", so the sentence doesn't end on a preposition. - Also fixed a typo in `gcp-to-aws.md`: "may needed" is now "might need". ## Left as-is - **`admin/setup/configuration-reference.md` (7 lines):** this page is generated from `codersdk` deployment options (`<!-- DO NOT EDIT | GENERATED CONTENT -->`), so the fix belongs in the Go option descriptions, followed by `make gen`. - **Text that quotes the product:** - `admin/monitoring/health-check.md:196` matches the derphealth message. - The heading at `templates/troubleshooting.md:45`, the first "may" on line 47, and the link on line 67 match the web terminal's "your workspace may be incomplete" warning and its anchor. - `admin/integrations/oauth2-provider/troubleshooting.md:269` quotes a server error. The changed files have no new findings from other rules. --- AI-generated by Superblink on behalf of @nickvigilante. --------- Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com> |
||
|
|
f97eee3c49 |
docs: redistribute tutorials and rename top-level sidebar sections (#31647)
> [!NOTE] > Generated by Coder Agents. The branch and this description were written by an AI agent and need human review. ## Summary Third of three stacked PRs for the docs IA overhaul (Proposal 1, sections 1 and 4). This PR dissolves Tutorials and finishes the top-level nav. - **Tutorials redistribution.** Every remaining `docs/tutorials/` page moves to the section it belongs to (`git mv`, table below). The `tutorials/index.md` and `tutorials/best-practices/index.md` hub pages are deleted, so `docs/tutorials/` no longer exists. That matters for the folder-driven beta renderer: no stray "Tutorials" group is left. `example-guide.md` was already deleted on `main` in #30711. - **Duplicate Tutorials entries are dropped.** Each of these pages stays in the sidebar at its real location: Quickstart, Image management, JFrog Artifactory, Island browser integration, Deploy Coder on Azure with an Application Gateway, Pre-install JetBrains IDEs, and JetBrains IDEs air-gapped. Scale Coder was also a duplicate, already listed under Install > Validate > Scale testing, and it stays there. - **Istio** (`admin/integrations/istio.md`) gets its sidebar entry under Administration > Integrations, after Island. Before this PR, only Tutorials linked to it. - **Nav renames.** - About becomes **Home**, with no children; `about.yml` is renamed `home.yml`. A third commit, `docs: title the docs landing page Home`, changes the `docs/README.md` front matter title from About to Home and deletes the stale HTML comment that said the first section must be titled About. - Quickstart becomes **Get started**. - User guides becomes **Workspaces**. - **Support** (with Support bundle) becomes a top-level section and goes last; `about/support.yml` moves to `support.yml`. - **Screenshots.** Nothing to do here: #31465 already deleted `about/screenshots.md` on `main` and added its redirect. - **Final top-level order:** Home, Get started, Install, Templates, Workspaces, Coder Agents, AI Governance, Agent Relay, MCP server, Administration, Reference, Support. - Commit 2, `chore: point in-product docs links at the new docs paths`, makes two edits outside `docs/`. You can drop it. - `README.md`: the `docs/about#why-coder` link now points to `docs#why-coder`. - `cli/server.go`: the built-in PostgreSQL error message now links to `install/server/external-database`. - The last commit, `fix: keep docs links healthy before the release`, reverts both of those back to the URLs that are live today (`https://coder.com/docs/about#why-coder` and `https://coder.com/docs/tutorials/external-database`). Both are hardcoded, unversioned `https://coder.com/docs/...` URLs, and the new paths 404 on the live site until a release that includes this stack becomes the default. See "Post-release follow-up". No hand-written page in this PR's moves had an absolute `coder.com/docs` link to a moved page, so `docs/` needed no changes. Net, this PR changes nothing outside `docs/`. Stack: `docs/ia-ai-sections` (with Templates squash-merged in #31646) → **this PR** → `docs/ia-workspaces-folder` (folder rename). Refs: Linear DOCS-1154, DOCS-1179. ## Move map | Old | New | Sidebar position | | --- | --- | --- | | `tutorials/configuring-okta.md` | `admin/users/oidc-auth/configuring-okta.md` | Administration > Users > OpenID Connect (last) | | `tutorials/best-practices/organizations.md` | `admin/users/organizations-best-practices.md` | Administration > Users, after Organizations | | `tutorials/best-practices/security-best-practices.md` | `admin/security/security-best-practices.md` | Administration > Security (last) | | `tutorials/reverse-proxy-apache.md` | `admin/networking/reverse-proxy-apache.md` | Administration > Networking, before Troubleshooting | | `tutorials/reverse-proxy-caddy.md` | `admin/networking/reverse-proxy-caddy.md` | same | | `tutorials/reverse-proxy-nginx.md` | `admin/networking/reverse-proxy-nginx.md` | same | | `tutorials/gcp-to-aws.md` | `install/operate/gcp-to-aws.md` | Install > Operate, before Uninstall | | `tutorials/azure-federation.md` | `install/operate/azure-federation.md` | same | | `tutorials/image-pull-secret.md` | `install/operate/image-pull-secret.md` | same | | `tutorials/postgres-ssl.md` | `install/server/postgres-ssl.md` | Install > Install the control plane (last) | | `tutorials/external-database.md` | `install/server/external-database.md` | same (**deviation**, see below) | | `tutorials/best-practices/scale-coder.md` | `install/validate/scale-coder.md` | unchanged: Install > Validate > Scale testing | | `tutorials/faqs.md` | `reference/faqs.md` | Reference (last) | | `tutorials/persistent-shared-workspaces.md` | `user-guides/persistent-shared-workspaces.md` | Workspaces, after Shared workspaces | | `tutorials/cloning-git-repositories.md` | `user-guides/cloning-git-repositories.md` | Workspaces (end) | | `tutorials/best-practices/speed-up-templates.md` | `user-guides/speed-up-templates.md` | Workspaces (end) | | `tutorials/index.md` | deleted | | | `tutorials/best-practices/index.md` | deleted | | All paths are relative to `docs/`. Every relative link and image path is fixed, in moved pages and in pages that link to them, including the `github.com/coder/coder/edit/main/docs/...` link in the FAQ page and the link to the build timeline in `templates/extending-templates/script-ordering.md`, which is new on `main`. ## Redirects added | Source | Destination | | --- | --- | | `/docs/tutorials/azure-federation` | `/docs/install/operate/azure-federation` | | `/docs/tutorials/best-practices/organizations` | `/docs/admin/users/organizations-best-practices` | | `/docs/tutorials/best-practices/scale-coder` | `/docs/install/validate/scale-coder` | | `/docs/tutorials/best-practices/security-best-practices` | `/docs/admin/security/security-best-practices` | | `/docs/tutorials/best-practices/speed-up-templates` | `/docs/user-guides/speed-up-templates` | | `/docs/tutorials/cloning-git-repositories` | `/docs/user-guides/cloning-git-repositories` | | `/docs/tutorials/configuring-okta` | `/docs/admin/users/oidc-auth/configuring-okta` | | `/docs/tutorials/external-database` | `/docs/install/server/external-database` | | `/docs/tutorials/faqs` | `/docs/reference/faqs` | | `/docs/tutorials/gcp-to-aws` | `/docs/install/operate/gcp-to-aws` | | `/docs/tutorials/image-pull-secret` | `/docs/install/operate/image-pull-secret` | | `/docs/tutorials/persistent-shared-workspaces` | `/docs/user-guides/persistent-shared-workspaces` | | `/docs/tutorials/postgres-ssl` | `/docs/install/server/postgres-ssl` | | `/docs/tutorials/reverse-proxy-apache` | `/docs/admin/networking/reverse-proxy-apache` | | `/docs/tutorials/reverse-proxy-caddy` | `/docs/admin/networking/reverse-proxy-caddy` | | `/docs/tutorials/reverse-proxy-nginx` | `/docs/admin/networking/reverse-proxy-nginx` | | `/docs/tutorials/best-practices` | `/docs` (deleted hub, **please confirm**) | | `/docs/tutorials` | `/docs` (deleted hub, **please confirm**) | | `/docs/about` | `/docs` | Exact rules are used instead of a `/docs/tutorials/:path*` wildcard, because the pages went to many different sections. The `/docs/about` rule stays: classic coder.com adds the `/docs/about` alias only when the first section is titled About, so after the rename that URL needs the redirect. `/docs/about/screenshots` → `/docs` is already on `main` (#31465), so this PR doesn't add it. **coder.com and router static redirects:** a chain simulation of coder.com's and the router's static rules together with this branch's `docs/redirects.json` finds no loops or hidden pages from this PR. The static `/docs/tutorials/...` and `/docs/about` rules there still work; some now take two redirects. The only loops in the stack come from the Templates move; see #31645, coder/coder.com#1201, and coder/docs-engine#304. ## Deviations from the proposal - **`external-database.md` goes to `install/server/`, not `templates/`.** The page covers the control plane's PostgreSQL database, so it sits next to `postgres-ssl.md`. - **Dead links to the Tutorials hub.** - `admin/index.md` linked to "Tutorials and FAQs"; it now links to the FAQs only. - The style guide's link-wording examples in `docs/.style/style-guide/word-choice.md` linked "Quickstart" to `tutorials/index.md`; they now link to `get-started/index.md`. - **Support icon.** Top-level sections have icons, so Support gets `info.svg`. - **Home title.** Titling the first section Home was checked against both renderers. Classic coder.com renders `/docs` from its own landing component, and docs-engine maps `README.md` to the root page and already titles it Home. `docs/README.md` stays in place, because classic serves `/docs.md` from it and docs-preview references it. Its front matter title is now Home, and the warning comment about the About title is gone. - **Other page titles not changed.** Only the sidebar titles changed. The front matter titles of `get-started/index.md` and `user-guides/index.md` stay as they are. - **Proposal page count.** The proposal expected 469 pages, measured against an older `main`. Current `main` already differs, so I report counts below instead of matching that number. ## Open questions for Nick 1. Confirm the redirect targets for the two deleted hubs (both `/docs`). 2. `speed-up-templates.md` lands in Workspaces, as the proposal says, but it is mostly about template build performance. Should it go to Templates instead? 3. Confirm `external-database.md` under Install (see PR B). 4. The sidebar sources still live under `docs/manifest/`, mirroring the new folders (`home.yml`, `support.yml`, and so on). Moving them next to the Markdown files is the follow-up PR waiting on the naming decision (DOCS-1154). ## Post-release follow-up After a release that includes this stack becomes the default docs version on coder.com, point these hardcoded URLs at the new paths. They work today and redirect after the release. | Current (old) URL | Post-release URL | Files | | --- | --- | --- | | `https://coder.com/docs/about#why-coder` | `https://coder.com/docs#why-coder` | `README.md` | | `https://coder.com/docs/tutorials/external-database` | `https://coder.com/docs/install/server/external-database` | `cli/server.go` (built-in PostgreSQL error message) | ## Validation run - `make gen/docs-manifest`: clean diff afterward. - `make lint/docs-manifest`, `lint/docs-redirects` (`-base docs/ia-templates`: 34 rules OK), `lint/docs-html`, `lint/emdash`: pass. - `pnpm check-docs` (markdownlint + table formatter): pass. - Vale over `docs/`: the same 12 warnings and 1 error as `main`, all pre-existing (suggestions: 645, the same as PRs A and B). - Local relative-link check over `docs/**/*.md`: 0 unresolved. - Pre-commit hook: `make pre-commit-light` on both docs commits, and the full `make pre-commit` on the chore commit. `make gen` left a clean tree. - After the Home title commit, the full docs lint set above was re-run and passed again (34 redirect rules OK, 0 unresolved links). Vale on `docs/README.md` shows only its pre-existing alert. - Restacked on the rebased `docs/ia-ai-sections` (on `main` at `ccf5ec74ae`). After the restack, `make gen/docs-manifest` (clean), `lint/docs-manifest`, `lint/docs-redirects` (34 rules OK), `lint/docs-html`, `lint/emdash`, `pnpm check-docs`, and the relative-link and anchor check over the changed pages pass. - **Link health (fix commit):** - linkspector 0.5.6 with `.github/.linkspector.yml` over all of `docs/`, like the weekly docs job, run locally. - `origin/main`: 0 errors. This branch before the fix (`5fe2b627df`, on the pre-fix `docs/ia-ai-sections`): the same 6 `https://coder.com/docs/<new path>` 404s as #31645, plus a transient Red Hat URL failure in `install/server/openshift.md`. That URL is unchanged from `main`, and it passed on reruns. After rebasing onto the fixed `docs/ia-ai-sections` and adding this fix (`c664641e1e`): 0 errors. Nothing is new compared with `main`. - After the fix: `make gen/docs-manifest` (clean), `lint/docs-manifest`, `lint/docs-redirects` (34 rules OK against `docs/ia-ai-sections`), `lint/docs-html`, `lint/emdash`, `pnpm check-docs`, and the relative-link check (0 unresolved) pass. The full `make pre-commit` passed on the commit. - Page counts across the stack: | | `main` | after A | after B | after C | | --- | --- | --- | --- | --- | | `docs/**/*.md` (excl. `.style`) | 490 | 487 | 487 | 485 | | `manifest.json` routes | 495 | 492 | 492 | 482 | The 10 routes removed in C are the 2 Tutorials hubs, 7 duplicate Tutorials entries, and the duplicate Scale Coder entry. The Istio entry moved, so it nets to zero. - **Skipped:** the docs-engine sync check, which was not available in this environment. <details> <summary>Implementation notes</summary> - Rebuilt on the new `docs/ia-templates`, which is based on `main` at `9839406ff7` (2026-11-02). After #31646 squash-merged PR B into `docs/ia-ai-sections`, this branch was rebased onto it with `git rebase --onto`; the tree didn't change. It was rebased again onto `docs/ia-ai-sections` after #31645's link-health fix commit (`def074caab`), which applied cleanly. - Restacked on 2026-11-03 onto `docs/ia-ai-sections` at `4c356c6314`, after #31645 was rebased onto `main` at `ccf5ec74ae`. The restack applied cleanly. Folded into the docs commit: the links between `shared-workspaces.md` and `persistent-shared-workspaces.md` that `main` added in #31152 now resolve from the moved page. `git range-diff` against the previous head (`c664641e1e`) shows only those changes and the sidebar entry `main` added for Bring your own MCP servers. - The same one-shot move script as PRs A and B did the move and link pass from a clean tree. Run on the old base, it reproduced the old commit except for the three hand edits listed under Deviations (dead Tutorials hub links), which were reapplied by hand. - The sidebar changes were applied with a three-way merge of each YAML file from the earlier version of this branch onto the current files, so entries added on `main` since then (for example Nix(OS) under Integrations) stay in place. - Changes from the earlier version of this branch: the Screenshots page and its redirect are gone from this PR, because #31465 did both on `main`. `admin/index.md` was reworded on `main`, and the Tutorials hub link was removed from the new wording. One more page link is fixed (`script-ordering.md`). </details> <details> <summary>CI flake on <code>70232dbbfb</code></summary> The `fmt` job failed because GitHub canceled the step on the Depot runner, before any formatting ran. A rerun of the failed jobs passed. </details> --------- Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com> Co-authored-by: Nick Vigilante <nick.vigilante@coder.com> |
||
|
|
7eacfe95b2 |
feat: enable Coder.LatinAbbreviations Vale rule (#30794)
Builds on #30782, which is merged; the branch now merges `main`. Adds `Coder.LatinAbbreviations`, a Vale rule that enforces [Latin abbreviations](https://github.com/coder/coder/blob/main/docs/.style/style-guide/accessibility-and-inclusion.md#latin-abbreviations). - Suggests "for example", "that is", and "and so on" for `e.g.`, `i.e.`, and `etc.`, including `eg.`, `ie.`, and a missing final period (`e.g`). - Severity: `suggestion`. Scope: `docs/**` except `docs/.style/style-guide/**`, limited to paragraphs, lists, headings, and blockquotes. Table cells and code are skipped. - Baseline: 170 findings in 91 files. The brief estimated 148. - Cleanup: 153 findings fixed across 81 hand-written pages, 0 left in linted pages. The count is lower than the original 158 because other PRs on `main` already rewrote or removed some of the lines, and `parameters.md` was deleted on `main`. - `vs.` and `et al.` aren't flagged. Commits: 1. `docs(docs): use English forms of Latin abbreviations` 2. `feat(docs/.style): enable Coder.LatinAbbreviations Vale rule` Generated pages: `.vale.ini` skips `docs/reference/{api,cli}/*.md` and `docs/admin/setup/configuration-reference.md` for this rule, as it does for `Coder.UnitSpacing`. Their prose comes from CLI flag help text and Swagger comments in Go source, and `make gen` rewrites them, so a hand edit fails the `gen` check (an earlier revision of this PR edited `configuration-reference.md` and failed `gen` for that reason). Cleaning them means editing Go and regenerating the help golden files and API docs, which is left for a follow-up. Linear: DOCS-450 <details> <summary>Decision log</summary> - `extends: substitution`, so the message names the replacement: "Consider 'for example' instead of 'e.g.'". - `scope: [paragraph, list, heading, blockquote]`. The single scope `paragraph` skips list items, blockquotes, and headings, so all four are listed. Table cells have their own scope and stay excluded. - Explicit `[Ee]` and `[Ii]` classes with `ignorecase: false`, so sentence-initial `E.g.,` still matches but the browser name `IE.` doesn't. - `eg.` and `ie.` require the trailing period so ordinary words and file extensions stay quiet. - Cleanup rules, applied by script and then reviewed line by line: - `e.g.` and `i.e.` become "for example," and "that is," (capitalized at the start of a sentence), with a comma added when the original had none. - `etc.` becomes "and so on", with the sentence-ending period kept when `etc.` closed the sentence. - Lines inside table rows, fenced blocks, and code spans are untouched, so are the style guide and the generated pages. - Hard-wrapped lines keep their wrapping, and CRLF files keep CRLF. - The rest of the Vale output is unchanged: the per-rule counts for every other rule match the pre-cleanup run. Test cases (fixtures under `/tmp/latin-test/`, not committed), run with LF and CRLF line endings: - Flagged (15 each): `e.g.,` in a paragraph, `i.e.,`, `etc.` at the end of a sentence and before a comma, `eg.`, `ie.`, `e.g` and `i.e` without the final period, `E.g.,`, `I.e.,`, `Etc.`, a blockquote, a list item, a numbered item, and a heading. - Not flagged: a table row with `e.g.,`, `i.e.,`, and `etc.`, code spans, a fenced block, "for example", "that is", "and so on", `IE.`, `genre`, `series`, `egg`, `tie`, `etcetera`, `vs.`, `et al.`. - Known edge case: a path-like token such as `path/i.e/x` outside code matches. It doesn't occur in the corpus. Checks: - `vale --output=line docs/`: 0 `Coder.LatinAbbreviations` findings. - `go run ./scripts/styleclaims` passes. - The pre-commit-light hook passes on both commits. </details> *Generated by [Coder Agents](https://coder.com/docs/ai-coder/agents) on behalf of @nickvigilante.* |
||
|
|
21c1abe9ad |
docs(docs/install): reformat to one sentence per line (#30438)
Reformats every Markdown page under `docs/install` to the [one-sentence-per-line convention](https://github.com/coder/coder/blob/main/docs/.style/style-guide/formatting.md#one-sentence-per-line). Addresses DOCS-668. This is a source-layout change only: 28 of the 36 pages change, and rendered HTML is identical for all of them except three wording fixes. Three pre-existing em dashes sat on reflowed lines, which `lint/emdash` flags as new, so they're rewritten with commas or a sentence break (`operate/upgrade/esr-2.24-2.29-upgrade.md`, `operate/upgrade/best-practices.md`). Front matter, fenced code, tables, HTML blocks, and headings are untouched. `Coder.OneSentencePerLine` is not enabled for `docs/install` in `.vale.ini`: the 39 remaining findings are all table rows or code, which the guide puts out of scope, and enabling the rule would break the zero-baseline doctrine. <details> <summary>Implementation and verification notes</summary> **Approach.** A throwaway script reflowed each paragraph. Bullet items, numbered entries, and blockquote lines (including `> [!NOTE]` callouts) are each their own paragraph; extra sentences in a list item continue on indented lines, matching `docs/.style/content-guidelines.md`. Sentence breaks are never inserted inside inline code, link text, URLs, or HTML tags, and abbreviations such as `e.g.` and `etc.` don't count as sentence ends. Images that started their own source line stay on their own line. The script is idempotent: a second pass produces no changes. **Merge with main.** `main` restructured `docs/install` into plan, prepare, server, validate, and operate sections after this branch was cut. The merge takes `main`'s tree and re-runs the reflow over every page now under `docs/install`, so the branch diff against `main` is reflow only. `releases/index.md` and `releases/feature-stages.md` moved out of `docs/install` on `main` and are no longer in scope. **Verification.** - Rendered every page with `marked` from `main` and from this branch and compared normalized HTML: identical except the three em-dash rewrites. - Vale with `Coder.OneSentencePerLine` forced on for `docs/install`: 277 findings on `main`, 39 on this branch, all in table rows or fenced code. - A broader sweep for mid-line sentence boundaries and for false splits (lines starting lowercase, lines ending in an abbreviation) found no prose hits. - `markdownlint-cli2`, `markdown-table-formatter --check`, `make lint/emdash`, and `make pre-commit-light` pass. </details> --- *Generated by Coder Agents on behalf of @ianjevans.* |
||
|
|
88aa2cc373 |
feat: enable Coder.UnitSpacing (#29944)
## Summary
Adds `Coder.UnitSpacing`, a Vale rule that enforces the style guide's
[non-breaking space between number and
unit](https://github.com/coder/coder/blob/main/docs/.style/style-guide/numbers-units-and-dates.md#non-breaking-space-between-number-and-unit)
policy.
Until now, the guide pointed at `Google.Units (planned)`, but that rule
accepts a regular space, so it can't enforce the policy.
Resolves [DOCS-1072](https://linear.app/codercom/issue/DOCS-1072).
## Changes
- **Cleanup commit**: replaces the regular space (or missing space) with
` ` in 189 prose findings across 55 files. One config default,
`(default: 15s)`, moves to code font instead, as the guide requires for
configuration values. One table row that was realigned also swaps a
pre-existing en dash for a hyphen, since `lint/emdash` checks changed
lines.
- **Enable commit**: adds `docs/.style/styles/Coder/UnitSpacing.yml` at
`warning`, updates the enforcement footer in
`numbers-units-and-dates.md`, and updates the coverage tables in the
style guide README.
- **Reflow commit**: every hard-wrapped paragraph the cleanup touched
(45 paragraphs in 29 files) is rewrapped to one sentence per line.
Joining lines exposed units split across a line break, which now use
` `, and two em dashes on rewritten lines are reworded.
- **Rule fix commit**: the token now matches ASCII whitespace, including
a newline, between the number and the unit, so a hard-wrapped paragraph
can't hide a missing ` `. The class is spelled out because Vale's
`\s` is Unicode and would match U+00A0. Vale can't locate a match that
spans list indentation or a blockquote marker, so splits there still go
unreported.
- **Rule count sync**: the tooling paragraph in the style guide README
now reads 79 rules, 9 tool-checked, to match the coverage table. The 79
corrects drift already on `main` since #29758; the 9 is this PR's new
rule.
- `.vale.ini` turns the rule off for pages generated from Go source:
`docs/reference/{api,cli}/*.md`, `configuration-reference.md`, and
`prometheus.md`. That text comes from flag descriptions, Swagger
comments, and metric help text, which also render outside Markdown,
where ` ` would show up literally.
<details>
<summary>Rule design decisions</summary>
- An `existence` rule matches `\d+(\.\d+)?` followed by a regular space
or no space, then a unit from a curated list (time, data size,
bandwidth, frequency, vCPU/CPU/cores).
- Vale renders Markdown before matching, so ` ` and a literal
U+00A0 both pass. Code spans and fences are skipped.
- Hyphenated compound modifiers (`12-hour clock`) don't match, because
the token allows only a space or nothing between the number and the
unit.
- Exceptions cover HTTP status plurals (`413s`) and decades (`1990s`).
- Severity is `warning`, because the unit list is curated and a count
followed by a unit-like word can still be a judgment call.
- Alternative considered: a `BlockIgnores` pattern for the `<!-- Code
generated ... -->` regions. I didn't use it because it would silence
every rule in those regions, not just this one.
</details>
## Testing
- Ran the rule against fixtures: `30 seconds`, `150ms`, `4 vCPU` in a
table, and `16` / `GB` split across lines in a paragraph all flag.
`30 seconds`, literal U+00A0, `12-hour`, `413s`, `1990s`, and ``
`30s` `` don't.
- `vale docs/` reports 0 `Coder.UnitSpacing` findings, and the counts
for every other rule match `main`.
- A scratch config with `Coder.OneSentencePerLine` turned on reports 0
findings on changed lines.
- `make lint/markdown`, `make lint/style-claims`, `make lint/emdash`,
and the `pre-commit-light` hook pass.
<details>
<summary>CI flake note</summary>
`Storybook` failed on
|
||
|
|
d5a6047879 |
docs: restructure Install into the five phase deployment spine (#29304)
Restructures the Install section into the five-phase deployment spine, so the reading order matches the order a deployment actually happens: **plan, prepare, install, validate, operate.** Today the first thing a reader sees is a shell command, and architecture and sizing sit downstream in Administration, after the point where they would have been useful. Resolves [DOCS-869](https://linear.app/codercom/issue/DOCS-869). Part of [DOCS-685](https://linear.app/codercom/issue/DOCS-685) and [DOCS-738](https://linear.app/codercom/issue/DOCS-738). > [!IMPORTANT] > **Stacked on [#28960](https://github.com/coder/coder/pull/28960)** (DOCS-871, terminology). Base is that branch, not `main`. Retarget to `main` after it merges. > > **Paired with coder/coder.com [#1077](https://github.com/coder/coder.com/pull/1077)**, which must merge **first**. Without it, every inbound link to a moved page 404s in the gap. ## Deliberately mechanical No prose changes. The only edits inside moved pages are relative link and image path repairs, so the diff reads as renames. That is the point: this is the highest link-breakage change in the project, and it should be reviewable as such. The prose work is [DOCS-868](https://linear.app/codercom/issue/DOCS-868) (phase overview, architecture rewrite, sizing split, actor table) and [DOCS-872](https://linear.app/codercom/issue/DOCS-872) (new pages). ## The new spine ```text Install and deploy Coder /install ├── Coder CLI [unchanged, retired by DOCS-870] ├── 1. Plan your deployment │ ├── Architecture and components [from admin/infrastructure] │ └── Coder Validated Architecture [from admin/infrastructure] │ └── 1k / 2k / 3k / 10k users ├── 2. Prepare prerequisites │ ├── Licensing [from admin/licensing] │ ├── Air-gapped deployments [from install/airgap] │ └── Mirror images and registries [from install/registry-mirror-artifactory] ├── 3. Install the control plane │ ├── Docker / Kubernetes / Rancher / OpenShift │ ├── Cloud marketplace and VM images │ └── Unofficial install methods ├── 4. Validate your deployment │ └── Scale testing [from admin/infrastructure] │ ├── Scale test utility │ └── Scaling best practices └── 5. Operate and maintain ├── External provisioners [from admin/provisioners] ├── Upgrading (+ best practices, ESR guides) └── Uninstall ``` Leaving Install: release channels become `reference/releases`, feature stages become `reference/feature-stages`. `docs/admin/infrastructure/` is gone entirely, which is what DOCS-738 recommended. ## Numbers - 31 pages moved, all as `git mv` renames. - 1 page deleted: `admin/infrastructure/index.md`, whose content was a one-line section blurb. - 5 new placeholder index pages, one per phase, each a sentence of orientation plus `<children></children>`. The nav schema requires a path on every entry, so a phase cannot exist without one. - 265 relative links and asset paths repaired across 57 files. - `docs/manifest.json` restructured. Entry count goes 460 to 464: plus 5 stubs, minus the deleted Infrastructure entry. ## Reviewer attention, please **The redirects PR repairs 19 existing redirects, not just adds new ones.** This was the surprise. `redirects.json` already had entries whose *destinations* pointed at pages this PR moves, so they would have started redirecting to 404s. Examples: `/docs/architecture/architecture`, `/docs/admin/architectures`, `/docs/scaling/scale-testing`, `/docs/licensing`, `/docs/enterprise`, `/docs/install/offline`, `/docs/platforms`, `/docs/install/1-click`, `/docs/admin/upgrade`, `/docs/install/cloud/ec2`, and both `feature-stages` aliases. All 19 are fixed in the paired PR. **This PR touches `scripts/`, so it is not docs-only.** Two release tools write to paths that moved and would have broken silently at release time: - `scripts/update-release-calendar.sh`: `DOCS_FILE` now points at `docs/reference/releases.md`. - `scripts/releaser/docs.go`: `releasesFile`, and also `kubernetesFile` and `rancherFile`, which pointed at `docs/install/kubernetes.md` and `docs/install/rancher.md`. <details> <summary>Deliberate scope decisions</summary> - **Self-managed vs cloud grouping is flattened.** The reconciled IA nested platform pages under a "Self-managed platforms" parent. That would need two more placeholder index pages for groups with no content yet, so the platform pages sit directly under Phase 3 and the grouping lands with the DOCS-868 prose. - **Release-notes URLs left alone.** `scripts/releaser/release.go` and `scripts/release/generate_release_notes.sh` embed `https://coder.com/docs/install/releases` and `/docs/install/upgrade` in release-note templates. The redirects cover them, and changing the strings would require updating Go test fixtures in `scripts/release/main_internal_test.go`. Better as its own change. - **In-product doc links left alone.** Several `site/src` pages link to `coder.com/docs/admin/provisioners` and similar. Those are absolute URLs, so the redirects cover them. Updating them is a frontend change that would pull frontend review into a docs restructure. - **`admin/security/audit-logs.md` line 237** is hand-written prose below the generated table, and its `../licensing/index.md` link had to move with the licensing page. Verified `make gen` does not revert it. - **`reference/feature-stages.md`** has generated blocks whose relative links changed depth with the move. The generator named in its own marker comment (`scripts/release/docs_update_feature_stages.sh`) no longer exists in the repo, so those links were repaired by hand and the file is effectively hand-maintained. Worth its own issue. - **`install/cli.md` keeps its nav slot** here. DOCS-870 retires it. </details> ## Verification | Check | Result | |---|---| | Broken relative link scan | 0 in `install/`, `admin/`, `reference/`. 21 remain, all pre-existing illustrative examples in `docs/.style/style-guide/**` and one malformed URL in `docs/README.md` | | `make gen` | clean, manifest not clobbered, phase structure intact | | `make lint/markdown` | pass, 508 files, 0 errors | | `make lint/emdash` | pass | | `make lint/docs-html` | pass | | `make lint/prose` | pass, 1 intentional demo error, no new findings | | `make pre-commit` | pass, including `lint/go`, `lint/ts`, `lint/shellcheck`, and a slim build | | Manifest audit | every path resolves to a file on disk; entry-by-entry diff shows only the expected moves | Generated with Coder Agents on behalf of @nickvigilante. <details> <summary>CI note: doc-check failure is infrastructure, not this PR</summary> `Analyze PR for Documentation Updates Needed` fails before it reviews anything: the Coder account behind `agents-chat-action` returns `User is not active (status = "suspended")`. It isn't a required check. `check-docs` (linkspector) and every other check pass on `58ed9e3e4b`. _CI note added by Coder Agents on behalf of @nickvigilante._ </details> |