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.0 KiB
Working with templates
You create and edit Coder templates as
Terraform configuration files (.tf) and
any supporting files, like a README or configuration files for other services.
Who creates templates?
The Template Admin role (and above) can create templates. End users, like developers, create workspaces from them. Templates can also be managed with git, allowing any developer to propose changes to a template.
You can give different users and groups access to templates with role-based access control.
Creating templates
The template builder is the recommended way to create templates. It guides you through selecting a base infrastructure template, adding modules (IDEs, tools, integrations), and configuring template settings without writing Terraform.
Starter templates for common cloud providers (AWS, Azure) and orchestrators (Kubernetes, Docker) are available as base templates within the builder. You can modify the generated template to use your own images, VPC, cloud credentials, and so on. Coder supports all Terraform resources and properties.
If you prefer to use Coder on the
command line, use coder templates init to
pull a starter template, then coder templates push to upload it.
Coder starter templates are also available on our GitHub repo.
Community Templates
As well as Coder's starter templates, you can see a list of community templates by our users here.
Editing templates
Our templates are meant to be modified for your use cases. You can edit any template's files directly in the Coder dashboard.
If you'd prefer to use the CLI, use coder templates pull, edit the template
files, then coder templates push.
Tip
Even if you are a Terraform expert, we suggest reading our guided tour of a template.
Updating templates
Coder tracks a template's versions, keeping all developer workspaces up-to-date. When you publish a new version, developers are notified to get the latest infrastructure, software, or security patches. Learn more about change management.
Template update policies
Note
Template update policies are a Premium feature. Learn more.
Licensed template admins may want workspaces to always remain on the latest version of their parent template. To do so, enable Template Update Policies in the template's general settings. All non-admin users of the template will be forced to update their workspaces before starting them once the setting is applied. Workspaces which leverage autostart or start-on-connect will be automatically updated on the next startup.
Delete templates
You can delete a template using both the coder CLI and UI. Only template admins and owners can delete a template, and the template must not have any running workspaces associated to it.
In the UI, navigate to the template you want to delete, and select the dropdown in the right-hand corner of the page to delete the template.
Using the CLI, login to Coder and run the following command to delete a template:
coder templates delete <template-name>
Next steps
- Image management
- Dev Containers integration (recommended)
- Envbuilder (alternative for environments without Docker)
- Change management