Nick Vigilante
c84aa564ba
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.*
4.6 KiB
Organizations (Premium)
Note
Organizations requires a Premium license. For more details, contact your account team.
Organizations can be used to segment and isolate resources inside a Coder deployment for different user groups or projects.
Example
Here is an example of how one could use organizations to run a Coder deployment with multiple platform teams, all with unique resources:
For more information about how to use organizations, visit the organizations best practices guide.
The default organization
All Coder deployments start with one organization called coder. All new users
are added to this organization by default.
To edit the organization details, select Admin settings from the top bar, then Organizations:
From there, you can manage the name, icon, description, users, and groups:
Additional organizations
Any additional organizations have unique admins, users, templates, provisioners, groups, and workspaces. Each organization must have at least one dedicated provisioner since the built-in provisioners only apply to the default organization.
You can configure organization/role/group sync from your identity provider to avoid manually assigning users to organizations.
How to create an organization
Prerequisites
- Coder v2.16+ deployment with Premium license and Organizations enabled (contact your account team) for more details.
- User with
Ownerrole
1. Create the organization
To create a new organization:
-
Select Admin settings from the top bar, then Organizations.
-
Select the current organization to expand the organizations dropdown, then select Create Organization:
-
Enter the details and select Save to continue:
In this example, we'll create the data-platform org.
Next deploy a provisioner and template for this organization.
2. Deploy a provisioner
Provisioners are organization-scoped and are responsible for executing Terraform/OpenTofu to provision the infrastructure for workspaces and testing templates. Before creating templates, we must deploy at least one provisioner as the built-in provisioners are scoped to the default organization.
-
Using Coder CLI, run the following command to create a key that will be used to authenticate the provisioner:
coder provisioner keys create data-cluster-key --org data-platform Successfully created provisioner key data-cluster! Save this authentication token, it will not be shown again. < key omitted > -
Start the provisioner with the key on your desired platform.
In this example, start the provisioner using the Coder CLI on a host with Docker. For instructions on using other platforms like Kubernetes, see our provisioner documentation.
export CODER_URL=https://<your-coder-url> export CODER_PROVISIONER_DAEMON_KEY=<key> coder provisionerd start --org <org-name>
3. Create a template
Once you've started a provisioner, you can create a template. You'll notice the Create Template screen now has an organization dropdown:
4. Add members
From Admin settings, select Organizations, then Members to add members to your organization. Once added, members will be able to see the organization-specific templates.
5. Create a workspace
Now, users in the data platform organization will see the templates related to their organization. Users can be in multiple organizations.
