mirror of
https://github.com/coder/coder.git
synced 2026-11-01 21:13:14 +08:00
Nick Vigilante
61e52532c0
## Problem
Generated reference docs (`docs/reference/cli/*`,
`docs/reference/api/*`) contained raw placeholder and JSON syntax that
came straight from Go CLI help strings and swagger annotations. HTML
renderers treat the angle-bracket tokens (`<team-slug>`, `<uuid>`,
`<KEY>`, etc.) as unknown tags and drop them, so readers see
broken/half-missing text today. The same strings also break MDX parsing.
## Fix
Wrap the placeholder/JSON syntax in backticks **at the source** (Go help
strings and swagger annotation comments), then `make gen`. Rendered docs
now show the placeholders as inline code instead of dropping them.
### Source changes
| File | Placeholder wrapped | Surfaces in |
|------|--------------------|-------------|
| `codersdk/deployment.go` | `` `<organization-name>/<team-slug>` `` |
`cli/server.md`, `coder --help`, settings UI |
| `codersdk/deployment.go` | `` `CODER_AI_GATEWAY_PROVIDER_<N>_*` ``, ``
`CODER_AI_GATEWAY_PROVIDER_<N>_<KEY>` `` | `api/schemas.md` |
| `cli/tokens.go` | `` `<type>:<uuid>` `` | `cli/tokens_create.md`,
`coder --help` |
| `coderd/aitasks.go` | `` `owner:<…>` ``, `` `organization:<…>` ``, ``
`status:<status>` `` | `api/tasks.md` |
| `coderd/exp_chats.go` | `` `pr_status:<…>` `` and sibling filter
tokens | `api/chats.md` |
| `coderd/provisionerdaemons.go`, `coderd/provisionerjobs.go` | ``
`{'tag1':'value1','tag2':'value2'}` `` | `api/organizations.md`,
`api/provisioning.md` |
Everything else in the diff (`coderd/apidoc/*`, `docs/reference/**`,
`*.golden`, `site/src/api/typesGenerated.ts`) is `make gen` output.
## Reviewer notes (the "considered pass" from the ticket)
- **Product-visible:** this changes `coder server --help` and `coder
tokens create --help` output, and the `server-config.yaml` reference
comment. Backticks in terminal help are literal but read fine as
placeholder markers.
- **Settings UI:** the `deployment.go` `Description` also renders in the
deployment settings page. If that field is not Markdown-rendered,
literal backticks will show there. Happy to drop the `deployment.go`
change if you'd rather keep the UI text clean and fix `server.md`
another way.
- **Out of scope here:** `docs/reference/cli/agent-firewall.md`
(`<host>`/`<glob>`) is generated from the external
`github.com/coder/boundary` module, not this repo. It needs an upstream
fix + module bump; not included in this PR.
<details>
<summary>Implementation notes / decision log</summary>
- Scope taken from DOCS-551: source-level backtick pass for generated
reference docs only. Hand-written Markdown fixes are tracked separately
(companion ticket).
- Swagger `@Param` descriptions are Go comments, so the existing `\|`
pipe-escaping in the chats `q` filter is preserved inside the new
backticks (still required for the Markdown table cell to render `|`).
- Verified after `make gen`: generated docs render placeholders as code
spans, table pipes intact; `gofmt` clean; changed Go packages build; no
emdash/endash introduced.
- Deliberately left the `AIProviderConfig` type-level doc comment
untouched because it does not surface in any generated doc (kept the
diff to doc-feeding comments).
</details>
Linear: DOCS-551
---
_Opened by Coder Agents on behalf of @nickvigilante._
---
## Evidence: placeholders dropped on the live docs site
Verified **2026-07-14** against the live site (`coder.com/docs`, i.e.
`main`, pre-merge) by loading each affected page in headless Chrome and
reading the post-hydration DOM (confirmed identical in the raw page
payload). Each simple `<token>` placeholder is parsed as an **empty
custom HTML element**, so the browser renders nothing for it and the
placeholder text disappears from the page.
### What readers see today (before this PR)
| Page (live) | Source Markdown | Rendered on the live site |
|-------------|-----------------|---------------------------|
| [`cli/server`](https://coder.com/docs/reference/cli/server) — OAuth2
GitHub Allowed Teams | `Structured as: <organization-name>/<team-slug>.`
| `Structured as: /.` |
|
[`cli/tokens_create`](https://coder.com/docs/reference/cli/tokens_create)
— `--allow` | `Repeatable allow-list entry (<type>:<uuid>, e.g.
workspace:1234-...).` | `Repeatable allow-list entry (:, e.g.
workspace:1234-...).` |
| [`api/tasks`](https://coder.com/docs/reference/api/tasks) — `q` | `...
status:<status>` | `... status:` (nothing after the colon) |
| [`api/schemas`](https://coder.com/docs/reference/api/schemas) —
AIBridgeConfig (`anthropic`/`bedrock`/`openai`) |
`CODER_AI_GATEWAY_PROVIDER_<N>_*` | `CODER_AI_GATEWAY_PROVIDER__*` |
| [`api/schemas`](https://coder.com/docs/reference/api/schemas) —
AIBridgeConfig (`providers`) | `CODER_AI_GATEWAY_PROVIDER_<N>_<KEY>` |
`CODER_AI_GATEWAY_PROVIDER__` |
[`api/chats`](https://coder.com/docs/reference/api/chats) (`q`) drops
five tokens the same way — `title:<substring>`, `diff_url:<url>`,
`pr:<number>`, `pr_title:<text>`, and the trailing `title:<value>`. The
live parameter description reads (note the dangling `title:`,
`diff_url:`, `pr:`, `pr_title:`):
```text
Search query. Supports title: (case-insensitive, quote multi-word values), archived:bool, has_unread:bool, pr_status:<draft|open|merged|closed> as repeated or comma-separated values, source:<created_by_me|shared_with_me>, diff_url: (quote values containing colons), pr: (exact PR number match), repo:<owner/repo> (case-insensitive substring match against git remote origin or URL), pr_title: (case-insensitive PR title substring). Bare terms are not supported; use title: for title filtering.
```
<details>
<summary>Raw rendered DOM from the live site (headless Chrome,
post-hydration)</summary>
```html
<!-- reference/cli/server -->
Structured as: <organization-name>/<team-slug>.</team-slug></organization-name>
<!-- reference/cli/tokens_create -->
Repeatable allow-list entry (<type>:<uuid>, e.g. workspace:1234-...).</uuid></type>
<!-- reference/api/tasks : only status:<status> drops; the /-containing tokens are escaped and survive -->
Search query for filtering tasks. Supports: owner:<username/uuid/me>, organization:<org-name/uuid>, status:<status></status>
<!-- reference/api/schemas : anthropic / bedrock / openai rows -->
Deprecated: Use Providers with indexed CODER_AI_GATEWAY_PROVIDER_<n>_* env vars instead.</n>
<!-- reference/api/schemas : providers row -->
Providers holds provider instances populated from CODER_AI_GATEWAY_PROVIDER_<n>_<key> env vars and/or the deprecated LegacyOpenAI/LegacyAnthropic/LegacyBedrock fields above.</key></n>
```
The parser auto-inserts closing tags
(`</team-slug></organization-name>`) and lowercases the tag name (`<N>`
becomes `<n>`), leaving `__` where `<N>_` used to be. Every wrapped
placeholder renders correctly as inline code on the [docs preview for
this
branch](https://coder.com/docs/@vigilante%2Fdocs-551-backtick-placeholder-syntax-in-generated-reference-docs-cli/reference/cli/server).
</details>
### Accuracy note — cases that do *not* drop on live
These render fine today, so they are **not** evidence of dropping (the
PR still wraps them for consistency / MDX-safety):
-
[`api/organizations`](https://coder.com/docs/reference/api/organizations)
and
[`api/provisioning`](https://coder.com/docs/reference/api/provisioning):
`{'tag1':'value1','tag2':'value2'}` renders verbatim — curly braces are
not an HTML tag.
- Tokens containing `/` or `|` are escaped by the renderer and stay
visible (as literal `<...>`): `<username/uuid/me>`, `<org-name/uuid>`,
`<owner/repo>`, `<draft|open|merged|closed>`,
`<created_by_me|shared_with_me>`. Backticks still improve their
readability, but they were never dropped.
115 lines
7.1 KiB
Markdown
Generated
115 lines
7.1 KiB
Markdown
Generated
# Provisioning
|
|
|
|
## Get provisioner daemons
|
|
|
|
### Code samples
|
|
|
|
```shell
|
|
# Example request using curl
|
|
curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/provisionerdaemons \
|
|
-H 'Accept: application/json' \
|
|
-H 'Coder-Session-Token: API_KEY'
|
|
```
|
|
|
|
`GET /api/v2/organizations/{organization}/provisionerdaemons`
|
|
|
|
### Parameters
|
|
|
|
| Name | In | Type | Required | Description |
|
|
|----------------|-------|--------------|----------|--------------------------------------------------------------------------------------|
|
|
| `organization` | path | string(uuid) | true | Organization ID |
|
|
| `limit` | query | integer | false | Page limit |
|
|
| `ids` | query | array(uuid) | false | Filter results by job IDs |
|
|
| `status` | query | string | false | Filter results by status |
|
|
| `tags` | query | object | false | Provisioner tags to filter by (JSON of the form `{'tag1':'value1','tag2':'value2'}`) |
|
|
|
|
#### Enumerated Values
|
|
|
|
| Parameter | Value(s) |
|
|
|-----------|---------------------------------------------------------------------------------|
|
|
| `status` | `canceled`, `canceling`, `failed`, `pending`, `running`, `succeeded`, `unknown` |
|
|
|
|
### Example responses
|
|
|
|
> 200 Response
|
|
|
|
```json
|
|
[
|
|
{
|
|
"api_version": "string",
|
|
"created_at": "2019-08-24T14:15:22Z",
|
|
"current_job": {
|
|
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
|
|
"status": "pending",
|
|
"template_display_name": "string",
|
|
"template_icon": "string",
|
|
"template_name": "string"
|
|
},
|
|
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
|
|
"key_id": "1e779c8a-6786-4c89-b7c3-a6666f5fd6b5",
|
|
"key_name": "string",
|
|
"last_seen_at": "2019-08-24T14:15:22Z",
|
|
"name": "string",
|
|
"organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
|
|
"previous_job": {
|
|
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
|
|
"status": "pending",
|
|
"template_display_name": "string",
|
|
"template_icon": "string",
|
|
"template_name": "string"
|
|
},
|
|
"provisioners": [
|
|
"string"
|
|
],
|
|
"status": "offline",
|
|
"tags": {
|
|
"property1": "string",
|
|
"property2": "string"
|
|
},
|
|
"version": "string"
|
|
}
|
|
]
|
|
```
|
|
|
|
### Responses
|
|
|
|
| Status | Meaning | Description | Schema |
|
|
|--------|---------------------------------------------------------|-------------|-----------------------------------------------------------------------------|
|
|
| 200 | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK | array of [codersdk.ProvisionerDaemon](schemas.md#codersdkprovisionerdaemon) |
|
|
|
|
<h3 id="get-provisioner-daemons-responseschema">Response Schema</h3>
|
|
|
|
Status Code **200**
|
|
|
|
| Name | Type | Required | Restrictions | Description |
|
|
|----------------------------|--------------------------------------------------------------------------------|----------|--------------|------------------|
|
|
| `[array item]` | array | false | | |
|
|
| `» api_version` | string | false | | |
|
|
| `» created_at` | string(date-time) | false | | |
|
|
| `» current_job` | [codersdk.ProvisionerDaemonJob](schemas.md#codersdkprovisionerdaemonjob) | false | | |
|
|
| `»» id` | string(uuid) | false | | |
|
|
| `»» status` | [codersdk.ProvisionerJobStatus](schemas.md#codersdkprovisionerjobstatus) | false | | |
|
|
| `»» template_display_name` | string | false | | |
|
|
| `»» template_icon` | string | false | | |
|
|
| `»» template_name` | string | false | | |
|
|
| `» id` | string(uuid) | false | | |
|
|
| `» key_id` | string(uuid) | false | | |
|
|
| `» key_name` | string | false | | Optional fields. |
|
|
| `» last_seen_at` | string(date-time) | false | | |
|
|
| `» name` | string | false | | |
|
|
| `» organization_id` | string(uuid) | false | | |
|
|
| `» previous_job` | [codersdk.ProvisionerDaemonJob](schemas.md#codersdkprovisionerdaemonjob) | false | | |
|
|
| `» provisioners` | array | false | | |
|
|
| `» status` | [codersdk.ProvisionerDaemonStatus](schemas.md#codersdkprovisionerdaemonstatus) | false | | |
|
|
| `» tags` | object | false | | |
|
|
| `»» [any property]` | string | false | | |
|
|
| `» version` | string | false | | |
|
|
|
|
#### Enumerated Values
|
|
|
|
| Property | Value(s) |
|
|
|----------|-------------------------------------------------------------------------------------------------|
|
|
| `status` | `busy`, `canceled`, `canceling`, `failed`, `idle`, `offline`, `pending`, `running`, `succeeded` |
|
|
|
|
To perform this operation, you must be authenticated. [Learn more](authentication.md).
|