mirror of
https://github.com/coder/coder.git
synced 2026-11-22 11:28:40 +08:00
a9643ffcd378565e01303b4fc433461e83facdf1
13
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
731f0c6ac1 |
docs: explain git identity and credentials in shared workspaces (#31152)
Adds a **Git identity and credentials** section to the shared workspaces guide and links it from the persistent shared workspaces tutorial. Every user of a shared workspace uses the owner's Git identity, Git SSH key, external auth tokens, and user secrets, and the docs didn't say so. Closes #30278. Refs ENG-3444. ## Changes - `docs/user-guides/shared-workspaces.md`: new section that covers what resolves to the owner, the security implications, the service account recommendation, and how a shared user commits and pushes as themselves, with trade-offs. - `docs/tutorials/persistent-shared-workspaces.md`: two sentences after the service account step that link to the new section. ## Where this differs from the issue - The issue suggests `git -c user.name=... -c user.email=...`. It has no effect when the template sets `GIT_AUTHOR_*` and `GIT_COMMITTER_*`, because Git env vars beat all config, including `-c`. The docs say this and recommend exporting the env vars or using `git commit --author` instead. - Service accounts have no email address and can't sign in to the dashboard, so the docs don't claim the Git provider attributes activity to the service account. The docs say what commits look like and suggest putting the service account's `coder publickey` on a dedicated machine account. - Added user secrets to the list of owner-scoped things, since `docs/user-guides/user-secrets.md` already warns about this. ## Testing - Code sources: `coderd/gitsshkey.go` (`GetGitSSHKey(ctx, workspace.OwnerID)`), `coderd/workspaceagents.go` (external auth links looked up by `workspace.OwnerID`), `agent/agent.go` (`GIT_SSH_COMMAND`, env precedence), `cli/agent.go` (`GIT_ASKPASS`), `cli/ssh.go` (`--forward-agent`), `examples/templates/docker/main.tf`. - Ran with Git 2.53.0: exported `GIT_*` vars beat `git -c user.*`, `--author` changes only the author, and an empty `GIT_AUTHOR_EMAIL` produces `name <>`. - `markdownlint-cli2`, `make lint/emdash`, and Vale pass on both files. The pre-commit hook passed. <details> <summary>Not verified end to end (please check)</summary> - I didn't test SSH agent forwarding (`coder ssh --forward-agent` plus `export GIT_SSH_COMMAND=ssh`) against a real Git provider from a shared workspace. - I didn't run `gh auth setup-git` taking priority over Coder's `GIT_ASKPASS` in a workspace. This is based on Git's documented credential order: helpers first, then askpass. - I didn't check in a running deployment that `coder publickey` works with a service account token. </details> --- _Generated by Coder Agents on behalf of @nickvigilante._ |
||
|
|
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. |
||
|
|
21471da74c |
feat: enable Coder.Semicolons Vale rule (#30787)
Depends on #30782. Adds `Coder.Semicolons`, a Vale rule that flags a semicolon in prose. It enforces [No semicolons in prose](https://github.com/coder/coder/blob/main/docs/.style/style-guide/capitalization-and-punctuation.md#no-semicolons-in-prose). - Severity: `warning`. - Scope: paragraphs, list items, headings, and blockquotes in `docs/**` except `docs/.style/style-guide/**`. Table cells, code spans, and code blocks keep their semicolons. - Baseline: 137 findings. The cleanup commit fixes 112 of them across 61 files by splitting sentences, or by using a comma or a connecting word where a split reads badly. - Excluded in `.vale.ini`: `docs/reference/{api,cli}/*.md` and `docs/admin/setup/configuration-reference.md`. Their text is generated from Go source (CLI flag help, Swagger comments), and 25 findings live there. Fixing them means editing Go and regenerating, so I used a commented exclusion like `Coder.UnitSpacing` does. Say so if you prefer the Go fix. - Result: `vale --output=line docs/` reports 0 `Coder.Semicolons` findings outside the style guide. - Three headings lost a semicolon, so their anchors changed. I updated the links in `docs/.style/` and in `.claude/` (`DOCS_STYLE_GUIDE.md`, the `write-docs` and `doc-check` skills). Linear: DOCS-1261 <details><summary>Decision log</summary> - Scope list is `paragraph`, `list`, `heading`, `blockquote`. Without `blockquote`, a semicolon in a `>` quote goes unreported, which I checked. Table cells are outside those scopes, so they stay exempt without extra config. - Token is `(?<!TL);(?!DR)`. `TL;DR` in `telemetry.md` is an abbreviation, not punctuation. - ` ` entities and `style="a: b;"` attributes don't match. Vale can report a real semicolon on the wrong line of a paragraph that contains an entity or raw HTML (for example, `modules.md:69` pointed at a semicolon on line 71), so cleanup used a paragraph-wide search instead of trusting reported lines. - A semicolon inside a fenced block in a blockquote (`ai-gateway/monitoring.md:105`, a YAML comment) isn't reported and stays. - Cleanup default: `; x` becomes `. X`, then I reviewed the diff and hand-fixed list fragments, parentheticals, and headings. Each new sentence sits on its own line, outside table cells. The hand-written part of `prometheus.md` is also reformatted to one sentence per line. - Heading rewrites: `Verify against the code and document exact values`, `Evidence justifies a claim and does not belong in the claim`, `STUN returned different addresses and you may be behind a hard NAT`. - `prometheus.md` is in the generated-page exclusion for `Coder.UnitSpacing` but not here. Its semicolon was in hand-written prose, so I fixed it. - Enable commit updates the footer, the checks table (scope text matches `.vale.ini`), the coverage counts (Capitalization and punctuation 3/7 to 4/6, total 20 to 21 tool-checked and 25 to 24 planned), and the "What the tooling checks" counts. Tests (fixtures in `/tmp`, not committed), each run with LF and CRLF files: - Flagged: paragraph, list item, ordered list item, heading, blockquote. - Not flagged: table cell, code span, fenced block, ` ` and `&`, an HTML `style` attribute, and `TL;DR`. - `go run ./scripts/styleclaims`, `make lint/emdash`, and the pre-commit hook (markdown, typos, style-claims) pass. </details> *Generated by [Coder Agents](https://coder.com/docs/ai-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.* |
||
|
|
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. |
||
|
|
0d1225694e |
feat: show coder sharing in CLI help and reference docs (#30141)
`coder sharing` has been hidden since it was added behind an experiment,
although Shared Workspaces is GA and the prose docs already use it.
This removes `Hidden: true`, regenerates `docs/reference/cli/sharing/*`,
and adds the pages to the docs manifest.
The shared workspaces guide and the persistent shared workspaces
tutorial now link to the new reference.
**Behavior change:** `coder sharing` and its subcommands now appear in
`coder --help`.
The commands themselves are unchanged.
The `sharing remove --user/--group` help text previously said "to share
the workspace with"; it now says "to remove from the workspace".
<details>
<summary>Decisions</summary>
- Follow-up not in this PR: `DELETE /workspaces/{workspace}/acl` has no
CLI caller.
</details>
Closes [CLI-22](https://linear.app/codercom/issue/CLI-22)
_This PR was generated by Coder Agents on behalf of @nickvigilante._
|
||
|
|
d43dd98baf |
docs: rewrite gerund-leading headings and page titles (#30049)
Rewrites the headings and page titles that `Coder.GerundHeading` flags as gerund-leading, using the imperative for tasks and the noun form for concepts. This PR covers only changes that don't rename a page slug. ## Changes - Rewrites 121 in-page headings, bringing `Coder.GerundHeading` findings in `docs/` to zero. - Adds an empty `<a id="old-slug"></a>` above each renamed heading, so existing bookmarks and inbound deep links still land on the section. The legacy IDs were computed with the same slugger the classic renderer uses (`rehype-slug`), and all 115 that exist on production today match the live `id` attributes; the other 6 are on pages not published yet. - Updates the 18 in-docs links that targeted old anchors to use the new slugs, and the link text that quoted the old heading. - De-gerunds seven page titles (frontmatter and `manifest.json`) whose slugs don't change, for example `Upgrading Best Practices` to `Upgrade best practices`. - Scopes a Vale exception around the glossary term `Coding agent`, where "Coding" is an adjective. ## Not in this PR - **Pages with gerund slugs** (`creating-templates`, `getting-started`, `working-with-dev-containers`, `cloning-git-repositories`, `configuring-okta`, and others) keep their current titles, so the title and slug change together in the slug-rename PR. The redirects for those renames come in a third PR. - **Links outside `docs/`** to old anchors (Go notification strings, an applied SQL migration, golden files, and the generated `prometheus.md`) still target old slugs. They keep working through the legacy anchors, and updating them would need code changes. ## Known limitation `coder/docs-engine` prefixes raw-HTML `id` attributes with `user-content-` (DOM-clobbering protection), and inbound deep links aren't rewritten. Once the docs move to docs-engine, these legacy anchors resolve only as `#user-content-<old-slug>` unless docs-engine adds a fragment fallback. They work on the current coder.com renderer and on GitHub. ## Testing - `vale --filter='.Name=="Coder.GerundHeading"' docs`: zero findings, down from 122. - `make lint/markdown`, `make lint/docs-html`, `make lint/emdash`, and the pre-commit hook: all pass. - Scripted check that every relative `#fragment` link into a changed file resolves to a heading slug or a legacy anchor (177 links). - Scripted check that no legacy ID collides with a heading slug on the same page, and that no untouched heading's duplicate-suffix slug shifted. <details> <summary>Heading renames and legacy anchors (121)</summary> | File | Old heading | New heading | Legacy anchor | | --- | --- | --- | --- | | `admin/integrations/opentofu.md` | Using a custom Terraform binary | Use a custom Terraform binary | `#using-a-custom-terraform-binary` | | `admin/monitoring/connection-logs.md` | Capturing/Exporting Connection Logs | Capture and export connection logs | `#capturingexporting-connection-logs` | | `admin/monitoring/metrics.md` | Setting up metrics | Set up metrics | `#setting-up-metrics` | | `admin/networking/port-forwarding.md` | Accessing workspace ports | Access workspace ports | `#accessing-workspace-ports` | | `admin/networking/port-forwarding.md` | Sharing ports | Share ports | `#sharing-ports` | | `admin/networking/port-forwarding.md` | Configuring port protocol | Configure port protocol | `#configuring-port-protocol` | | `admin/networking/workspace-proxies.md` | Running on Kubernetes | Run on Kubernetes | `#running-on-kubernetes` | | `admin/networking/workspace-proxies.md` | Running on a VM | Run on a VM | `#running-on-a-vm` | | `admin/networking/workspace-proxies.md` | Running as a system service | Run as a system service | `#running-as-a-system-service` | | `admin/networking/workspace-proxies.md` | Running in Docker | Run in Docker | `#running-in-docker` | | `admin/networking/workspace-proxies.md` | Selecting a proxy | Select a proxy | `#selecting-a-proxy` | | `admin/security/audit-logs.md` | Capturing/Exporting Audit Logs | Capture and export audit logs | `#capturingexporting-audit-logs` | | `admin/security/audit-logs.md` | Purging Old Audit Logs | Purge old audit logs | `#purging-old-audit-logs` | | `admin/security/database-encryption.md` | Enabling encryption | Turn on encryption | `#enabling-encryption` | | `admin/security/database-encryption.md` | Rotating keys | Rotate keys | `#rotating-keys` | | `admin/security/database-encryption.md` | Disabling encryption | Turn off encryption | `#disabling-encryption` | | `admin/security/database-encryption.md` | Deleting Encrypted Data | Delete encrypted data | `#deleting-encrypted-data` | | `admin/security/secrets.md` | Displaying Secrets | Display secrets | `#displaying-secrets` | | `admin/setup/data-retention.md` | Keeping Data Indefinitely | Keep data indefinitely | `#keeping-data-indefinitely` | | `admin/setup/index.md` | Migrating from the built-in database to an external database | Migrate from the built-in database to an external database | `#migrating-from-the-built-in-database-to-an-external-database` | | `admin/setup/index.md` | Configuring Coder behind a proxy | Configure Coder behind a proxy | `#configuring-coder-behind-a-proxy` | | `admin/setup/telemetry.md` | Toggling | Turn telemetry on or off | `#toggling` | | `admin/templates/creating-templates.md` | Disabling the template builder | Turn off the template builder | `#disabling-the-template-builder` | | `admin/templates/extending-templates/agent-metadata.md` | Managing the database load | Manage the database load | `#managing-the-database-load` | | `admin/templates/extending-templates/docker-in-workspaces.md` | Authenticating with a Private Registry | Authenticate with a private registry | `#authenticating-with-a-private-registry` | | `admin/templates/extending-templates/index.md` | Running scripts on workspace lifecycle | Run scripts on workspace lifecycle events | `#running-scripts-on-workspace-lifecycle` | | `admin/templates/extending-templates/parameters.md` | Validating parameters | Validate parameters | `#validating-parameters` | | `admin/templates/extending-templates/prebuilt-workspaces.md` | Invalidating prebuilds | Invalidate prebuilds | `#invalidating-prebuilds` | | `admin/templates/extending-templates/prebuilt-workspaces.md` | Managing resource quotas | Manage resource quotas | `#managing-resource-quotas` | | `admin/templates/extending-templates/prebuilt-workspaces.md` | Managing prebuild provisioning queues | Manage prebuild provisioning queues | `#managing-prebuild-provisioning-queues` | | `admin/templates/extending-templates/prebuilt-workspaces.md` | Preventing resource replacement | Prevent resource replacement | `#preventing-resource-replacement` | | `admin/templates/extending-templates/prebuilt-workspaces.md` | Preventing prebuild queue contention (recommended) | Prevent prebuild queue contention (recommended) | `#preventing-prebuild-queue-contention-recommended` | | `admin/templates/extending-templates/process-logging.md` | Configuring custom templates to use workspace process logging | Configure custom templates to use workspace process logging | `#configuring-custom-templates-to-use-workspace-process-logging` | | `admin/templates/extending-templates/process-logging.md` | Viewing workspace process logs | View workspace process logs | `#viewing-workspace-process-logs` | | `admin/templates/extending-templates/process-priority.md` | Verifying the feature is enabled | Verify the feature is enabled | `#verifying-the-feature-is-enabled` | | `admin/templates/extending-templates/resource-metadata.md` | Hiding resources in the dashboard | Hide resources in the dashboard | `#hiding-resources-in-the-dashboard` | | `admin/templates/extending-templates/resource-metadata.md` | Using a custom resource icon | Use a custom resource icon | `#using-a-custom-resource-icon` | | `admin/templates/extending-templates/resource-ordering.md` | Using "order" property | Use the "order" property | `#using-order-property` | | `admin/templates/extending-templates/resource-persistence.md` | Disabling persistence | Turn off persistence | `#disabling-persistence` | | `admin/templates/index.md` | Extending templates | Extend templates | `#extending-templates` | | `admin/templates/managing-templates/change-management.md` | Testing and Publishing Coder Templates in CI/CD | Test and publish Coder templates in CI/CD | `#testing-and-publishing-coder-templates-in-cicd` | | `admin/templates/managing-templates/index.md` | Creating templates | Create templates | `#creating-templates` | | `admin/templates/managing-templates/index.md` | Editing templates | Edit templates | `#editing-templates` | | `admin/templates/managing-templates/index.md` | Updating templates | Update templates | `#updating-templates` | | `admin/templates/troubleshooting.md` | Debugging the startup script | Debug the startup script | `#debugging-the-startup-script` | | `admin/users/groups-roles.md` | Creating custom roles | Create custom roles | `#creating-custom-roles` | | `admin/users/index.md` | Configuring SSO | Configure SSO | `#configuring-sso` | | `admin/users/index.md` | Resetting a password on Kubernetes | Reset a password on Kubernetes | `#resetting-a-password-on-kubernetes` | | `admin/users/quotas.md` | Establishing Costs | Establish costs | `#establishing-costs` | | `admin/users/quotas.md` | Establishing Budgets | Establish budgets | `#establishing-budgets` | | `admin/users/sessions-tokens.md` | Creating tokens with scopes | Create tokens with scopes | `#creating-tokens-with-scopes` | | `ai-coder/agent-firewall/index.md` | Getting Started with Agent Firewall | Get started with Agent Firewall | `#getting-started-with-agent-firewall` | | `ai-coder/agent-firewall/index.md` | Viewing Audit Logs | View audit logs | `#viewing-audit-logs` | | `ai-coder/agent-firewall/nsjail/k8s.md` | Running without user namespaces | Run without user namespaces | `#running-without-user-namespaces` | | `ai-coder/agent-firewall/version.md` | Using Coder Before v2.30.0 with Claude Code Module v4.7.0+ | Coder before v2.30.0 with Claude Code module v4.7.0+ | `#using-coder-before-v2300-with-claude-code-module-v470` | | `ai-coder/agent-firewall/version.md` | Using Claude Code Module Before v4.7.0 | Claude Code module before v4.7.0 | `#using-claude-code-module-before-v470` | | `ai-coder/agents/getting-started.md` | Providing feedback | Provide feedback | `#providing-feedback` | | `ai-coder/agents/models.md` | Managing personal API keys | Manage personal API keys | `#managing-personal-api-keys` | | `ai-coder/agents/models.md` | Removing a personal key | Remove a personal key | `#removing-a-personal-key` | | `ai-coder/agents/models.md` | Using an LLM proxy | Use an LLM proxy | `#using-an-llm-proxy` | | `ai-coder/agents/platform-controls/git-providers.md` | Checking logs | Check logs | `#checking-logs` | | `ai-coder/ai-gateway/audit.md` | Navigating the UI | Navigate the UI | `#navigating-the-ui` | | `ai-coder/ai-gateway/audit.md` | Conducting a forensic audit | Conduct a forensic audit | `#conducting-a-forensic-audit` | | `ai-coder/ai-gateway/clients/jetbrains.md` | Using the AI Assistant | Use the AI Assistant | `#using-the-ai-assistant` | | `install/operate/upgrade/best-practices.md` | Diagnosing liveness probe issues | Diagnose liveness probe issues | `#diagnosing-liveness-probe-issues` | | `install/operate/upgrade/best-practices.md` | Recovering from failed database migrations | Recover from failed database migrations | `#recovering-from-failed-database-migrations` | | `install/operate/upgrade/esr-2.24-2.29-upgrade.md` | Upgrading | Upgrade recommendations | `#upgrading` | | `install/operate/upgrade/esr-2.29-2.34-upgrade.md` | Upgrading | Upgrade recommendations | `#upgrading` | | `install/prepare/licensing.md` | Adding your license key | Add your license key | `#adding-your-license-key` | | `install/server/cloud/azure-vm.md` | Creating and Uploading Your First Template | Create and upload your first template | `#creating-and-uploading-your-first-template` | | `install/server/cloud/compute-engine.md` | Configuring the control plane | Configure the control plane | `#configuring-the-control-plane` | | `reference/releases.md` | Installing stable | Install stable | `#installing-stable` | | `start/first-workspace.md` | Creating your first coder workspace | Create your first Coder workspace | `#creating-your-first-coder-workspace` | | `start/local-deploy.md` | Setting up a Coder deployment | Set up a Coder deployment | `#setting-up-a-coder-deployment` | | `tutorials/best-practices/organizations.md` | Managing Organizations at Scale | Manage organizations at scale | `#managing-organizations-at-scale` | | `tutorials/example-guide.md` | Adding Photos | Add photos | `#adding-photos` | | `tutorials/example-guide.md` | Setting the author data | Set the author data | `#setting-the-author-data` | | `tutorials/example-guide.md` | Setting up the routes | Set up the routes | `#setting-up-the-routes` | | `tutorials/persistent-shared-workspaces.md` | Finding shared workspaces | Find shared workspaces | `#finding-shared-workspaces` | | `tutorials/reverse-proxy-caddy.md` | Getting started | Get started | `#getting-started` | | `tutorials/reverse-proxy-caddy.md` | Generating wildcard certificates | Generate wildcard certificates | `#generating-wildcard-certificates` | | `tutorials/reverse-proxy-nginx.md` | Adding Coder deployment subdomain | Add the Coder deployment subdomain | `#adding-coder-deployment-subdomain` | | `tutorials/testing-templates.md` | Creating the headless user | Create the headless user | `#creating-the-headless-user` | | `user-guides/desktop/desktop-connect-sync.md` | Accessing web apps in a secure browser context | Access web apps in a secure browser context | `#accessing-web-apps-in-a-secure-browser-context` | | `user-guides/desktop/index.md` | Testing Your Connection | Test your connection | `#testing-your-connection` | | `user-guides/desktop/index.md` | Getting Help | Get help | `#getting-help` | | `user-guides/desktop/index.md` | Uninstalling | Uninstall Coder Desktop | `#uninstalling` | | `user-guides/devcontainers/index.md` | Getting started | Get started | `#getting-started` | | `user-guides/devcontainers/troubleshooting-dev-containers.md` | Finding your dev container agent | Find your dev container agent | `#finding-your-dev-container-agent` | | `user-guides/devcontainers/troubleshooting-dev-containers.md` | Getting more help | Get more help | `#getting-more-help` | | `user-guides/devcontainers/working-with-dev-containers.md` | Using the Coder CLI | Use the Coder CLI | `#using-the-coder-cli` | | `user-guides/devcontainers/working-with-dev-containers.md` | Using OpenSSH (config-ssh) | Use OpenSSH (config-ssh) | `#using-openssh-config-ssh` | | `user-guides/devcontainers/working-with-dev-containers.md` | Exposing ports on the parent workspace | Expose ports on the parent workspace | `#exposing-ports-on-the-parent-workspace` | | `user-guides/devcontainers/working-with-dev-containers.md` | Rebuilding dev containers | Rebuild dev containers | `#rebuilding-dev-containers` | | `user-guides/shared-workspaces.md` | Getting Started | Get started | `#getting-started` | | `user-guides/shared-workspaces.md` | Sharing your Workspace | Share your workspace | `#sharing-your-workspace` | | `user-guides/shared-workspaces.md` | Using a shared workspace | Use a shared workspace | `#using-a-shared-workspace` | | `user-guides/shared-workspaces.md` | Accessing workspace apps in shared workspaces | Access workspace apps in shared workspaces | `#accessing-workspace-apps-in-shared-workspaces` | | `user-guides/workspace-access/emacs-tramp.md` | Connecting To A Workspace | Connect to a workspace | `#connecting-to-a-workspace` | | `user-guides/workspace-access/emacs-tramp.md` | Using SSH | Use SSH | `#using-ssh` | | `user-guides/workspace-access/index.md` | Running remote commands with quoting | Run remote commands with quoting | `#running-remote-commands-with-quoting` | | `user-guides/workspace-access/jetbrains/gateway.md` | Configuring the Gateway plugin to use internal certificates | Configure the Gateway plugin to use internal certificates | `#configuring-the-gateway-plugin-to-use-internal-certificates` | | `user-guides/workspace-access/jetbrains/gateway.md` | Using an existing JetBrains installation in the workspace | Use an existing JetBrains installation in the workspace | `#using-an-existing-jetbrains-installation-in-the-workspace` | | `user-guides/workspace-access/port-forwarding.md` | Accessing workspace ports | Access workspace ports | `#accessing-workspace-ports` | | `user-guides/workspace-access/port-forwarding.md` | Sharing ports | Share ports | `#sharing-ports` | | `user-guides/workspace-access/port-forwarding.md` | Configuring port protocol | Configure port protocol | `#configuring-port-protocol` | | `user-guides/workspace-access/vscode.md` | Using the public extensions marketplaces | Use the public extensions marketplaces | `#using-the-public-extensions-marketplaces` | | `user-guides/workspace-access/vscode.md` | Adding extensions to custom images | Add extensions to custom images | `#adding-extensions-to-custom-images` | | `user-guides/workspace-access/vscode.md` | Installing extensions using its `vsix` file at the command line | Install extensions using a `vsix` file at the command line | `#installing-extensions-using-its-vsix-file-at-the-command-line` | | `user-guides/workspace-access/vscode.md` | Installing from a marketplace at the command line | Install from a marketplace at the command line | `#installing-from-a-marketplace-at-the-command-line` | | `user-guides/workspace-access/vscode.md` | Using VS Code Desktop | Use VS Code Desktop | `#using-vs-code-desktop` | | `user-guides/workspace-access/web-terminal.md` | Accessing the Terminal | Access the terminal | `#accessing-the-terminal` | | `user-guides/workspace-lifecycle.md` | Stopping workspaces | Stop workspaces | `#stopping-workspaces` | | `user-guides/workspace-lifecycle.md` | Deleting workspaces | Delete workspaces | `#deleting-workspaces` | | `user-guides/workspace-management.md` | Creating workspaces | Create workspaces | `#creating-workspaces` | | `user-guides/workspace-management.md` | Updating workspaces | Update workspaces | `#updating-workspaces` | | `user-guides/workspace-management.md` | Updating via the CLI | Update with the CLI | `#updating-via-the-cli` | | `user-guides/workspace-management.md` | Starting and stopping workspaces | Start and stop workspaces | `#starting-and-stopping-workspaces` | | `user-guides/workspace-management.md` | Repairing workspaces | Repair workspaces | `#repairing-workspaces` | | `user-guides/workspace-scheduling.md` | Working hours | Work schedule | `#working-hours` | | `user-guides/workspace-scheduling.md` | Basing solely on activity detection | Rely solely on activity detection | `#basing-solely-on-activity-detection` | </details> <details> <summary>Plan</summary> The de-gerund work ships as three PRs: 1. This PR: in-page headings and page titles that do not require a page slug rename. 1. Page slug renames for pages whose filenames are gerunds. 1. Redirects for the renamed slugs. Heading rewrites follow the style guide section "No gerund-leading headings": imperative for task headings, noun form for concept headings, sentence case, and "turn on"/"turn off" instead of "enable"/"disable" per word-choice guidance. The legacy anchor sits on its own line above the heading (with a blank line between) rather than inside the heading, so it does not leak into heading text, TOC entries, or Fumadocs slugs. </details> --- _Generated by Coder Agents on behalf of @nickvigilante._ |
||
|
|
5e41baf73c |
docs: normalize control plane, coderd, and coder server terminology (#28960)
Normalizes the three overlapping names for the thing that serves the Coder API and dashboard. This is step 1 of the Install/Deploy and Administration refactor ([DOCS-685](https://linear.app/codercom/issue/DOCS-685), [DOCS-738](https://linear.app/codercom/issue/DOCS-738)) and lands first because every later page depends on settled terminology. Resolves [DOCS-871](https://linear.app/codercom/issue/DOCS-871). ## The rule | Term | Means | Use when | |---|---|---| | control plane | The component that serves the Coder API and dashboard, brokers connections, and coordinates provisioners | Default in prose, diagrams, planning, sizing, security | | `coderd` | The process that implements it | Architecture internals, metrics, logs, flags, troubleshooting | | `coder server` | The literal CLI command | Only when the reader will type it | Retired: "the Coder server" as a name for the component, and "a service" as a standalone description of it. ## What changed - **`docs/.style/style-guide/word-choice.md`**: new "Naming Coder's components" rule, with do/don't examples. Also fixes a "Do" example on that page that itself used "the Coder server". - **`docs/reference/glossary.md`**: rewrote `coderd` and Control plane, added a `coder server` entry. The existing Control plane entry defined it as "the collective term for `coderd`, its provisioners, and its database", which made it indistinguishable from the Deployment entry two sections later. Control plane is now the component; Deployment remains the whole installation. - **65 pages** across `docs/admin`, `docs/install`, `docs/get-started`, `docs/tutorials`, `docs/user-guides`, `docs/ai-coder`, and `docs/about`: roughly 154 component-sense "Coder server" usages, 21 bare "the server" usages meaning the control plane, 3 "a service" descriptions, and 43 unbackticked `coderd` mentions in prose. - One real bug caught in passing: `docs/tutorials/best-practices/security-best-practices.md` documented `coderd server --disable-path-apps`, which is not a command. Now `coder server`. Generated files were not touched: `configuration-reference.md`, `prometheus.md`, `audit-logs.md`, `reference/cli/*`, `reference/api/*`, and the generated blocks inside `feature-stages.md`. Those still contain the retired term and need generator-side changes; see the deferred list below. ## Reviewer attention, please **Anchor changes.** 11 headings were renamed, so their fragments change. No in-repo link targets any of them (the one internal link that did was updated), but external deep links from tickets or blog posts would break, and fragments cannot be fixed with a redirect. Happy to revert any of these if you would rather they ride along with the page moves in [DOCS-869](https://linear.app/codercom/issue/DOCS-869), which changes those URLs anyway. <details> <summary>Renamed headings and their old fragments</summary> | File | Old fragment | New heading | |---|---|---| | `admin/networking/index.md` | `#coder-server` | `## Control plane` | | `install/index.md` | `#starting-the-coder-server` | `## Starting the control plane` | | `install/uninstall.md` | `#the-coder-server-binary-and-cli` | `## The Coder binary and CLI` | | `install/registry-mirror-artifactory.md` | `#step-5-configure-coder-server-or-provisioners` | `## Step 5: Configure the control plane or provisioners` | | `install/cloud/compute-engine.md` | `#configuring-coder-server` | `## Configuring the control plane` | | `get-started/index.md` | `#cant-start-coder-server-address-already-in-use` | ``### Can't start `coder server`: Address already in use`` | | `tutorials/external-database.md` | `#coder-server-fails-startup-with-...` | ``### `coder server` fails startup with ...`` | | `tutorials/faqs.md` | `#how-do-i-change-the-access-url-for-my-coder-server` | `## How do I change the access URL for my control plane?` | | `tutorials/best-practices/security-best-practices.md` | `#coder-server` | `## Control plane` | | `tutorials/best-practices/security-best-practices.md` | `#server-logs-and-audit-logs` | `### Control plane logs and audit logs` | | `tutorials/best-practices/scale-coder.md` | `#coder-server`, `#how-to-capture-coder-server-metrics-with-prometheus` | `## Control plane`, `### How to capture control plane metrics with Prometheus` | </details> **One deliberate deviation from the issue.** DOCS-871 proposed reserving "sub-agent" for the Coder Agents sense and using "devcontainer agent" for the workspace sense. I did not make that change. The glossary already disambiguates with "Sub-agent (Coder Agents)" and "Sub-agent (dev containers)", and "devcontainer agent" would violate the existing dev container spelling rule in the same style guide, which requires "dev container" as two lowercase words. The current split reads correctly and costs no churn. Happy to revisit if you disagree. <details> <summary>Deferred, with reasons</summary> - **Generated content still says "Coder server".** `reference/cli/*` comes from Go command help text, `configuration-reference.md` from `configdocgen`, and `reference/api/*` from Swagger annotations. Fixing those means changing Go source, which belongs in its own PR so a docs review does not turn into a backend review. - **`validated-architectures/index.md` "also known as `coderd`"** is fixed here, but the page's larger problem is that it holds four documents in one file. That split is [DOCS-868](https://linear.app/codercom/issue/DOCS-868). - **"server flag" phrasing** in `admin/users/idp-sync.md` and `admin/users/oidc-auth/index.md` means `coder server` flags. Left alone; rewording those sentences is a copy edit, not a substitution. - **Metric and UI labels** such as "Dashboard-to-server latency" in `admin/networking/index.md`. Renaming risks diverging from what the dashboard shows. - **Pre-existing `Coder.GerundHeading` warnings** on headings this PR touches, and a "from from" typo in `scale-coder.md`. Out of scope for a terminology pass. - **Peer-sense "server"** in NAT traversal prose, where "client or server" describes the connection roles rather than the control plane. Needs restructuring, not substitution. </details> ## Verification | Check | Result | |---|---| | `make lint/emdash` | pass | | `make lint/markdown` | pass, 504 files, 0 errors | | `make lint/docs-html` | pass | | `make lint/prose` | pass, findings identical to the `main` baseline (1 intentional demo error, 145 warnings, 1 suggestion; only Vale's file ordering and one line-number shift in `glossary.md` differ) | | `make gen` | clean, no drift | | `make fmt/markdown` | applied | No redirects needed: no page moved or was renamed in this PR. <details> <summary>Merged main, 2026-09-14</summary> One conflict, in `docs/ai-coder/ai-gateway/providers.md`. Both hunks were text this PR had edited and `main` had since deleted in #29053, which removed env-based AI provider configuration: - The deprecated provider seeding note, which held a `coderd` backtick fix, is gone. Took `main`. - The failure-mode table lost its env-drift row. Took `main`'s two rows and reapplied the `coderd` logs wording. `main` also landed new prose carrying the retired terms, so the pass was extended to cover it: - `docs/admin/integrations/oauth2-provider.md`: two "the server log(s)" in the scope-enforcement sections added by #29144 are now "the `coderd` log(s)"; "a `scope` the server will not grant" is now "the control plane". - `docs/reference/cli/index.md` gained "the server" from #29104, and stays deferred as generated content. The new `docs/ai-coder/agent-relay/claude-code.md` needed no change, and no page `main` added links to a heading this PR renamed. </details> <details> <summary>Decision log for the wider refactor</summary> Agreed with @nickvigilante before implementation, recorded on DOCS-685 and in the Notion outline: 1. Feature stages and release channels move to Reference; ESR upgrade guides move under Operate. No new top-level Releases section. 2. `data-retention.md` moves to Administration > Security; `chat-lifecycle-hooks.md` moves into the Coder Agents docs. `admin/setup/` therefore survives as "Deployment configuration" and `configdocgen` is not touched. 3. Prepare is advisory, not a gate, framed as "don't know where to start? Start here", with lead times and owners per item. 4. One actor table, on the Install overview, spanning all five phases, noting that one person can be several actors and several people can be one actor. 5. The quickstart stays independent and is mentioned once, on the Install overview. The proposed `server/single-machine` page is dropped. 6. Coder Validated Architecture keeps its name in nav, defined in-page, with a glossary entry. 7. PR 3 is split: moves only, then prose, so the riskiest change reads as a pure rename diff. 8. For every PR that moves a page, the coder.com `redirects.json` change merges first. 9. There is no Download section and no CLI page in docs. Per-OS CLI steps live on coder.com/download and the Install overview links to it. </details> Generated with Coder Agents on behalf of @nickvigilante. |
||
|
|
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). |
||
|
|
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.* |
||
|
|
9b847cc5ab | feat: support "me" with shared_with_user filter (#26494) | ||
|
|
61d6c728b9 |
docs: adding a tutorial for persistent shared workspaces (#23738)
Co-authored-by: Jiachen Jiang <jcjiang42@gmail.com> |