mirror of
https://github.com/coder/coder.git
synced 2026-11-22 19:39:23 +08:00
feea5ab959f59cd2135443ed2a0c19bf7643db8f
11
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
155861f04e |
docs: replace ensure, should, and since per the Vale spike review (#31879)
Applies the Vale findings spike review's `ensure`, `should`, and `since` decisions, following `word-choice.md#choose-words-that-have-one-meaning`. ## `ensure`, `ensures`, `ensuring`: every row marked valid - 148 lines in 70 files. - Most became `make sure`, `makes sure`, or `making sure`. - When the subject isn't a person, I used a verb that reads better, such as `guarantees`, `keeps`, `prevents`, `maintains`, or `provides`. - `admin/monitoring/health-check.md:227`: "Make sure that" is now "Make sure", so the step stays within `Coder.StepLength`. - Left as-is: `admin/setup/configuration-reference.md:1339`, which is generated from `codersdk`. ## `should` and `since`: only rows with a verdict or a note - `.style/README.md`: "what should be routed elsewhere" is now "what to route elsewhere". - `.style/content-guidelines.md`: - "Avoid mixing those modes within a single page." - "Every page must be accurate" - "Check docs claims against the actual implementation" - "must include the documentation" - "Support owns the content they produce." - "because they don't change" - `.style/styles/Coder/README.md`: "must link to the matching section". - `admin/external-auth.md`: - "The redirect URI for Gitea is ..." - "Use custom authentication and token URLs ...", which is now active voice. - `envbuilder-releases-known-issues.md`: "so it's experimental and prone to breaking changes". Rows marked unsure with no note were left alone: `content-guidelines.md` lines 49, 330, and 405, and `envbuilder/index.md:24`. 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> |
||
|
|
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> |
||
|
|
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. |
||
|
|
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 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.* |
||
|
|
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.* |
||
|
|
fda1ed5dcd |
docs: give screenshots their own alt text and fill empty table headers (#30873)
## Summary An axe sweep of every page on https://coder.com/beta-docs (coder/docs-engine#224) found two content-side problems. Nine screenshots have alt text identical to the italic caption right after them, so screen readers read the same words twice (axe `image-redundant-alt`). Four hand-written tables have an empty top-left header cell, which leaves their row-label column without a name (axe `empty-table-header`). This fixes both. These are content fixes on `main` only; earlier release lines keep the old text. ## Findings | Rule | Pages | Cause | Fixed where | | --- | --- | --- | --- | | image-redundant-alt | 4 | Alt text repeats the caption | This PR | | empty-table-header | 4 hand-written | Empty corner header cell | This PR | | empty-table-header | 105 CLI reference pages, `audit-logs.md` | Generated tables with empty headers | Not here: needs a generator change | | empty-table-header | `admin/networking/port-forwarding.md` | Spanning corner cells in a raw HTML matrix | Not here: needs a rework of that table | | heading-order | `remote-desktops.md` | `<div class="tab">` typo | Separate PR | | link-name, scrollable-region-focusable, aria-valid-attr-value, label | many | Engine | coder/docs-engine #220, #217, #224 | ## Fix Each of the nine screenshots gets alt text that describes what it shows (for example, "Preset dropdown with Ruby Development added between Full Stack and Web Development"), and keeps its caption. The corner cells become "Permission" (Groups and roles), "Component" (air-gapped comparison), "Scenario" (scale-testing workloads) and "Input" (workspace tags). Tables were re-padded with `markdown-table-formatter`. ## QA 1. Open each production page below. Expected: the screenshots and tables look the same as before, except the four tables now show a word in their top-left header cell. 2. In Chrome DevTools (Elements) or Firefox's Inspector, select a screenshot on the Add a language page. Expected: its `alt` differs from the italic caption under it. ## Pages to compare | What to check | Production | Preview | | --- | --- | --- | | Screenshot alt text vs caption | https://coder.com/beta-docs/@main/get-started/customize-your-template/add-a-language/ | This PR's GitHub preview: https://github.com/coder/coder/blob/vigilante/docs-a11y-fixes/docs/get-started/customize-your-template/add-a-language.md | | Roles table corner cell | https://coder.com/beta-docs/@main/admin/users/groups-roles/ | https://github.com/coder/coder/blob/vigilante/docs-a11y-fixes/docs/admin/users/groups-roles.md | | Scale-testing table corner cell | https://coder.com/beta-docs/@main/install/validate/scale-testing/ | https://github.com/coder/coder/blob/vigilante/docs-a11y-fixes/docs/install/validate/scale-testing.md | ## Testing `markdownlint-cli2` and `markdown-table-formatter` over the eight changed files: 0 errors. Re-running the sweep after merge should drop `image-redundant-alt` and the four tables' `empty-table-header` findings from `@main`. ## Upstream No: these are Coder content fixes, not Fumadocs bugs. Linear: [DOCS-1303](https://linear.app/coder/issue/DOCS-1303) --- 🤖 Built with AI assistance. |
||
|
|
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.* |
||
|
|
d40e24cf7d |
docs: nest the CLI reference by subcommand (#29956)
## Summary Nests the CLI reference by subcommand so the Command Line sidebar collapses from 156 flat entries to 49 top-level verbs. Each page's URL follows the invocation, its page title is the full command as inline code, and its sidebar label is only its own verb as inline code. | | Before | After | | --- | --- | --- | | File | `docs/reference/cli/oauth2-provider_dcr_disable.md` | `docs/reference/cli/oauth2-provider/dcr/disable.md` | | URL | `/reference/cli/oauth2-provider_dcr_disable` | `/reference/cli/oauth2-provider/dcr/disable` | | Page title (front matter) | `oauth2-provider dcr disable` | `` `coder oauth2-provider dcr disable` `` | | Sidebar label (manifest) | `oauth2-provider dcr disable` | `` `disable` `` | Resolves DOCS-140 (coder/coder half). Also fixes the Makefile part of DOCS-1073 / DOCS-912, which this change depends on. ## Changes - `scripts/clidocgen`: pages nest by command path. A command with visible subcommands becomes its directory's `index.md`, so `oauth2-provider/index.md` and `oauth2-provider/dcr/index.md` sit above `oauth2-provider/dcr/disable.md`. Subcommand table links are relative to the parent page. - `scripts/clidocgen`: the manifest "Command Line" section is built from the command tree (nested, sorted by name, hidden commands skipped) instead of a flat list. The redundant `coder` child that pointed back at `reference/cli/index.md` is gone. - `Makefile`: the CLI rule now replaces `docs/reference/cli/` wholesale, so stale pages get removed. The manifest rule now runs `clidocgen -manifest-only` on top of the API staging manifest, so the CLI nav is generated instead of edited by hand. As a result, the nine pages that had no nav entry (`ai-gateway*`, `secret enable/disable`, `server fix-oidc-links`) now have one. - `scripts/configdocgen` and 48 prose pages: links point at the new paths (for example `reference/cli/server.md` is now `reference/cli/server/index.md`). ## How to review/QA this PR - `docs/reference/cli/**/*` (approximately 190 pages): Each of these pages are generated automatically. Some pages appear deleted, and some pages appear new. Every deleted page corresponds to a new page somewhere else, so no information is being deleted. The docs in this section should adhere to the following, so a test in the build preview for each of these items should be satisfactory: - [ ] Each subcommand of a command gets nested as a child instead of being displayed as a flat list. - [ ] Each parent command is stored in an `index.md` file. - [ ] The title of each page inside the page should now feature the full `coder XYZ` command. - [ ] The title of each page inside the page should now be formatted as inline code. - [ ] The title of each page in the sidebar should be the most granular subcommand of the whole command string (if the page's title is `coder ai-gateway keys create`, the sidebar label is `create`). - [ ] The title of each page in the sidebar should now be formatted as inline code. - [ ] The page slug for each page is now the most granular subcommand. - [ ] All links now point to the correct page. - `docs/manifest.json`: The changes here reflect the updated structure of the `docs/reference/cli` section. - `docs/**/*.md` outside of `docs/reference/cli/**/*` (approximately 50 pages): The extent of the changes in these pages are just updating the paths to point to the new page locations. - [ ] The links on the page all point to the correct new path in `docs/reference/cli`. - `scripts/clidocgen` (4 files): This is the Go code responsible for generating everything inside of `docs/reference/cli/**/*`. A typical code review here should be satisfactory. - `scripts/configdocgen` (2 files): these two files just have updates to the raw `.md` path used by `docs/admin/setup/configuration-reference.md` and updates the tests to reflect that. - `Makefile`: This updates the `make` targets for generating the CLI docs to fit the new structure. ## Merge ordering Without the renderer PRs deployed, both docs sites show literal backticks in titles and sidebar labels. Without the redirects, the old flat URLs return 404. 1. Deploy before merging this PR: coder/docs-engine#176 (beta-docs renders these titles as inline code) and coder/coder.com#1111 (classic docs renders them as inline code). Both are safe to ship first, because titles without backticks render as before. 2. Merge this PR. 3. Merge coder/coder.com#1112 (redirects from the old flat URLs) only once this content reaches the mainline release branch that serves unversioned `/docs`. ## Testing - `go test ./scripts/clidocgen/ ./scripts/configdocgen/ ./scripts/docshtmlcheck/`: pass. New tests cover page paths, subcommand links, the nested manifest, and front matter quoting. - `make docs/reference/cli/index.md docs/manifest.json docs/admin/setup/configuration-reference.md`, then a forced rerun: the second run produced no diff. - Checked the manifest: all 164 CLI entries resolve to a file, no page is missing a nav entry, and everything outside "Command Line" is byte-identical. - Relative `.md` links across `docs/`: 0 broken, same as `main`. - `make pre-commit` and `make pre-push`: pass. On earlier pre-push attempts, different unrelated vitest files timed out under host load. Those files pass when run alone, and the final push passed with `PARALLEL_JOBS=1`. <details> <summary>Implementation plan and decision log</summary> **Goal (from DOCS-140 and the requester):** URLs follow the command hierarchy. Pages are titled with the full command, and sidebar entries with the last verb only. Both are formatted as inline code. **Contract with the renderers:** a title wrapped entirely in one pair of backticks (``^`[^`]+`$``) renders as inline code. Plain-text consumers (`<title>`, meta, search, llms corpus) strip the backticks. Page title comes from front matter `title`, and the sidebar label from the manifest node `title`. **Decisions** - A parent command is `dir/index.md` rather than a sibling `dir.md`. The root CLI page is already `index.md`, and both docs-engine and the legacy coder.com renderer map `x/index.md` to `/x`. - The manifest is built from the command tree, not from the written files, so ordering is deterministic and the nesting matches the pages exactly. - The manifest discard bug (DOCS-1073 item 1) is fixed here, because without that fix the generated nested manifest would never reach the tree. DOCS-1073 items 2 through 4 (a prose fix and a hidden-command policy) are out of scope. - `-manifest-only` keeps the existing parallel `make gen` layout: the API rule still owns `_gen/manifest-staging.json`, and CLI regeneration doesn't retrigger swag. - The renderer and redirect work lives in the companion PRs in coder/docs-engine and coder/coder.com. It is linked above and not duplicated here. </details> --- > [!NOTE] > Generated by Coder Agents on behalf of @nickvigilante. |
||
|
|
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> |