Commit Graph
48 Commits
Author SHA1 Message Date
Nick Vigilante 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).
2026-08-27 12:34:13 -04:00
Nick Vigilante fc6d6babfa docs: add markdown_url front matter so the About page links to /docs.md (#28281)
The docs About page renders at `/docs/about`, but its Markdown source is
the docs root `README.md`, whose Markdown twin is `/docs.md`. The
path-derived mapping (`/docs/about` -> `/docs/about.md`) points the
"Copy page / view as Markdown" affordance and the sitewide
`rel="alternate"` link at a URL that 404s for this page.

Add a `markdown_url: /docs.md` front-matter override to
`docs/README.md`. It is inert for rendering and for `/docs.md` itself
(the body still begins at `# About`); it only populates the front matter
the docs site reads to advertise the correct Markdown alternate.

Reader side: coder/coder.com#1013 (DOCS-638). Neither change breaks
without the other, so they can merge in either order.

Refs DOCS-678

> This PR was created with AI assistance (Coder Agents).
2026-08-19 10:37:43 -04:00
Nick Vigilante 89b0a66079 docs: add top-level Get started section and move the Quickstart (#26821)
Add a top-level "Get started" docs section to the nav and move the Quickstart to /docs/get-started, with inbound link updates and the install page TIP pointing to the Quickstart.

Filed via Coder Agents on Nick's behalf.
2026-06-29 16:07:10 -04:00
Nick Vigilante 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.
2026-06-22 11:39:12 -04:00
Michael Suchacz 38f586107d refactor: remove agents TUI (#25190) 2026-05-13 21:30:11 +02:00
Ben Potter 6711552f7b docs: add Coder Agents to README and about page (#24915)
Adds Coder Agents messaging to the README and about page
(docs/README.md), and updates the hero screenshots.

**README.md**: Adds agents to the tagline, intro paragraph, feature
bullets, and documentation links. Reorders docs section (Workspaces,
Templates, Agents, Administration, Premium, IDEs). Refreshes
integrations: Registry first, renames Dev Container Builder to Dev
Containers, Setup Coder to GitHub Actions, adds community
templates/modules/Discord links. Removes "we" language and vague link
text per docs style feedback.

**docs/README.md**: Adds dedicated Coder Workspaces and Coder Agents
sections with inline links to their respective doc pages. Rewrites "Why
remote development" as prose instead of a flat bullet list. Adds agents
benefits to "Why Coder" (MCP servers, skills, system prompts). Fixes
heading punctuation, replaces "Up next" with "Learn more", corrects
ARM/OS positioning. Removes stale Coder v1 section.

**Screenshots**: Replaces hero-image.png with an updated screenshot
showing templates and a running workspace with IDE apps. Adds
agents-hero-image.png showing the agents chat UI with the git diff
sidebar.

> Generated with [Coder Agents](https://coder.com/agents)
2026-05-04 07:30:41 -05:00
Edward AngertandEdwardAngert 5c16079aff docs: add more specific steps and information about oidc refresh tokens (#18336)
closes https://github.com/coder/coder/issues/18307

relates to https://github.com/coder/coder/pull/18318

preview:
-
[refresh-tokens](https://coder.com/docs/@18307-refresh-tokens/admin/users/oidc-auth/refresh-tokens)
-
[configuring-okta](https://coder.com/docs/@18307-refresh-tokens/tutorials/configuring-okta)
~(not sure why @Emyrk 's photo is so huge there though)~ ✔️
- [x] removed from
[idp-sync](https://coder.com/docs/@18307-refresh-tokens/admin/users/idp-sync)

to do:
- move keycloak
- add ping federate and azure
- edit text (possibly placeholders for now - I want to see how it all
relates and edit it again. right now, there's a note about the same
thing in every section in way that's not super helpful/necessary)
- ~convert some paragraphs to OL~ calling this out of scope for now

---------

Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
2025-06-16 13:18:55 -04:00
Edward Angert 3f1795fd92 docs: remove Coder from Quickstart title (#16016)
[preview](https://coder.com/docs/@quickstart-coder-coder/tutorials/quickstart)
2025-01-03 00:27:56 -05:00
ed5da65a54 chore(docs): add Quickstart doc to tutorials (#14744)
New doc to get users up and running quickly

preview: https://coder.com/docs/@quickstart-guide/tutorials/quickstart

## To Do

- [x] update or remove Codium steps
- [x] add to sidebar
- [x] add to README and others as needed
- [x] reference https://github.com/coder/coder/pull/11946 and the
discussion to influence this PR

closes https://github.com/coder/internal/issues/107

---------

Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Co-authored-by: Muhammad Atif Ali <atif@coder.com>
2024-10-23 11:31:29 -04:00
88c6a75d48 docs: reorganize and edit docs README (#14706)
Edit the docs readme for consistency and better flow

---------

Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Co-authored-by: Muhammad Atif Ali <atif@coder.com>
2024-10-14 13:39:54 -04:00
419eba5fb6 docs: restructure docs (#14421)
Closes #13434 
Supersedes #14182

---------

Co-authored-by: Ethan <39577870+ethanndickson@users.noreply.github.com>
Co-authored-by: Ethan Dickson <ethan@coder.com>
Co-authored-by: Ben Potter <ben@coder.com>
Co-authored-by: Stephen Kirby <58410745+stirby@users.noreply.github.com>
Co-authored-by: Stephen Kirby <me@skirby.dev>
Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Co-authored-by: Edward Angert <EdwardAngert@users.noreply.github.com>
2024-10-05 10:52:04 -05:00
Stephen Kirby 91a8b1b886 chore: fix broken docs links (#11760)
* fixed broken install/packages.md link

* fixed broken docs links

* fixed admin/auth link

* fixed example-guide links

* replaced mitchell tweet with nix docs

* make fmt

* replaced private image with imgur
2024-01-22 18:45:34 -06:00
Eric Paulsen 6715cb6a95 docs: resolve README 404s (#7822) 2023-06-02 20:56:06 +00:00
Muhammad Atif Ali 4061a254a5 docs: fix a broken link in docs/README.md (#7150) 2023-04-17 13:05:12 +00:00
Muhammad Atif Ali 0e50afe4cf fix(docs): fix broken docs (#7138)
* fixing a lot of broken links

* more fixes

* add 0 as valid status codes

https://tools.ietf.org/html/rfc7231#section-6.3.1 --> 0 as status code
2023-04-14 11:11:51 -05:00
Bruno Quaresma de66f0d540 docs: Add frontend guide (#5852) 2023-01-25 16:15:06 +00:00
Ammar Bandukwala 05dc83e522 docs: add hero image to About (#5539)
A reddit comment recently linked to this page, so we want to
make it convert better.
2023-01-02 14:36:36 -06:00
sharkymarkandBen 461c0d0d39 docs: v1 docs redirect (#5509)
* docs: v1 docs redirect

* fix link

Co-authored-by: Ben <me@bpmct.net>
2022-12-22 15:14:36 -08:00
Marcin Tojek cec667d309 fix: prettier misses docs directory (#5285)
* chore: keep admin/prometheus.md if make target fails

* Address PR comments

* Formatted

* fix: prettier misses docs

* make fmt

* More md files
2022-12-05 12:21:09 +01:00
Michael Eanes 126d71f41d Remove alpha warning from about (#3774)
The doc was outdated; I don't think the software is alpha anymore.
2022-08-31 03:23:56 +00:00
Roman ZubovandAnton Korzhuk a21a6d2f4a docs: replaced manual up next blocks with doc tag in workspaces.md (#3023)
* docs: replaced manual up next blocks with doc tag in workspaces.md

* replaced up next blocks with <doc page=""> tags

* revert back to markdown

now that we updated how these links work, we can have them as markdown on github and as cards on the docs website.

Co-authored-by: Anton Korzhuk <antonkorzhuk@gmail.com>
2022-08-25 08:26:04 -07:00
whitney-coder d6351a6b9f Update README.md (#3539)
Minor grammatical change on line 14
2022-08-17 14:48:41 -05:00
Katie Horne 407c47fd65 chore: change Coder v2 to Coder OSS in docs (#2630) 2022-06-27 11:07:17 -05:00
Katie Horne 4eda7034ee chore: fix broken links to use full path (#2606) 2022-06-23 09:04:31 -05:00
Katie Horne f476a4ad37 chore: fix broken links and formatting issues (#2547) 2022-06-21 13:13:38 +00:00
Katie Horne f5e558c4ec chore: convert citations to hyperlinks (#2392) 2022-06-15 16:11:44 -05:00
Ammar Bandukwala 2e625c1d9b docs: use about as home page (#2382)
* docs: use About as home page

* docs: format install.md
2022-06-15 14:03:13 -05:00
Katie Horne cbde8e8b91 chore: add hero image to OSS docs homepage (#2241) 2022-06-13 09:16:26 -05:00
Bruno QuaresmaandJoe Previte d04d527f2c chore: Update docs manifest home page and icons (#2133)
* chore: Update docs manifest home page and icons

* RRemove contributors

* Update template icon

* fixup: manifest.json changes

* fix: add missing readme to root

* fix: add readme to /docs with toc

* fix: add quickstart to manifest

Co-authored-by: Joe Previte <jjprevite@gmail.com>
2022-06-09 18:46:16 +00:00
Joe Previte 0622603220 docs: move README to root (#1630)
We noticed that when you download the repo as a ZIP from GitHub, it
places the `README.md` in the root, which causes the relative links to
break.

By moving it to the root, this will fix that issue.
2022-05-20 09:56:50 -07:00
Katie Horne 6f969214d3 chore: validate docs (#1485) 2022-05-19 08:01:19 -05:00
Ben Potter b8ee939e52 chore: change Slack to Discord link (#1573) 2022-05-18 21:14:31 +00:00
Eric Paulsen 695b709173 fix: examples link in README (#1441) 2022-05-13 16:43:10 -05:00
Ben Potter 64a8b4ac47 chore: add bpmct to contributors list (#1332) 2022-05-13 02:01:31 +00:00
G r e y 9ef64fd192 chore: add myself as a contributor (#1408) 2022-05-12 14:44:54 -04:00
Spike Curtis c96d439f3d chore: add Spike Curtis to contributors (#1333)
Signed-off-by: Spike Curtis <spike@coder.com>
2022-05-10 16:46:28 +00:00
Ben PotterandKatie Horne e8e4cf9a37 feat: add comparison to docs (#1315)
* fix typo

* feat: add comparison table

* Update docs/about.md

Co-authored-by: Katie Horne <katie@23spoons.com>

* Update docs/about.md

Co-authored-by: Katie Horne <katie@23spoons.com>

* Update docs/about.md

Co-authored-by: Katie Horne <katie@23spoons.com>

* chore: remove gitpod

Co-authored-by: Katie Horne <katie@23spoons.com>
2022-05-10 16:31:59 +00:00
David Wahler d847d2b1c5 chore: add dwahler as contributor (#1352) 2022-05-09 20:57:03 +00:00
Kira Pilot f5693dff3d chore: added contributer (#1349) 2022-05-09 14:49:23 -04:00
Ben Potter f965066517 feat: add screenshot to readme (#1313)
* feat: add screenshot to readme

* change
2022-05-06 01:09:27 +00:00
Kyle Carberry c2b5009208 fix: Unnest workspaces command to the top-level (#1241)
This changes all "coder workspace *" commands to root.
A few of these were already at the root, like SSH. The
inconsistency made for a confusing experience.
2022-05-02 11:08:52 -05:00
Mathias FredrikssonandCian Johnston 0b1ee3303d chore: Add Contributors section to readme (#1144)
Co-authored-by: Cian Johnston <public@cianjohnston.ie>
2022-04-27 11:48:45 +00:00
22668c388c feat: initial docs pages (#1107)
* docs structure and edits to getting started

* draft for about page

* skeleton for concepts page

* attempt at explaining templates

* left-align tables

* add best practices and variables

* update structrure

* update structure

* templates are shared

* workspaces docs

* remove coming soon

* fix typos

* docs structure and edits to getting started

* draft for about page

* skeleton for concepts page

* attempt at explaining templates

* left-align tables

* add best practices and variables

* update structrure

* update structure

* templates are shared

* workspaces docs

* remove coming soon

* fix typos

* fix typos

* Update docs/about.md

Co-authored-by: Joe Previte <jjprevite@gmail.com>

* remove line breaks between bullets

* rename variables to parameters

* reduce limits

* chore: edit text

* revert some changes, fix footnotes

Co-authored-by: Katie Horne <katie@coder.com>
Co-authored-by: Joe Previte <jjprevite@gmail.com>
2022-04-26 12:10:50 -05:00
Kyle Carberry 3976994781 chore: Rename "start" to "server" (#1110)
Workspace commands will be aliased at the top-level, so
"start" would easily be confused with starting a workspace.

Server seems like a more appropriate name too.
2022-04-23 12:19:20 -05:00
Ben Potter b7d7e19606 fix: rename projects to templates in README (#920) 2022-04-07 17:58:17 -04:00
Joe Previte 584c8b4fc3 docs: move development workflow to CONTRIBUTING (#890) 2022-04-06 10:26:17 -07:00
Kyle Carberry 1e9e5f7c76 chore: Add contributing guidelines (#874)
It's helpful for us Coders to align on a common set of style
guidelines. While I'd prefer to automate this, documentation
should get us a lot of the way there!

Please review these thoroughly, as PRs will be checked against it
after merge.
2022-04-05 15:02:28 -05:00
Joe Previte f02b8fda9e docs(README): move to /docs folder (#871) 2022-04-04 15:48:22 -07:00