mirror of
https://github.com/coder/coder.git
synced 2026-11-22 11:28:40 +08:00
25af21b5d5d86ab7d9253e1e72d33b2da170e4f8
9
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
bc77c40296 |
docs: add front-matter titles to mechanical and no-H1 pages (Phase 3) (#28030)
## Summary **Batch A of Phase 3** of the H1 → front-matter migration (`DOCS-484`; parent `DOCS-477`). Adds a front-matter `title` to every navigable docs page whose title can be migrated **mechanically**, with no editorial judgment. This is the content step that Phase 1 (renderers prefer front-matter title, `DOCS-482`) and Phase 2 (tooling + generators front-matter-aware, `DOCS-483`) unblocked. Both are merged; coder.com #964/#974 are merged and live. **Rendered no-op.** The renderers already resolve the page title from the manifest and hide the leading body H1 (Phase 1), so no page changes visually. This just moves the title into front matter where Fumadocs and the migrated tooling can read it. ## What's in this batch Dry-run on `main` (464 navigable pages) splits into: | category | count | this PR | |----------|-------|---------| | already has front-matter title (Reference, from Phase 2 generators) | 196 | skipped (idempotent) | | **mechanical** — leading body H1 equals the manifest label | 138 | ✅ add front-matter `title`, drop the duplicate H1 | | **no body H1** — renders under the manifest label only | 4 | ✅ add front-matter `title` only | | **mismatch** — body H1 differs from the manifest label | 126 | ⏭️ deferred (needs an editorial decision, see below) | 142 files changed, all under `docs/`. ## Deliberately out of scope: the 126 mismatches Pages where the body H1 is richer than the short sidebar label (e.g. label **Modules** / H1 *Contributing modules*, label **Install** / H1 *Installing Coder*) need a canonical-title decision, not a script. A few even look like the body H1 is the redundant one (`install/cli.md` and `install/index.md` both carry the H1 *Installing Coder*). These will land in follow-up batches **by nav section** once the policy is set, so each gets real review. ## Verification AI was the primary author of this PR (see disclosure below); per the [AI Contribution Guidelines](https://coder.com/docs/about/contributing/AI_CONTRIBUTING) here is the manual verification. - Every added front-matter block parses as YAML and its `title` round-trips to the manifest label (checked programmatically across all 142 files). - Every removed line is a leading `# H1` that equalled the manifest title; no body prose was reflowed. Front matter is correctly hoisted above pre-existing `<!-- markdownlint-disable -->` comments on the two pages that had them. - `pnpm check-docs` (markdownlint-cli2 + table formatter) passes on the changed set: `Summary: 0 error(s)`. `MD041` stays off (re-enabled in Phase 4); `MD025` is not tripped because the duplicate body H1s are removed. ``` $ pnpm exec markdownlint-cli2 $(git diff --name-only origin/main) Linting: 142 file(s) Summary: 0 error(s) ``` Linear: DOCS-484 > This PR was created with AI assistance (Coder Agents). |
||
|
|
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.* |
||
|
|
e458692cb8 |
refactor(docs): convert absolute coder/coder blob/tree/main links to relative (DOCS-351) (#26341)
Closes [DOCS-351](https://linear.app/codercom/issue/DOCS-351). > [!WARNING] > **DO NOT MERGE** until [DOCS-349](https://linear.app/codercom/issue/DOCS-349) ([coder.com#877](https://github.com/coder/coder.com/pull/877)) has shipped to production and baked for at least one Vercel cycle. > > Without DOCS-349, the relative links in this PR resolve to broken docs-route URLs (`/docs/helm/coder/values.yaml` -> 404) instead of GitHub URLs tagged with the displayed docs version. DOCS-349 fixes the rewriter to classify these as GitHub blob/tree URLs with the page's resolved ref. ## TL;DR Converts 121 absolute `https://github.com/coder/coder/(blob|tree)/main/<path>` links across 39 docs markdown files to relative paths. After this lands AND DOCS-349 deploys, every one of these links will follow the displayed docs version (mainline tag on bare URLs, explicit tag on `/@vX.Y.Z/`, `main` on `/@main/`) instead of always pointing to `main`. ## Why Today a reader on `/docs/@v2.30.0/install/docker` follows a `compose.yaml` link and arrives at `main`'s `compose.yaml`, which doesn't necessarily match what the docs page describes. Helm values, Terraform templates, and source-code references in particular drift across versions. The fix is to let the coder.com rewriter substitute the page's resolved ref into the URL; that only works on relative links. ## Example payoff (post-DOCS-349) | URL | Today (absolute, always `main`) | After (relative + rewriter) | |---|---|---| | `/docs/install/docker` | `https://github.com/coder/coder/blob/main/compose.yaml` | `https://github.com/coder/coder/blob/v2.34.1/compose.yaml` (today's mainline) | | `/docs/@v2.30.0/install/docker` | same as above | `https://github.com/coder/coder/blob/v2.30.0/compose.yaml` | | `/docs/@main/install/docker` | same as above | `https://github.com/coder/coder/blob/main/compose.yaml` | ## Scope - **121 conversions** across **39 files**. - Verb breakdown: `tree/main` (directories) and `blob/main` (files), both flipped to relative paths. - Line anchors (`#L23-L24`) and query strings preserved verbatim. - Conversion is mechanical: relative path computed from the doc file's directory to the target via `os.path.relpath`. Any path starting at the same directory or below gets a `./` prefix; otherwise `../` chains. ## Rebased on main The branch was rebased onto `main` after the DOCS-350 hotfix ([#26339](https://github.com/coder/coder/pull/26339)) merged. The hotfix repointed 3 `docs-backend-contrib-guide` refs in `backend.md` to `main`, which then needed the same `main` -> relative conversion this PR is doing for the other 121 links. The conflict was resolved by reapplying the mechanical conversion to `backend.md` after taking the hotfix's content. Net result: those 3 links land here as relative, same as everything else. New HEAD `3f501cb622`. ## Inline fix folded in: dead `nix` link - `docs/about/contributing/CONTRIBUTING.md:7` -> `../../../nix` The original absolute URL `https://github.com/coder/coder/tree/main/nix` already returned 404 today. Repointed to `flake.nix` (modern Nix entrypoint, what the prose "Nix environment" semantically refers to). Closes [DOCS-357](https://linear.app/codercom/issue/DOCS-357) here since the `check-docs` Linkspector job surfaced it during rebase; cheaper to fix inline than in a separate single-line PR. ## Out of scope (filed separately) - [DOCS-350](https://linear.app/codercom/issue/DOCS-350): 3 dead `docs-backend-contrib-guide` branch refs in `backend.md` ([#26339](https://github.com/coder/coder/pull/26339), merged). - [DOCS-352](https://linear.app/codercom/issue/DOCS-352): 10 SHA-pinned `(blob|tree)/<sha>` links pending intent review. - [DOCS-355](https://linear.app/codercom/issue/DOCS-355): code-server analog (4 absolute `(blob|tree)/main` links in `coder/code-server`). - [DOCS-356](https://linear.app/codercom/issue/DOCS-356): 2 upstream content bugs in `coder/code-server/docs/CONTRIBUTING.md` (independent of this PR). ## Not triggering `/coder-agents-review` Docs-only edit; per `AGENTS.md` the bot review is reserved for product/CI changes. ## Pre-mortem | Concern | Mitigation | |---|---| | Merging before DOCS-349 deploys regresses ~120 currently-working links into 404s on coder.com | Clear DO-NOT-MERGE banner; tracked as blocker in Linear. | | Relative path computed incorrectly (off-by-one `..`) | Verified all 114 newly-relative non-md/non-image paths resolve to existing files in the repo (only exception is the pre-existing dead `nix` link above). | | Line anchors stripped during conversion | Preserved by the substitution regex; verified `#L<n>-L<m>` cases in `airgap.md` and `speed-up-templates.md`. | | Future code reorgs change file locations | Relative links will start pointing to nothing. Same failure mode as absolute links pointing to renamed files; can be caught with a future link-checker job. | ## Validation ``` $ grep -rE 'github\.com/coder/coder/(blob|tree)/main' docs --include="*.md" | wc -l 0 $ git diff --stat origin/main | tail -1 39 files changed, 118 insertions(+), 118 deletions(-) ``` 114 newly-relative paths verified to resolve to existing repo files (Python `os.path.exists` check on each computed target). <details> <summary>Decision log + planning context</summary> **Why relative over `(blob|tree)/{{currentDocsVersion}}/...` templating**: relative paths require zero markdown-system support and zero upstream churn beyond this one PR. Templating would require a preprocessor on `coder.com` side AND a convention upstream authors have to remember; relative paths just work in a plain editor and `github.com`'s own renderer too. **Why `./` prefix on same-directory targets**: makes the conversion grep-able later (`grep -E '\((\.\./|\./)'`). **Why preserve `#L<n>-L<m>` anchors verbatim**: the anchor is meaningful to the linked file's content, not to the URL form; keeping it as-is preserves authorial intent. If the file later changes such that the line range drifts, that's a different problem the SHA-pin audit ([DOCS-352](https://linear.app/codercom/issue/DOCS-352)) will surface. </details> --- *Generated by Coder Agents on @nickvigilante's behalf.* ## Drive-by external link fix folded in `docs/about/contributing/CONTRIBUTING.md:296` cited `https://reflectoring.io/meaningful-commit-messages/` which is returning HTTP 503 (the host appears to be down site-wide right now). `check-docs` Linkspector flagged it after the rebase. Replaced with `https://cbea.ms/git-commit/` (Chris Beams' canonical "If applied, this commit will..." article, confirmed 200), which is the original source of the rule the prose recites anyway. |
||
|
|
e18c86354c |
fix(docs/about/contributing): repoint dead docs-backend-contrib-guide refs to main (DOCS-350) (#26339)
Closes [DOCS-350](https://linear.app/codercom/issue/DOCS-350). ## Problem Three GitHub links in `docs/about/contributing/backend.md` are pinned to a feature branch (`docs-backend-contrib-guide`) that no longer exists in this repo. All three return HTTP 404 on github.com today. | File:line | Link text | Bad URL | |---|---|---| | `docs/about/contributing/backend.md:53` | `cliui` | `https://github.com/coder/coder/tree/docs-backend-contrib-guide/cli/cliui` | | `docs/about/contributing/backend.md:53` | `testdata` | `https://github.com/coder/coder/tree/docs-backend-contrib-guide/cli/testdata` | | `docs/about/contributing/backend.md:75` | `Go functions` | `https://github.com/coder/coder/blob/docs-backend-contrib-guide/coderd/database/queries.sql.go` | ## Fix Repoint each URL's branch segment to `main`. All three targets exist on `main` unchanged. ## Verification ``` $ curl -fsS -o /dev/null -w '%{http_code}\n' https://github.com/coder/coder/tree/main/cli/cliui 200 $ curl -fsS -o /dev/null -w '%{http_code}\n' https://github.com/coder/coder/tree/main/cli/testdata 200 $ curl -fsS -o /dev/null -w '%{http_code}\n' https://github.com/coder/coder/blob/main/coderd/database/queries.sql.go 200 ``` ## Not triggering `/coder-agents-review` Docs-only edit; per `AGENTS.md` the bot review is reserved for product/CI changes. ## Future-state note These three URLs are absolute `(blob|tree)/main` references. They will eventually be flipped to relative paths by [DOCS-351](https://linear.app/codercom/issue/DOCS-351) once the coder.com rewriter classifier fix ([DOCS-349](https://linear.app/codercom/issue/DOCS-349)) ships. Repointing to `main` here is the right interim fix. --- *Generated by Coder Agents on @nickvigilante's behalf.* |
||
|
|
ca337915cc |
docs: fix broken and naked relative links (#25825)
Several relative links in the docs pointed at pages that no longer exist or rendered incorrectly on coder.com. Fixes: - `start/first-template.md`: IDE links repointed from the removed `../ides.md` / `../ides/web-ides.md` to their current homes under `user-guides/workspace-access/`. - `tutorials/example-guide.md`: contributing link repointed to `../about/contributing/documentation.md`. - `about/contributing/backend.md`: the `migrations/testdata/fixtures` and `full_dumps` references (and the `000024_example.up.sql` example) used relative paths that escape `docs/` and render as bogus `/docs/coderd/...` routes on the site. Normalized to the canonical `github.com/coder/coder/(blob|tree)/main/...` form already used by ~120 other source links in the docs. - Normalized extensionless directory links (`ai-coder/ai-gateway`, `user-guides/workspace-access`, `install`) to their `/index.md` targets for consistency with the rest of the docs. This class of bug is invisible to the local doc checks (`make lint/markdown` / `pnpm check-docs` only run markdownlint + table formatting); only CI's Linkspector job validates link targets. Found via a relative-link audit while investigating the docs preview on #25816. Source-link version-awareness (so older docs versions don't all point at `main`) is tracked separately in DOCS-268 and will be handled in the coder.com render layer. Linear: DOCS-278 Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> |
||
|
|
57af7abf1f |
test: add testutil.WaitBuffer and replace time.Sleep in tests (#22922)
WaitBuffer is a thread-safe io.Writer that supports blocking until accumulated output matches a substring or custom predicate. It replaces ad-hoc safeBuffer/syncWriter types and time.Sleep-based poll loops in tests with signal-driven waits. - WaitFor/WaitForNth/WaitForCond for blocking on output - Replace custom buffer types in cli/sync_test.go and provisionersdk/agent_test.go - Convert time.Sleep poll loops to require.Eventually/require.Never in cli/ssh_test.go, coderd/activitybump_test.go, coderd/workspaceagentsrpc_test.go, workspaceproxy_test.go, and scaletest tests |
||
|
|
b882d46d91 |
docs: fix relative links in about/contributing (#18818)
hotfix --------- Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com> |
||
|
|
3c2f3d640b |
chore: remove dbmem (#18803)
Remove the in-memory database. Addresses #15109. |
||
|
|
f1cca03ed3 |
docs: reorganize the About section (#18236)
As part of an information architecture overhaul, this PR reorganizes the About section and adds a Support section (but not content to it yet) [preview](https://coder.com/docs/@docs-ia-about/about) this PR is intentionally limited in scope so that we can ship meaningful changes faster and followup PRs should include: - [ ] edit + overhaul the About page - [ ] decide on the `start` directory - [ ] ~screenshots page updates~ (this should happen July or later) redirects PR: https://github.com/coder/coder.com/pull/944 --------- Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com> |