mirror of
https://github.com/coder/coder.git
synced 2026-11-22 11:28:40 +08:00
90948802e2439d2641f392e6229dd058a1dcafe3
18
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
44af8a1b56 |
docs: shorten the add-a-language install script copy and note apt reinstalls (#30376)
The "Add a programming language" guide embedded a full copy of the install script that had drifted from the shipped Template Builder base (it used `grep -q` partial matching, not `has_language`). The Final code tab now shows an abbreviated excerpt (helpers plus the new Ruby branch) so it can't drift again, and Step 4 and the "How does Coder install the language you pick?" section use `has_language ruby`. Also adds a short note in Step 4 that `apt-get` installs Ruby into the ephemeral container, so it reinstalls on every start, while home-directory installs persist. The persistent `~/.local` approach from the ticket is not taught because it never landed on `main` (#28485 was closed unmerged). The `has_language` helper is present in the Template Builder base on `main`. The older example template gets it in #30373. Refs DOCS-713. Generated by Coder Agents on behalf of @nickvigilante. |
||
|
|
c30b44ad14 |
docs: turn the Quickstart's next steps into goal-based paths (#29800)
## Summary The Quickstart ends with one "customize your template" sentence and a flat "Learn more" list, so a reader who has just launched a workspace has no clear goal for what to do next. This rewrites "What's next?" into three goal-based paths, puts Coder Agents first, and gives readers without a project a small first task. ## Changes - **Hand a task to a coding agent**: what Coder Agents is, that Community deployments can run up to five agents at no cost, the LLM-provider-key prerequisite, and a link to the Coder Agents getting-started guide. Includes a concrete starter prompt idea for readers with no project in mind. - **Make the workspace fit how you work**: the existing Customize your template series, plus dotfiles. - **Bring in your team**: install on a separate machine, create users, and have teammates launch workspaces from the same template. - **Learn more** keeps monitoring and adds the Coder Registry; the workspace-management link moves into the team path. ## Testing - `pnpm exec markdownlint-cli2 docs/get-started/index.md`: 0 errors. - Checked that every relative link target exists on `main`, including the `#create-a-user` anchor. ## Notes - #29304 touches this page (terminology only, in other hunks); the only shared line, `A control plane running locally.`, is already on `main`, so the two should not conflict. - Not a Fumadocs upstream candidate (content only). Linear: https://linear.app/codercom/issue/DOCS-342 --- 🤖 Built with AI assistance. <details> <summary>CI flakes unrelated to this change (rerun)</summary> - `Storybook`: the Pixel upload returned HTTP 500 for many snapshots and the browser context closed mid-run. This PR changes only `docs/get-started/index.md`, so no stories are affected. Failed job rerun. - `Analyze PR for Documentation Updates Needed`: the AI docs check failed before analysis because the bot's Coder account was suspended (`401 User is not active`). Later runs on other PRs pass. Failed job rerun. _Generated by Coder Agents on behalf of @nickvigilante._ </details> --------- Co-authored-by: Ian Evans <5760366+ianjevans@users.noreply.github.com> |
||
|
|
1fd383e4fd |
docs: flatten lone index pages to single files (#30129)
The beta docs engine turns a directory that holds only an `index.md` into an empty collapsible section in the sidebar. Two pages on `main` have that shape: `docs/admin/external-auth/index.md` and `docs/ai-coder/agents/tools/index.md`. docs-engine is handling the shape in its own code (the sidebar render fix in https://github.com/coder/docs-engine/pull/196 and the sync-side handling in https://github.com/coder/docs-engine/pull/195), and this change removes it at the source by moving each page to a flat file: `docs/admin/external-auth.md` and `docs/ai-coder/agents/tools.md`. Both directories held only `index.md`, with no images or other files. The change updates the two `docs/manifest.json` paths, 29 inbound relative links across 17 pages, and the relative links inside the moved pages (three images and two page links in `external-auth.md`, one page link in `tools.md`), which now resolve one directory up. The ESR upgrade table in `docs/install/operate/upgrade/esr-2.29-2.34-upgrade.md` is re-padded because its link cells shrank, which is why that file shows 28 changed lines. No generator under `scripts/`, the docs-preview workflow, or `docs/.style` references either path. Published URLs stay the same, so no redirect is needed. coder.com's `convertPathToRoute` strips the `index.md` or `.md` suffix, the docs-preview workflow's `map_doc_path` maps `<dir>/index.md` and `<dir>.md` to the same route, and docs-engine's `mapMdPath` returns `admin/external-auth` and `ai-coder/agents/tools` for both the old and new paths. For verification, `docs/manifest.json` parses and all 471 of its paths exist. `make pre-commit-light` passes, which covers markdownlint, the table formatter, typos, emdash, and shellcheck, and `go run ./scripts/docshtmlcheck` passes. A local script resolved all 306 relative links in the changed files, and every one that the move touched points at an existing file and heading. linkspector runs on this PR in CI. A backport PR for `release/2.37` moves the same two pages plus `admin/licensing` and `install/other`: https://github.com/coder/coder/pull/30130. This change was prepared with AI assistance. The AI agent that prepared it ran the checks described above. --- 🤖 Built with AI assistance. |
||
|
|
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
|
||
|
|
99a3425333 |
fix: advertise install.sh with curl -fsSL everywhere (#29801)
## Summary The install one-liner is advertised as `curl -L` in most docs pages, the README, and the CLI's default version-mismatch hint, while `install.sh` itself and the deployment-local hint use `curl -fsSL`. Without `-f`, curl writes an HTTP error body to stdout, and the one-liner pipes that error page into `sh`. This PR standardizes every `install.sh` invocation on `-fsSL` so a failed download fails closed. ## Changes - Docs: `install/cli.md`, `install/operate/upgrade.md` (twice), `get-started/index.md`, `start/local-deploy.md`, `install/operate/provisioners/index.md`, `admin/templates/managing-templates/change-management.md` (twice), `user-guides/workspace-access/zed.md`, and `README.md`. - CLI: `defaultUpgradeMessage` in `cli/root.go` now prints `curl -fsSL`, matching the deployment-local branch in the same function. - `codersdk/deployment.go`: the `--cli-upgrade-message` description now says `curl -fsSL`; the server help goldens, `server-config.yaml.golden`, `docs/reference/cli/server.md`, and `docs/admin/setup/configuration-reference.md` are regenerated to match. - `install.sh`: the "To run" header comment now matches the script's own usage text. - Style guide: a new "Commands that pipe a download into a shell" rule in `docs/.style/style-guide/formatting.md`, and the tabs example uses `-fsSL`. The coder.com download page already builds its command from `-fsSL` in coder/coder.com#1093, and coder.com `main` has no other `install.sh` one-liners outside test fixtures, so no coder.com change is needed. DatoCMS content and a release verification page are not in this PR. `main` since moved the upgrade and provisioner pages under `docs/install/operate/` and removed the install one-liner from `docs/install/index.md` in #29304, so that page no longer appears in this diff. ## Testing - `TZ=UTC go test ./cli -run='Test(CommandHelp|ServerYAML|ErrorExamples|.*Golden)' -update` and `go test ./enterprise/cli -run=TestEnterpriseCommandHelp -update` pass and produce the committed golden diffs. - `go test ./cli -run 'Test.*Version|TestWrapTransport'` passes, including `Test_wrapTransportWithVersionCheck`. - `go run ./scripts/configdocgen` output contains the new `curl -fsSL` description. - `markdownlint-cli2` on the edited style guide page reports 0 errors. - `git grep` finds no remaining `curl -L …install.sh` outside the style guide's **Don't** example. - After merging `main`: `make pre-commit` passes, and `make test`, `make test-js`, and `make site/out/index.html` pass. Linear: https://linear.app/codercom/issue/DOCS-964/standardize-installsh-curl-flags-on-fssl-across-docs-codercom-and-the --- 🤖 Built with AI assistance. |
||
|
|
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> |
||
|
|
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). |
||
|
|
bc77c40296 |
docs: add front-matter titles to mechanical and no-H1 pages (Phase 3) (#28030)
## Summary **Batch A of Phase 3** of the H1 → front-matter migration (`DOCS-484`; parent `DOCS-477`). Adds a front-matter `title` to every navigable docs page whose title can be migrated **mechanically**, with no editorial judgment. This is the content step that Phase 1 (renderers prefer front-matter title, `DOCS-482`) and Phase 2 (tooling + generators front-matter-aware, `DOCS-483`) unblocked. Both are merged; coder.com #964/#974 are merged and live. **Rendered no-op.** The renderers already resolve the page title from the manifest and hide the leading body H1 (Phase 1), so no page changes visually. This just moves the title into front matter where Fumadocs and the migrated tooling can read it. ## What's in this batch Dry-run on `main` (464 navigable pages) splits into: | category | count | this PR | |----------|-------|---------| | already has front-matter title (Reference, from Phase 2 generators) | 196 | skipped (idempotent) | | **mechanical** — leading body H1 equals the manifest label | 138 | ✅ add front-matter `title`, drop the duplicate H1 | | **no body H1** — renders under the manifest label only | 4 | ✅ add front-matter `title` only | | **mismatch** — body H1 differs from the manifest label | 126 | ⏭️ deferred (needs an editorial decision, see below) | 142 files changed, all under `docs/`. ## Deliberately out of scope: the 126 mismatches Pages where the body H1 is richer than the short sidebar label (e.g. label **Modules** / H1 *Contributing modules*, label **Install** / H1 *Installing Coder*) need a canonical-title decision, not a script. A few even look like the body H1 is the redundant one (`install/cli.md` and `install/index.md` both carry the H1 *Installing Coder*). These will land in follow-up batches **by nav section** once the policy is set, so each gets real review. ## 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. - Every added front-matter block parses as YAML and its `title` round-trips to the manifest label (checked programmatically across all 142 files). - Every removed line is a leading `# H1` that equalled the manifest title; no body prose was reflowed. Front matter is correctly hoisted above pre-existing `<!-- markdownlint-disable -->` comments on the two pages that had them. - `pnpm check-docs` (markdownlint-cli2 + table formatter) passes on the changed set: `Summary: 0 error(s)`. `MD041` stays off (re-enabled in Phase 4); `MD025` is not tripped because the duplicate body H1s are removed. ``` $ pnpm exec markdownlint-cli2 $(git diff --name-only origin/main) Linting: 142 file(s) Summary: 0 error(s) ``` Linear: DOCS-484 > This PR was created with AI assistance (Coder Agents). |
||
|
|
defd5d48a1 |
docs: clarify that Coder server should run on a separate machine (#27468)
Closes [DOCS-600](https://linear.app/codercom/issue/DOCS-600/make-it-clear-in-the-quickstart-that-you-should-install-the-coder). The Quickstart guide has readers install and run `coder server` on the same machine they're working from, without calling out that this is only for a quick trial. Coder's actual value comes from remote development, so hosting the Coder server on a separate machine has a lot more power than running it locally. This adds two notes to `docs/get-started/index.md`: - In **Prerequisites**, explaining that this quickstart runs the server locally for convenience, but a real deployment should host it on a separate machine, and linking to the [Install](https://coder.com/docs/install) page. - In **Step 2: Install and start Coder**, a shorter reminder right before the install commands. ---- Created using Coder Agents 🤖 --------- Co-authored-by: Nick Vigilante <nickvigilante@users.noreply.github.com> |
||
|
|
062c0fdd3b |
docs: rebrand Windsurf doc page to Devin Desktop (#28205)
## Summary Cognition (maker of Devin) rebranded the Windsurf Editor as Devin Desktop on June 2, 2026, after acquiring it from Codeium in July 2025. Our docs still referred to the editor as Windsurf and linked to a dead `codeium.com` domain. ## Changes - Renamed `docs/user-guides/workspace-access/windsurf.md` to `devin-desktop.md`, rewritten to lead with Devin Desktop branding, note the Codeium -> Windsurf -> Devin Desktop history, and use current links (`windsurf.com`, `docs.windsurf.com`) instead of dead `codeium.com` ones. - Updated `docs/manifest.json` and `docs/user-guides/workspace-access/index.md` to reference the new page. - Updated remaining Windsurf mentions to Devin Desktop in `docs/ai-coder/ide-agents.md`, `docs/ai-coder/index.md`, `docs/reference/glossary.md`, and `docs/ai-coder/ai-gateway/clients/index.md`. - Added `windsurf.com`/`devin.ai` to `.github/.linkspector.yml` ignore patterns; both rate-limit repeated automated requests with 429s (same class of issue as the `codeium.com`/`marketplace.visualstudio.com` fix in #28203). - Switched every module reference from `windsurf` to the new `devin-desktop` registry module (`docs/about/contributing/modules.md`, the three `get-started/customize-your-template/*.md` Terraform tutorials, and the main doc page's module link), since the new module actually renders `display_name = "Devin Desktop"` / `slug = "devin-desktop"` in the UI (the old `windsurf` module hardcodes "Windsurf Editor"). <details> <summary>Scope notes / sequencing</summary> The `devin-desktop` module referenced here is being added in [coder/registry#1050](https://github.com/coder/registry/pull/1050) (not yet merged/released). That PR is itself gated on [coder/coder#28214](https://github.com/coder/coder/pull/28214) (whitelisting the `devin:` URI scheme) shipping in a released Coder version first. This docs PR can merge independently, the module link will 404 until #1050 is released, same as any docs-ahead-of-registry-release sequencing. The Terraform code samples now show `module "devin-desktop"` because that module's `display_name`/`slug` are properly parameterized (unlike `windsurf`, which hardcodes "Windsurf Editor"/`windsurf` regardless of what's passed in), so the docs stay accurate to the rendered UI. </details> ## Validation - `make lint` (docs lint, markdownlint, repo checks) passes. - Manually verified the new outbound links (`docs.windsurf.com`) return 200; `windsurf.com`/`devin.ai` are rate-limited (429) from this environment too, hence the added ignore patterns. Stacked on #28203 (targets that branch so the diff here stays scoped to the rebrand; will retarget to `main` once #28203 merges). > 🤖 This PR was created with the help of Coder Agents, and needs a human review. 🧑💻 |
||
|
|
e1fa247e59 | feat: redirect to the template builder after first time setup (#27670) | ||
|
|
79723db2d2 |
docs: replace enterprise-base image references with example-base (#27025)
Follow-up to #27018, sweeping the remaining `codercom/enterprise-base:ubuntu` references to `codercom/example-base:ubuntu` and `coder/enterprise-images` links to [coder/images](https://github.com/coder/images). The `example-` prefix is the recommended one for new deployments per the coder/images README. Covers the 11 docs pages flagged by doc-check on #27018 plus the embedded `examples/templates/docker` and `examples/templates/kubernetes` starter templates (image string only; the `image` variable lives in the coder/registry templates, see coder/registry#943). OpenShift imagestream names in `docs/install/openshift.md` keep the `enterprise-base` local name; only the upstream image reference changed. Part of DEVREL-201. 🤖 Generated with Coder Agents using Claude, on behalf of @bpmct |
||
|
|
8654b1cec3 |
docs: add clarification of install methods in Get Started guide (#27466)
I was confused by the difference between the Quickstart page and the Install page. Fixes DOCS 602 <!-- If you have used AI to produce some or all of this PR, please ensure you have read our [AI Contribution guidelines](https://coder.com/docs/about/contributing/AI_CONTRIBUTING) before submitting. --> |
||
|
|
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.* |
||
|
|
79fc8541ed |
docs: update template creation docs for template builder (#26993)
## Summary
Update documentation across 9 files to present the template builder as
the primary template creation method, replacing the old starter
templates flow as the default entry point.
The template builder is a guided wizard that lets admins select base
infrastructure, add registry modules, configure variables, and produce
validated Terraform without writing HCL.
## Changes
**Primary docs (significant rewrites):**
- `docs/admin/templates/creating-templates.md`: Added "Using the
template builder" as the first section with full 5-step wizard
documentation, screenshots, airgap/registry notes, and alternative
creation links. Moved CLI starter template flow to its own section.
Fixed "You can the" typo.
- `docs/get-started/index.md`: Rewrote Steps 4-6 to use the builder with
the Docker base template instead of the Coder Quickstart (which is not a
builder base template). Generalized workspace parameter instructions.
- `docs/start/first-template.md`: Rewrote to use the builder. Removed
old starter templates references, TODO notes, typo, and commented-out
sections.
**Secondary docs (targeted edits):**
- `docs/admin/templates/index.md`: Replaced starter templates section
with builder-first "Create a template" section.
- `docs/admin/templates/managing-templates/index.md`: Renamed "Starter
templates" to "Creating templates" pointing to the builder.
- `docs/install/airgap.md`: Added "Template builder" section documenting
`CODER_DISABLE_TEMPLATE_BUILDER` and
`CODER_TEMPLATE_BUILDER_REGISTRY_URL`.
- `docs/tutorials/template-from-scratch.md`: Added TIP callout
recommending the builder. Fixed `coder templates create` -> `coder
templates push` inconsistency.
- `docs/admin/integrations/devcontainers/envbuilder/add-envbuilder.md`:
Updated Dashboard tab to reference the builder and "Upload an existing
template" alternative.
- `docs/about/screenshots.md`: Updated caption and image reference for
template builder.
**Screenshots added:**
- `templatebuilder_01_bases.png` (base selection step)
- `templatebuilder_02_modules.png` (module selection step)
- `templatebuilder_03_module_customization.png` (module settings step)
- `templatebuilder_04_customizations.png` (template customizations step)
<details>
<summary>Implementation plan</summary>
# Plan: Update docs/ for Template Builder Launch
## Summary
The Template Builder is a new guided wizard at `/templates/new/builder`
that lets admins create templates by selecting a base infrastructure
template, composing it with registry modules, configuring variables, and
producing a validated Terraform bundle without writing HCL. The docs
need to be updated to present this as the primary/recommended template
creation path, while preserving the existing paths (upload, CLI,
duplicate) as alternatives.
## Key behavioral facts from the code
- **Route**: `/templates/new/builder` (new), `/templates/new` (old,
still exists)
- **Entry point**: The "New Template" button on the Templates page links
to `/templates/new/builder` when the builder is enabled; otherwise falls
back to `/starter-templates`
- **5-step wizard**:
1. **Select base infrastructure** (e.g., Docker, AWS EC2, Kubernetes)
2. **Base template parameters** (optional, skipped if base has none)
3. **Select modules** (IDE, AI Agent, Source Control, etc.;
multi-select, grouped by category)
4. **Module settings** (optional, skipped if no configurable variables)
5. **Template customizations** (name, display name, description, icon,
organization)
- **Alternative creation links** are shown on step 1: "Start from
scratch", "Upload an existing template", "Browse community templates",
"Use template agent skill"
- **Disabled via**: `CODER_DISABLE_TEMPLATE_BUILDER` env var /
`--disable-template-builder` flag. When disabled, redirects to old
`/templates/new` flow
- **Registry URL override**: `CODER_TEMPLATE_BUILDER_REGISTRY_URL`
(default: `registry.coder.com`)
- **Requires outbound access** to `registry.coder.com` for `terraform
init` at compose time
- **Modules are bundled** with the Coder release binary; the builder
does not fetch metadata from the registry at runtime
- **Sensitive variables** (secrets) are not collected by the builder;
they are deferred to workspace creation time
- **Module conflicts** show a warning but do not block creation
- **One-way**: No re-entry into the builder for existing templates; edit
HCL directly after creation
## Files to update
### Tier 1: Primary creation flow docs (significant rewrites)
#### 1. `docs/admin/templates/creating-templates.md`
**Current state**: Documents three creation paths: "From a starter
template" (primary), "From an existing template", "From scratch
(advanced)".
**Changes**:
- Add a new section **"Using the template builder"** as the first and
primary section (before "From a starter template").
- Describe the 5-step wizard flow: select base infrastructure, configure
base parameters, select modules, configure module settings, set template
customizations.
- Mention that the builder is enabled by default and requires outbound
access to `registry.coder.com`.
- Note that sensitive variables are collected from developers at
workspace creation, not during template building.
- Add a callout about disabling the builder for airgapped deployments
(`CODER_DISABLE_TEMPLATE_BUILDER`).
- Note the `CODER_TEMPLATE_BUILDER_REGISTRY_URL` option for self-hosted
registry mirrors.
- Keep existing "From a starter template", "From an existing template",
and "From scratch" sections largely intact, but reframe them as
alternative paths.
- Update the "From a starter template" Web UI instructions to note the
new entry point routing (the "New Template" button now goes to the
builder when enabled).
- Fix existing typo: "You can the [Coder CLI]" should be "You can use
the [Coder CLI]".
#### 2. `docs/start/first-template.md`
**Current state**: Beginner tutorial walking through creating a template
from the Docker starter template via the old flow. Has a typo (`s` at
end of line 32), commented-out workspace creation section, and TODO
notes.
**Changes**:
- Rewrite steps 2 and 3 to use the Template Builder as the primary path.
- Step 2: Navigate to **Templates**, select **New Template**, which
opens the Template Builder.
- Step 3: Walk through the builder wizard steps (select Docker base,
optionally select modules like code-server, configure template
name/description, create).
- Remove the typo on line 32 (`s`).
- Keep the "Modify your template" section (step 6) intact since it
covers post-creation editing which is unchanged.
- Remove or update the reference to "Starter Templates" as a separate
page since the builder subsumes that entry point.
#### 3. `docs/get-started/index.md`
**Current state**: Quickstart guide. Step 4 says "Select **Templates** →
**New Template**" then pick "Coder Quickstart" from starter templates.
**Changes**:
- Update Step 4 to describe using the Template Builder.
- The flow becomes: Select **Templates** → **New Template** → builder
opens → select **Coder Quickstart** as the base template → optionally
add modules → set name/description → **Create Template**.
- Update the "What just happened?" explanation to mention the builder
composed and validated the Terraform.
- Screenshot reference `create-quickstart-template.png` will need a new
screenshot (note this in the PR; screenshots are out of scope for this
change but should be flagged).
### Tier 2: Secondary references (targeted edits)
#### 4. `docs/admin/templates/index.md`
**Current state**: Overview page mentioning starter templates as the
primary creation path.
**Changes**:
- Update the "Starter templates" section to mention the Template Builder
as the recommended way to create templates, with starter templates
serving as base templates within the builder.
- Update the link to point to the builder section: `[Create a template
with the template
builder](./creating-templates.md#using-the-template-builder)`.
- Update the screenshot reference and caption. The "Starter Templates"
page screenshot may no longer be the first thing admins see.
#### 5. `docs/admin/templates/managing-templates/index.md`
**Current state**: Documents starter templates, editing, updating,
deleting.
**Changes**:
- Update the "Starter templates" section to mention the Template Builder
as the primary creation path, with starter templates available as base
templates within it.
- Update the image reference from `starter-templates.png` if it shows
the old flow.
#### 6. `docs/tutorials/template-from-scratch.md`
**Current state**: Detailed tutorial for writing a template from scratch
with Terraform.
**Changes**:
- Add a brief note at the top recommending the Template Builder for
users who want to create templates without writing Terraform, with a
link to
`docs/admin/templates/creating-templates.md#using-the-template-builder`.
- In section "7. Create the template in Coder" → "Dashboard" tab, update
the UI steps. The "Upload template" option is now accessed via the old
creation flow at `/templates/new` (or through the "Upload an existing
template" link in the builder's alternatives).
- Fix the inconsistency where text says `coder templates create` but the
code block uses `coder templates push`.
#### 7.
`docs/admin/integrations/devcontainers/envbuilder/add-envbuilder.md`
**Current state**: Documents creating envbuilder templates via
Dashboard, CLI, and Registry tabs.
**Changes**:
- In the Dashboard tab, update the instructions. The "Create Template"
button now opens the builder by default. Users need to use the "Upload
an existing template" alternative link or navigate to `/templates/new`
directly.
- Update "From scratch" reference since that option is now an
alternative link in the builder.
- The CLI and Registry tabs remain unchanged.
#### 8. `docs/install/airgap.md`
**Current state**: Documents air-gapped installations. No mention of
Template Builder.
**Changes**:
- Add a note in the relevant section about the Template Builder
requiring outbound access to `registry.coder.com`.
- Document `CODER_DISABLE_TEMPLATE_BUILDER` for fully air-gapped
deployments.
- Document `CODER_TEMPLATE_BUILDER_REGISTRY_URL` for deployments using a
self-hosted registry mirror.
#### 9. `docs/about/screenshots.md`
**Current state**: Contains a caption "Template administrators can
either create a new Template from scratch or choose a Starter Template".
**Changes**:
- Update the caption to mention the Template Builder as the primary
creation method.
- Screenshot reference may need updating (flag for new screenshot).
### Tier 3: Minor/link-only updates
#### 10. `docs/admin/users/organizations.md`
- If it references the old "Create Template" screen with an org picker,
add a note that the Template Builder also includes organization
selection in its final step.
#### 11. `docs/ai-coder/tasks.md`
- If it mentions creating templates, add a passing reference to the
Template Builder as an option.
## Files NOT to update
- `docs/reference/api/templatebuilder.md`: Auto-generated API reference.
Already correct.
- `docs/reference/api/schemas.md`: Auto-generated. Already correct.
- `docs/reference/cli/server.md`: Auto-generated. Already has
`--disable-template-builder` and `--template-builder-registry-url`.
- `docs/reference/cli/templates_create.md`: Already deprecated.
- `docs/reference/cli/templates.md`: No changes needed.
## Implementation order
1. `docs/admin/templates/creating-templates.md` (primary creation docs,
most content)
2. `docs/get-started/index.md` (quickstart)
3. `docs/start/first-template.md` (beginner tutorial)
4. `docs/admin/templates/index.md` (overview)
5. `docs/admin/templates/managing-templates/index.md` (managing
overview)
6. `docs/install/airgap.md` (airgap note)
7. `docs/tutorials/template-from-scratch.md` (from-scratch tutorial)
8. `docs/admin/integrations/devcontainers/envbuilder/add-envbuilder.md`
(envbuilder)
9. `docs/about/screenshots.md` (screenshot captions)
10. Minor link/reference updates in tier 3 files
## Style notes
- Follow the Diataxis framework; keep tutorials as tutorials, reference
as reference.
- Use present tense, active voice, second person.
- Bold for UI elements: **Templates**, **New Template**, **Create
Template**.
- No emdash/endash.
- Do not add screenshots; flag where new screenshots are needed as
comments/TODOs.
- Run `make fmt/markdown` and `make lint/markdown` after all changes.
- Verify all pages are already in `docs/manifest.json` (no new pages
being added, only existing pages being updated).
</details>
> 🤖 Generated by Coder Agents
|
||
|
|
2ea0d5f8ef |
docs: add a Customize your template series under Get started (#26712)
## What Adds a **Customize your template** series under the top-level **Get started** section, at `docs/get-started/customize-your-template/`. These guides extend the single-page Quickstart (added in #26821) with hands-on template customization: - **Add a programming language** — expose a language through a parameter, install it at startup, and offer it as a preset. - **Install your own command-line tools** — install personal tools with Homebrew and mise, and make them persist. - **Clone private repositories** — authenticate workspaces to GitHub with an external-auth data source. ## Changes from the earlier draft This branch was rebased onto the consolidated `/docs/get-started` structure: - Re-homed the series from `tutorials/quickstart/` to `get-started/customize-your-template/`, nested under the new Get started section. - Dropped the Part 1 launch page and the old landing page; the merged Quickstart (`get-started/index.md`, #26821) already covers them. - Archived the dotfiles guide out of the series (tracked as a follow-up to document the dotfiles module as a standalone tutorial) and removed its inbound links. - Renamed the section to **Customize your template**. - Added a Ruby **preset** alongside the Ruby parameter so the parameter and preset choices stay in sync. - Fixed the parameter-change steps to route through **Workspace settings > Parameters**. - Gave each page a **What's next?** step so the series reads as a sequence. ## Still open / follow-ups - Screenshots for the UI steps (handled separately). - The launch step will be revised after the template-builder change ships in the next mainline release. <details> <summary>Decision log</summary> - **Why re-home, not keep `tutorials/quickstart/`:** the Quickstart now lives at `/docs/get-started`, so the series belongs under the same top-level section for a single, coherent entry point. - **Why drop Part 1 here:** the launch content already merged as `get-started/index.md` in #26821; keeping a second copy would duplicate and drift. - **Why archive dotfiles:** it works better as a standalone module tutorial than as a Quickstart step; removed from the series for now and tracked for later. - **Final code fixtures** stay scoped per guide (base template plus that page's edit), so only the language guide's fixture gains the Ruby option and preset. </details> --- Generated by Coder Agents on behalf of @nickvigilante. |
||
|
|
89b0a66079 |
docs: add top-level Get started section and move the Quickstart (#26821)
Add a top-level "Get started" docs section to the nav and move the Quickstart to /docs/get-started, with inbound link updates and the install page TIP pointing to the Quickstart. Filed via Coder Agents on Nick's behalf. |