mirror of
https://github.com/coder/coder.git
synced 2026-11-22 03:18:31 +08:00
90948802e2439d2641f392e6229dd058a1dcafe3
15
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
d40e24cf7d |
docs: nest the CLI reference by subcommand (#29956)
## Summary Nests the CLI reference by subcommand so the Command Line sidebar collapses from 156 flat entries to 49 top-level verbs. Each page's URL follows the invocation, its page title is the full command as inline code, and its sidebar label is only its own verb as inline code. | | Before | After | | --- | --- | --- | | File | `docs/reference/cli/oauth2-provider_dcr_disable.md` | `docs/reference/cli/oauth2-provider/dcr/disable.md` | | URL | `/reference/cli/oauth2-provider_dcr_disable` | `/reference/cli/oauth2-provider/dcr/disable` | | Page title (front matter) | `oauth2-provider dcr disable` | `` `coder oauth2-provider dcr disable` `` | | Sidebar label (manifest) | `oauth2-provider dcr disable` | `` `disable` `` | Resolves DOCS-140 (coder/coder half). Also fixes the Makefile part of DOCS-1073 / DOCS-912, which this change depends on. ## Changes - `scripts/clidocgen`: pages nest by command path. A command with visible subcommands becomes its directory's `index.md`, so `oauth2-provider/index.md` and `oauth2-provider/dcr/index.md` sit above `oauth2-provider/dcr/disable.md`. Subcommand table links are relative to the parent page. - `scripts/clidocgen`: the manifest "Command Line" section is built from the command tree (nested, sorted by name, hidden commands skipped) instead of a flat list. The redundant `coder` child that pointed back at `reference/cli/index.md` is gone. - `Makefile`: the CLI rule now replaces `docs/reference/cli/` wholesale, so stale pages get removed. The manifest rule now runs `clidocgen -manifest-only` on top of the API staging manifest, so the CLI nav is generated instead of edited by hand. As a result, the nine pages that had no nav entry (`ai-gateway*`, `secret enable/disable`, `server fix-oidc-links`) now have one. - `scripts/configdocgen` and 48 prose pages: links point at the new paths (for example `reference/cli/server.md` is now `reference/cli/server/index.md`). ## How to review/QA this PR - `docs/reference/cli/**/*` (approximately 190 pages): Each of these pages are generated automatically. Some pages appear deleted, and some pages appear new. Every deleted page corresponds to a new page somewhere else, so no information is being deleted. The docs in this section should adhere to the following, so a test in the build preview for each of these items should be satisfactory: - [ ] Each subcommand of a command gets nested as a child instead of being displayed as a flat list. - [ ] Each parent command is stored in an `index.md` file. - [ ] The title of each page inside the page should now feature the full `coder XYZ` command. - [ ] The title of each page inside the page should now be formatted as inline code. - [ ] The title of each page in the sidebar should be the most granular subcommand of the whole command string (if the page's title is `coder ai-gateway keys create`, the sidebar label is `create`). - [ ] The title of each page in the sidebar should now be formatted as inline code. - [ ] The page slug for each page is now the most granular subcommand. - [ ] All links now point to the correct page. - `docs/manifest.json`: The changes here reflect the updated structure of the `docs/reference/cli` section. - `docs/**/*.md` outside of `docs/reference/cli/**/*` (approximately 50 pages): The extent of the changes in these pages are just updating the paths to point to the new page locations. - [ ] The links on the page all point to the correct new path in `docs/reference/cli`. - `scripts/clidocgen` (4 files): This is the Go code responsible for generating everything inside of `docs/reference/cli/**/*`. A typical code review here should be satisfactory. - `scripts/configdocgen` (2 files): these two files just have updates to the raw `.md` path used by `docs/admin/setup/configuration-reference.md` and updates the tests to reflect that. - `Makefile`: This updates the `make` targets for generating the CLI docs to fit the new structure. ## Merge ordering Without the renderer PRs deployed, both docs sites show literal backticks in titles and sidebar labels. Without the redirects, the old flat URLs return 404. 1. Deploy before merging this PR: coder/docs-engine#176 (beta-docs renders these titles as inline code) and coder/coder.com#1111 (classic docs renders them as inline code). Both are safe to ship first, because titles without backticks render as before. 2. Merge this PR. 3. Merge coder/coder.com#1112 (redirects from the old flat URLs) only once this content reaches the mainline release branch that serves unversioned `/docs`. ## Testing - `go test ./scripts/clidocgen/ ./scripts/configdocgen/ ./scripts/docshtmlcheck/`: pass. New tests cover page paths, subcommand links, the nested manifest, and front matter quoting. - `make docs/reference/cli/index.md docs/manifest.json docs/admin/setup/configuration-reference.md`, then a forced rerun: the second run produced no diff. - Checked the manifest: all 164 CLI entries resolve to a file, no page is missing a nav entry, and everything outside "Command Line" is byte-identical. - Relative `.md` links across `docs/`: 0 broken, same as `main`. - `make pre-commit` and `make pre-push`: pass. On earlier pre-push attempts, different unrelated vitest files timed out under host load. Those files pass when run alone, and the final push passed with `PARALLEL_JOBS=1`. <details> <summary>Implementation plan and decision log</summary> **Goal (from DOCS-140 and the requester):** URLs follow the command hierarchy. Pages are titled with the full command, and sidebar entries with the last verb only. Both are formatted as inline code. **Contract with the renderers:** a title wrapped entirely in one pair of backticks (``^`[^`]+`$``) renders as inline code. Plain-text consumers (`<title>`, meta, search, llms corpus) strip the backticks. Page title comes from front matter `title`, and the sidebar label from the manifest node `title`. **Decisions** - A parent command is `dir/index.md` rather than a sibling `dir.md`. The root CLI page is already `index.md`, and both docs-engine and the legacy coder.com renderer map `x/index.md` to `/x`. - The manifest is built from the command tree, not from the written files, so ordering is deterministic and the nesting matches the pages exactly. - The manifest discard bug (DOCS-1073 item 1) is fixed here, because without that fix the generated nested manifest would never reach the tree. DOCS-1073 items 2 through 4 (a prose fix and a hidden-command policy) are out of scope. - `-manifest-only` keeps the existing parallel `make gen` layout: the API rule still owns `_gen/manifest-staging.json`, and CLI regeneration doesn't retrigger swag. - The renderer and redirect work lives in the companion PRs in coder/docs-engine and coder/coder.com. It is linked above and not duplicated here. </details> --- > [!NOTE] > Generated by Coder Agents on behalf of @nickvigilante. |
||
|
|
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). |
||
|
|
ba4779fc87 |
docs: lead with env vars in admin docs and add configuration reference (#26824)
## What & why Admin/setup docs lead with `coder server --flag` examples, but most operators configure Coder through `CODER_*` environment variables (system service, container, or Helm chart). There is no single page mapping a setting to its env var, CLI flag, YAML key, and default, so searching the docs for an env var name such as `CODER_PG_CONNECTION_URL` returns nothing. This adds a generated configuration reference and begins shifting admin docs to lead with the environment-variable form. ## Changes - **Generated configuration reference** (`docs/admin/setup/configuration-reference.md`): a searchable, per-setting list of every visible deployment option. Each option is a heading (grouped and nested by serpent group) followed by its description and the environment variable, CLI flag, YAML key, and default that apply to it. Generated from `codersdk.DeploymentValues` so it stays in sync. - **Generator + `make gen` wiring** (`scripts/configdocgen/`): new binary plus a Makefile target and `GEN_FILES` entry, mirroring the existing `clidocgen` / `auditdocgen` pattern. Output is host-independent (same env normalization as `clidocgen`). - **Demo conversion** (`docs/admin/users/github-auth.md`): inverted to lead with the `/etc/coder.d/coder.env` env-var form; the CLI-flag form becomes a closing note that links to the reference. H2 slugs preserved. - **Style guide** (`.claude/docs/DOCS_STYLE_GUIDE.md`): documents the env-var-first convention for admin/setup docs. - **Navigation**: manifest entry under Administration → Setup, plus a TIP callout on the setup index. ## Risk Docs + gen pipeline only; no runtime change. The page is regenerated by `make gen`; the `gen` and `check-docs` CI checks pass. ## Follow-up Several other admin pages still lead with flag walls. Recommend sweeping them incrementally in separate PRs rather than expanding scope here. <details> <summary>Implementation notes (provenance, conflict resolution, verification)</summary> - Continues prior work by @aslilac and @bpmct from the `kayla/docs-env-vars-first` branch. Both original commits are cherry-picked here with authorship preserved. - Rebased onto current `main`. Resolved two `Makefile` conflicts where `main` had since added the `feature-stages.md` gen target at the same locations; kept both targets (union) in `GEN_FILES`, `gen/mark-fresh`, and the recipe block. - The original branch's checked-in page predated recent `codersdk.DeploymentValues` changes, so it was **regenerated** against current `main` (adds `CODER_SCIM_USE_LEGACY`, the `Networking / Cluster` section with `CODER_CLUSTER_HOST`, `CODER_BOUNDARY_LOG_RETENTION`, and the AI Gateway description rename). The `gen` CI check enforces this stays current. - Fixed flag-link anchors for short-form flags (`--config`, `--log-filter`): the generator derives the anchor from `FlagShorthand` to match `clidocgen`'s heading (e.g. `#-l---log-filter`). - `linkspector` ignores the AWS Bedrock base URL that appears as an illustrative `<region>` placeholder in an option description, consistent with the existing `openai.com` ignore patterns. </details> <details> <summary>Configuration reference layout (2026-07-08 update)</summary> Reworked the reference from a wide table into a nested, per-setting list so it fits without horizontal scrolling and stops repeating the group name in every heading: - **List, not table.** Each option renders as a heading, its description, and a bullet list of only the configuration methods that apply to it (non-applicable methods are omitted instead of shown as `-`). - **Nested sections.** Sections nest by the serpent group hierarchy, so `Email / Email Authentication` becomes `Email` (h2) with an `Email authentication` (h3) subsection instead of a redundant flat title. - **Shorter, sentence-case headings.** The redundant group prefix is stripped from each option name and the remainder is lowercased to sentence case, preserving acronyms and mixed-case tokens (`URL`, `TLS`, `OAuth2`, `GitHub`) plus a small proper-noun allowlist (`Coder`, `Terraform`, `Honeycomb`, `Anthropic`, `Bedrock`, ...). Example: `AI Gateway Send Actor Headers` becomes `Send actor headers`. - **Deprecated options** sort to the end of each section and lead with an emphasized **Deprecated** marker. Headings stay clean (no `(deprecated)` suffix) so their anchors remain stable. - **Section intros** render from a group's `Description` when the source defines one (e.g. DERP); no hand-maintained prose or links are introduced. All transformations run in pure Go at `make gen` time (no AI at generation time). Generation is idempotent, and `markdownlint` and `golangci-lint` both pass. </details> --- 🤖 Opened by Coder Agents on behalf of @nickvigilante. Continues work by @aslilac and @bpmct. --------- Co-authored-by: Kayla (via Coder Agents) <kayla@coder.com> Co-authored-by: Coder Agents <noreply@coder.com> Co-authored-by: Ben Potter <me@bpmct.net> |
||
|
|
2b2a5c963a | Revert "fix(coderd): explain default GitHub app org visibility on login rejection" (#27388) | ||
|
|
48e9bb3391 |
fix(coderd): explain default GitHub app org visibility on login rejection (#27374)
## Problem On a fresh deployment with no custom GitHub OAuth app, Coder falls back to the default Coder-managed GitHub app. That app can only see organization memberships in organizations where it has been installed. If `CODER_OAUTH2_GITHUB_ALLOWED_ORGS` is set but the app isn't installed in the allowed organizations, the membership list comes back empty and every login, including the first admin login, is rejected with a bare "You aren't a member of the authorized Github organizations!" with no hint about the actual cause. This leaves fresh deployments in an apparently broken state. ## Fix * Append a remediation hint to the login rejection when the default provider is configured, pointing at the [app installation page](<https://github.com/apps/coder/installations/select_target>) and at configuring a custom GitHub OAuth app. * Log a startup warning when the default provider is combined with `CODER_OAUTH2_GITHUB_ALLOWED_ORGS`, listing the allowed orgs and the install URL. * Document the installation requirement next to the `CODER_OAUTH2_GITHUB_ALLOWED_ORGS` step in the GitHub auth docs. Access-control behavior is unchanged; the org check still rejects logins as before, it just explains why and how to fix it. ## Testing * New `TestUserOAuth2Github/NotInAllowedOrganizationDefaultProvider` asserts the hint appears when `DefaultProviderConfigured` is set; the existing `NotInAllowedOrganization` subtest asserts it does not leak into the custom-app path. Fixes coder/coder#17752 |
||
|
|
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.* |
||
|
|
345001ffd1 |
docs: update the GitHub Auth section (#17769)
Addresses https://github.com/coder/coder/issues/17752 [preview](https://coder.com/docs/@hugodutka%2Fgithub%2Dauth%2Dorg%2Ddocs/admin/users/github-auth) --------- Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com> Co-authored-by: Edward Angert <EdwardAngert@users.noreply.github.com> |
||
|
|
34752fa148 |
docs: add note about sign in with GitHub button should be hidden when flow is disabled (#17367)
Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com> |
||
|
|
f475555d06 |
docs: document that default GitHub app requires device flow (#17162)
## Issue Closes #16824 Document that the default GitHub authentication app provided by Coder requires device flow, and that this behavior cannot be overridden. ## Changes Made Claude updated the GitHub authentication documentation to: 1. Add a prominent warning in the Default Configuration section explaining that the default GitHub app requires device flow and ignores the `CODER_OAUTH2_GITHUB_DEVICE_FLOW` setting 2. Clarify the Device Flow section to indicate that: - Device flow is always enabled for the default GitHub app - Device flow is optional for custom GitHub OAuth apps - The `CODER_OAUTH2_GITHUB_DEVICE_FLOW` setting is ignored when using the default app [preview](https://coder.com/docs/@16824-github-device-flow/admin/users/github-auth) <sub>🤖 Generated with [Claude Code](https://claude.ai/code)</sub> --------- Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com> Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: M Atif Ali <atif@coder.com> |
||
|
|
101b62dc3e |
docs: convert alerts to use GitHub Flavored Markdown (GFM) (#16850)
followup to #16761 thanks @lucasmelin ! + thanks: @ethanndickson @Parkreiner @matifali @aqandrew - [x] update snippet - [x] find/replace - [x] spot-check [preview](https://coder.com/docs/@16761-gfm-callouts/admin/templates/managing-templates/schedule) (and others) --------- Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com> Co-authored-by: M Atif Ali <atif@coder.com> |
||
|
|
0f4f6bd147 |
docs: describe default sign up behavior with GitHub (#16765)
Document the sign up behavior with the default GitHub OAuth2 app. |
||
|
|
a5842e5ad1 |
docs: document default GitHub OAuth2 configuration and device flow (#16663)
Document the changes made in https://github.com/coder/coder/pull/16629 and https://github.com/coder/coder/pull/16585. |
||
|
|
94f5d52fdc |
chore: adopt markdownlint and markdown-table-formatter for *.md (#15831)
Co-authored-by: Edward Angert <EdwardAngert@users.noreply.github.com> |
||
|
|
419eba5fb6 |
docs: restructure docs (#14421)
Closes #13434 Supersedes #14182 --------- Co-authored-by: Ethan <39577870+ethanndickson@users.noreply.github.com> Co-authored-by: Ethan Dickson <ethan@coder.com> Co-authored-by: Ben Potter <ben@coder.com> Co-authored-by: Stephen Kirby <58410745+stirby@users.noreply.github.com> Co-authored-by: Stephen Kirby <me@skirby.dev> Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com> Co-authored-by: Edward Angert <EdwardAngert@users.noreply.github.com> |