opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-09-24 15:04:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: audit and fix manifest.json page descriptions for SEO (#27267)

Browse Source 
## What

Audit and fix the page `description` fields in `docs/manifest.json` so
each one is accurate, unique, and follows meta-description SEO best
practices, targeting 70-155 characters.

Tracking: DOCS-576

## Why

Many manifest descriptions were terse (243 of 272 hand-maintained
descriptions were under 70 characters), a few reused another page's
description (copy/paste errors), and one just repeated its own title.
These feed the per-page `<meta name="description">` on coder.com/docs,
so they matter for search snippets and click-through.

## What changed

The manifest diff is +244 / -244 lines, touching only `description`
string values (0 structural lines changed). A second commit regenerates
one downstream file (see Generated file below).

- **Fixed 5 copy/paste errors** where a page reused another page's
description:
  - `admin/monitoring/index.md` (had Security's text)
  - `admin/monitoring/metrics.md` (had Logs' text)
- `admin/templates/template-permissions.md` (had "Creating Templates"
text)
  - `admin/networking/stun.md` (had Port Forwarding's text)
- `admin/provisioners/manage-provisioner-jobs.md` (had the provisioners
index text)
- **Fixed `reference/index.md`**, whose description merely repeated the
title "Reference".
- **Corrected wording**: "Coderd API" to Coder REST API; "VSCode" to VS
Code; dropped the `&` shorthand on the AI Gateway index per the docs
style guide.
- **Corrected accuracy**: the AI landing page listed outdated example
agents (GPT-Code, OpenDevin, SWE-Agent); it now references agents used
elsewhere in the docs (Claude Code, Aider).
- **Expanded terse descriptions** into the 70-155 range with
active-voice, front-loaded phrasing.

## Generated file

`docs/install/releases/feature-stages.md` is generated by
`scripts/release/docs_update_feature_stages.sh`, which copies the beta
pages' manifest descriptions verbatim into the beta-features table.
Three rows (MCP Server, JetBrains Toolbox, Coder Agents) update to match
the new descriptions; User secrets is unchanged. Regenerated with `make
gen` so the generated-files check stays clean.

## Scope / exclusions

Auto-generated reference subtrees are intentionally left untouched,
since `make gen` rebuilds them from source and would revert hand edits
(and fail the generated-files check):

- `Reference > Command Line` children, from `scripts/clidocgen` (each
command's `Short` help)
- `Reference > REST API` children, from `scripts/apidocgen`
- `Reference > Agent API` children

The section index nodes themselves (Reference, REST API, Command Line,
Agent API) are hand-maintained and are in scope.

## Validation

- `docs/manifest.json` is valid JSON; diff touches only `description`
values.
- All 272 in-scope descriptions are now 70-155 characters, with 0
duplicates across distinct pages.
- No double quotes, backslashes, em/en dashes, or `&` / `<` / `>` in
descriptions.
- Biome 2.4.10 (`scripts/biome_format.sh`) is a no-op on the result.
- `scripts/check_emdash.sh` passes.

> This PR was created with AI assistance (Coder Agents).
This commit is contained in:
Nick Vigilante
2026-07-23 16:24:06 -05:00
committed by GitHub
parent 5bafbace8e
commit 73af2ca632
2 changed files with 250 additions and 250 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/install/releases/feature-stages.md
+6 -6
View File
@@ -104,12 +104,12 @@ available in the documentation.
<!-- Code generated by scripts/release/docs_update_feature_stages.sh. DO NOT EDIT. -->
<!-- BEGIN: available-beta-features -->
| Feature | Description |
|------------------------------------------------------------------------------|----------------------------------------------------------------------------|
| [MCP Server](../../ai-coder/mcp-server.md) | Connect AI coding agents to Coder using the MCP server |
| [JetBrains Toolbox](../../user-guides/workspace-access/jetbrains/toolbox.md) | Access Coder workspaces from JetBrains Toolbox |
| [User secrets](../../user-guides/user-secrets.md) | Store secret values in Coder and automatically inject them into workspaces |
| [Coder Agents](../../ai-coder/agents/index.md) | Self-hosted agent by Coder |
| Feature | Description |
|------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------|
| [MCP Server](../../ai-coder/mcp-server.md) | Connect external AI coding agents to Coder using its built-in Model Context Protocol server. |
| [JetBrains Toolbox](../../user-guides/workspace-access/jetbrains/toolbox.md) | Connect to and manage your Coder workspaces from the JetBrains Toolbox app. |
| [User secrets](../../user-guides/user-secrets.md) | Store secret values in Coder and automatically inject them into workspaces |
| [Coder Agents](../../ai-coder/agents/index.md) | Delegate development work to coding agents in your deployment with Coder Agents, a chat interface and API. |
<!-- END: available-beta-features -->
## General Availability (GA)