Commit Graph
15 Commits
Author SHA1 Message Date
Nick Vigilante 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.
2026-09-28 15:44:10 -04:00
Nick Vigilante 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.
2026-09-22 15:18:40 -04:00
Nick Vigilante 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).
2026-09-08 16:34:00 +00:00
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>
2026-08-03 14:33:01 -04:00
Atif Ali 2b2a5c963a Revert "fix(coderd): explain default GitHub app org visibility on login rejection" (#27388) 2026-07-21 16:17:27 +00:00
Atif Ali 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
2026-07-21 20:43:10 +05:00
Nick Vigilante 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.*
2026-07-15 14:07:09 -04:00
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>
2025-05-29 15:38:45 +00:00
Edward AngertandEdwardAngert 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>
2025-04-14 17:03:25 +05:00
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>
2025-04-05 21:44:13 -04:00
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>
2025-03-10 16:58:20 -04:00
Hugo Dutka 0f4f6bd147 docs: describe default sign up behavior with GitHub (#16765)
Document the sign up behavior with the default GitHub OAuth2 app.
2025-03-03 13:23:12 +01:00
Hugo Dutka 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.
2025-03-03 12:31:56 +01:00
Muhammad Atif AliandEdward Angert 94f5d52fdc chore: adopt markdownlint and markdown-table-formatter for *.md (#15831)
Co-authored-by: Edward Angert <EdwardAngert@users.noreply.github.com>
2025-01-03 13:12:59 +00:00
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>
2024-10-05 10:52:04 -05:00