mirror of https://github.com/coder/coder.git synced 2026-09-24 15:04:27 +08:00

Files

T

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

2.8 KiB

Raw Blame History

Workspace Startup Coordination Troubleshooting

Note

This feature is experimental and may change without notice in future releases.

Test Sync Availability

From a workspace terminal, test if sync is working using coder exp sync ping:

coder exp sync ping

If sync is working, expect the output to be Success.
Otherwise, you will see an error message similar to the below:

error: connect to agent socket: connect to socket: dial unix /tmp/coder-agent.sock: connect: permission denied

Check Unit Status

You can check the status of a specific unit using coder exp sync status:

coder exp sync status git-clone

If the unit exists, you will see output similar to the below:

# coder exp sync status git-clone
Unit: git-clone
Status: completed
Ready: true

If the unit is not known to the agent, you will see output similar to the below:

# coder exp sync status doesnotexist
Unit: doesnotexist
Status: not registered
Ready: true

Dependencies:
No dependencies found

List All Units

If you are unsure which units are registered, or want a quick overview of every unit's state, use coder exp sync list:

coder exp sync list

This displays all registered units, their statuses, and whether they are ready to start:

UNIT           STATUS     READY
git-clone      completed  true
env-setup      started    true
ide-configure  pending    false

You can also get JSON output for scripting:

coder exp sync list --output json

Common Issues

Workspace startup script hangs

If the workspace startup scripts appear to 'hang', one or more of your startup scripts may be waiting for a dependency that never completes.

Inside the workspace, review /tmp/coder-script-*.log for more details on your script's execution.

Tip: add set -x to the top of your script to enable debug mode and update/restart the workspace.
Review your template and verify that coder exp sync complete <unit> is called after the script completes e.g. with an exit trap.
List all units to identify which ones are blocked: coder exp sync list.
View the unit status using coder exp sync status <unit>.

Workspace startup scripts fail

If the workspace startup scripts fail:

Review /tmp/coder-script-*.log inside the workspace for script errors.
Verify the Coder CLI is available in $PATH inside the workspace:
```
command -v coder
```

Cycle detected

If you see an error similar to the below in your startup script logs, you have defined a cyclic dependency:

error: declare dependency failed: cannot add dependency: adding edge for unit "bar": failed to add dependency
adding edge (bar -> foo): cycle detected

To fix this, review your dependency declarations and redesign them to remove the cycle. It may help to draw out the dependency graph to find the cycle.

2.8 KiB Raw Blame History