mirror of
https://github.com/coder/coder.git
synced 2026-09-21 20:51:01 +08:00
fix(docs): replace invalid </br> tags and format swallowed placeholder URL (#27174)
## Summary Fixes two classes of invalid/broken HTML in hand-written docs. Both are visible problems in today's rendered docs, independent of any docs-engine work. 1. **`</br>` is not a real HTML tag.** `br` is a void element with no closing form; browsers error-correct `</br>`, but it is invalid HTML. Replaced all 15 usages with `<br />` across: - `docs/admin/templates/extending-templates/dynamic-parameters.md` - `docs/admin/users/idp-sync.md` - `docs/tutorials/best-practices/organizations.md` 2. **Browser-swallowed placeholder URL.** In `docs/ai-coder/github-to-tasks.md`, `https://<your-coder-url>/settings/external-auth` was unformatted, so HTML renderers parse `<your-coder-url>` as an unknown tag and drop it. The live docs currently render the broken text `re-authenticate at https:///settings/external-auth`. Wrapped in backticks, matching every other instance in the same file. Table realignment noise in the diff is from `fmt/markdown` (`<br />` is one character wider than `</br>`). A repo-wide grep confirms no remaining `</br>` and no other unformatted `https://<placeholder>` URLs in prose (other hits are inside code fences or already backticked). The equivalent placeholder issues in **generated** reference docs (CLI help strings, swagger annotations) are intentionally out of scope and tracked separately in [DOCS-551](https://linear.app/codercom/issue/DOCS-551/backtick-placeholder-syntax-in-generated-reference-docs-cli-help). Tracking issue: [DOCS-550](https://linear.app/codercom/issue/DOCS-550/fix-invalid-br-tags-and-browser-swallowed-placeholder-url-in-hand) --- Created by Coder Agents on behalf of @nickvigilante.
This commit is contained in:
Nick Vigilante
@@ -120,16 +120,16 @@ The **Options** column in the table below indicates whether the form type suppor
|
||||
When supported, you can specify options using one or more `option` blocks in your parameter definition,
|
||||
where each option has a `name` (displayed to the user) and a `value` (used in your template logic).
|
||||
|
||||
| Form Type | Parameter Types | Options | Notes |
|
||||
|----------------|--------------------------------------------|---------|------------------------------------------------------------------------------------------------------------------------|
|
||||
| `radio` | `string`, `number`, `bool`, `list(string)` | Yes | Radio buttons for selecting a single option with all choices visible at once. </br>The classic parameter option. |
|
||||
| `dropdown` | `string`, `number` | Yes | Choose a single option from a searchable dropdown list. </br>Default for `string` or `number` parameters with options. |
|
||||
| `multi-select` | `list(string)` | Yes | Select multiple items from a searchable dropdown list. </br>Selected items are shown as removable chips. |
|
||||
| `tag-select` | `list(string)` | No | Default for `list(string)` parameters without options. |
|
||||
| `input` | `string`, `number` | No | Standard single-line text input field. </br>Default for `string/number` parameters without options. |
|
||||
| `textarea` | `string` | No | Multi-line text input field for longer content. |
|
||||
| `slider` | `number` | No | Slider selection with min/max validation for numeric values. |
|
||||
| `checkbox` | `bool` | No | A single checkbox for boolean parameters. </br>Default for boolean parameters. |
|
||||
| Form Type | Parameter Types | Options | Notes |
|
||||
|----------------|--------------------------------------------|---------|-------------------------------------------------------------------------------------------------------------------------|
|
||||
| `radio` | `string`, `number`, `bool`, `list(string)` | Yes | Radio buttons for selecting a single option with all choices visible at once. <br />The classic parameter option. |
|
||||
| `dropdown` | `string`, `number` | Yes | Choose a single option from a searchable dropdown list. <br />Default for `string` or `number` parameters with options. |
|
||||
| `multi-select` | `list(string)` | Yes | Select multiple items from a searchable dropdown list. <br />Selected items are shown as removable chips. |
|
||||
| `tag-select` | `list(string)` | No | Default for `list(string)` parameters without options. |
|
||||
| `input` | `string`, `number` | No | Standard single-line text input field. <br />Default for `string/number` parameters without options. |
|
||||
| `textarea` | `string` | No | Multi-line text input field for longer content. |
|
||||
| `slider` | `number` | No | Slider selection with min/max validation for numeric values. |
|
||||
| `checkbox` | `bool` | No | A single checkbox for boolean parameters. <br />Default for boolean parameters. |
|
||||
|
||||
### Available Styling Options
|
||||
|
||||
@@ -162,7 +162,7 @@ Not all styling attributes are supported by all form types, use the reference be
|
||||
| Styling Option | Compatible parameter types | Compatible form types | Notes |
|
||||
|----------------|----------------------------|-----------------------|-------------------------------------------------------------------------------------|
|
||||
| `disabled` | All parameter types | All form types | Disables the form control when `true`. |
|
||||
| `placeholder` | `string` | `input`, `textarea` | Sets placeholder text. </br>This is overwritten by user entry. |
|
||||
| `placeholder` | `string` | `input`, `textarea` | Sets placeholder text. <br />This is overwritten by user entry. |
|
||||
| `mask_input` | `string`, `number` | `input`, `textarea` | Masks inputs as asterisks (`*`). Used to cosmetically hide token or password entry. |
|
||||
|
||||
## Use Case Examples
|
||||
|
||||
@@ -397,11 +397,11 @@ settings, a user's memberships will update when they log out and log back in.
|
||||
|
||||
Analyzing the JSON payload:
|
||||
|
||||
| Field | Explanation |
|
||||
|:----------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| field | If this field is the empty string `""`, then org-sync is disabled. </br> Org memberships must be manually configured through the UI or API. |
|
||||
| mapping | Mapping takes a claim from the IdP, and associates it with 1 or more organizations by UUID. </br> No validation is done, so you can put UUID's of orgs that do not exist (a noop). The UI picker will allow selecting orgs from a drop down, and convert it to a UUID for you. |
|
||||
| organization_assign_default | This setting exists for maintaining backwards compatibility with single org deployments, either through their upgrade, or in perpetuity. </br> If this is set to 'true', all users will always be assigned to the default organization regardless of the mappings and their IdP claims. |
|
||||
| Field | Explanation |
|
||||
|:----------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| field | If this field is the empty string `""`, then org-sync is disabled. <br /> Org memberships must be manually configured through the UI or API. |
|
||||
| mapping | Mapping takes a claim from the IdP, and associates it with 1 or more organizations by UUID. <br /> No validation is done, so you can put UUID's of orgs that do not exist (a noop). The UI picker will allow selecting orgs from a drop down, and convert it to a UUID for you. |
|
||||
| organization_assign_default | This setting exists for maintaining backwards compatibility with single org deployments, either through their upgrade, or in perpetuity. <br /> If this is set to 'true', all users will always be assigned to the default organization regardless of the mappings and their IdP claims. |
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
@@ -261,6 +261,6 @@ If this returns 401 Unauthorized or Bad credentials, the token has expired.
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. Have the user re-authenticate at https://<your-coder-url>/settings/external-auth
|
||||
1. Have the user re-authenticate at `https://<your-coder-url>/settings/external-auth`
|
||||
1. Verify the GitHub provider shows "Authenticated" with a green checkmark
|
||||
1. Re-trigger the workflow to create a new task with a fresh token
|
||||
|
||||
@@ -45,15 +45,15 @@ deployed with Coder and has 1000 users in production. Today, MegaCo has a single
|
||||
(default) organization and a central platform team but is evaluating whether to
|
||||
use organizations for several use cases.
|
||||
|
||||
| **Use Case** | **Description** | **Good fit for organizations?** |
|
||||
|--------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------|
|
||||
| Mergers and acquisitions | Raptix, a 180-person startup recently acquired by MegaCo, has an independent cloud account, platform team, and Terraform modules and pipelines for deploying their code. They want to use Coder. | ✅ Organizations |
|
||||
| Independent cloud-native teams that manage their namespaces, images, and/or clusters | MegaCo has six teams responsible for their own dev, staging, and production Kubernetes clusters and frequently deploy & test their work with `kubectl` and `helm`.</br></br>They wish to hook up Coder to their cluster so they can write and manage IDE templates for connecting to the cluster with their IDE | ✅ Organizations |
|
||||
| Java monolith | MegaCo has identified that anyone developing the Java monolith is best served with a VM instead of a container/cloud-native environment.</br></br>However, the Java team is supported by MegaCo's central platform team. | ❌ Use instead:</br>A separate template and/or groups |
|
||||
| Off-shore contractors | MegaCo employs off-shore contractors but has not onboarded them onto Coder due to privacy concerns, data sovereignty rules, and latency considerations.</br></br>They considered a minimal, localized second deployment of Coder, but decided against it due to maintenance overhead. | ✅ Organizations + Workspace Proxies |
|
||||
| Dev teams | Dev teams often need to bring their requirements for dev environments, such as specific repositories and tools | ❌ Use instead:</br>Parameters, dev containers, and/or groups |
|
||||
| ML Platform Team & ML Developers | MegaCo's data platform team maintains a homegrown "MLBox" product for data environments with a GPU, Jupyter, etc.</br></br>This team is interested in migrating to Coder for improved cost-saving and auditing of environments, but they need to hook up their own cluster and cloud accounts. They also want their templates only to be accessible to a specific set of users. | ✅ Organizations |
|
||||
| Supporting developers in various regions | MegaCo's central platform team supports developers connecting from the East Coast, the West Coast, and Australia. These developers are working on the same projects but need low-latency access to their environments. | ❌ Use instead:</br>Provisioners and workspace proxies to support multiple regions on a single template |
|
||||
| **Use Case** | **Description** | **Good fit for organizations?** |
|
||||
|--------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
|
||||
| Mergers and acquisitions | Raptix, a 180-person startup recently acquired by MegaCo, has an independent cloud account, platform team, and Terraform modules and pipelines for deploying their code. They want to use Coder. | ✅ Organizations |
|
||||
| Independent cloud-native teams that manage their namespaces, images, and/or clusters | MegaCo has six teams responsible for their own dev, staging, and production Kubernetes clusters and frequently deploy & test their work with `kubectl` and `helm`.<br /><br />They wish to hook up Coder to their cluster so they can write and manage IDE templates for connecting to the cluster with their IDE | ✅ Organizations |
|
||||
| Java monolith | MegaCo has identified that anyone developing the Java monolith is best served with a VM instead of a container/cloud-native environment.<br /><br />However, the Java team is supported by MegaCo's central platform team. | ❌ Use instead:<br />A separate template and/or groups |
|
||||
| Off-shore contractors | MegaCo employs off-shore contractors but has not onboarded them onto Coder due to privacy concerns, data sovereignty rules, and latency considerations.<br /><br />They considered a minimal, localized second deployment of Coder, but decided against it due to maintenance overhead. | ✅ Organizations + Workspace Proxies |
|
||||
| Dev teams | Dev teams often need to bring their requirements for dev environments, such as specific repositories and tools | ❌ Use instead:<br />Parameters, dev containers, and/or groups |
|
||||
| ML Platform Team & ML Developers | MegaCo's data platform team maintains a homegrown "MLBox" product for data environments with a GPU, Jupyter, etc.<br /><br />This team is interested in migrating to Coder for improved cost-saving and auditing of environments, but they need to hook up their own cluster and cloud accounts. They also want their templates only to be accessible to a specific set of users. | ✅ Organizations |
|
||||
| Supporting developers in various regions | MegaCo's central platform team supports developers connecting from the East Coast, the West Coast, and Australia. These developers are working on the same projects but need low-latency access to their environments. | ❌ Use instead:<br />Provisioners and workspace proxies to support multiple regions on a single template |
|
||||
|
||||
## How to migrate to organizations
|
||||
|
||||
|
||||
Reference in New Issue
Block a user