Skip to content

docs: promote Templates to a top-level sidebar section - #31646

Merged
nickvigilante merged 2 commits into
docs/ia-ai-sectionsfrom
docs/ia-templates
Nov 2, 2026
Merged

nickvigilante merged 2 commits into
docs/ia-ai-sectionsfrom
docs/ia-templates

Conversation

@coder

@coder coder Bot commented Nov 2, 2026

Copy link
Copy Markdown
Contributor

Note

Generated by Coder Agents. The branch and this description were written by an AI agent and need human review.

Summary

Second of three stacked PRs for the docs IA overhaul (Proposal 1, section 2). This PR promotes Templates out of Administration to a top-level sidebar section between Install and User guides.

  • docs/admin/templates/** moves to docs/templates/** with git mv: 46 files, including pages that are not in the sidebar, such as extending-templates/external-auth.md, and extending-templates/script-ordering.md, which was added to main after the first version of this PR.
  • Two of the three tutorials the proposal names still exist on main, and both move into the new section. template-from-scratch.md goes after "Creating templates" and testing-templates.md goes before "Troubleshoot templates". Their Tutorials sidebar entries are removed.
  • docs/manifest/admin/templates.yml and docs/manifest/admin/templates/ move to docs/manifest/templates.yml and docs/manifest/templates/. admin.yml no longer includes them, and index.yml lists templates.yml after install.yml. The Script ordering entry from main moves with them.
  • Every relative link and image path is fixed, in moved pages and in pages that link to them. This includes repo-relative links out of docs/, such as ../../../examples/templates, whose depth changed. docs/images/ stays where it is.
  • Commit 2, chore: point in-product docs links at the new docs paths, updates docs URLs outside docs/, then regenerates the files built from them with make gen. You can drop that commit; the redirects cover the old URLs.
    • Updated sources: site/ docs() links, cli/cliui troubleshooting links, CLI flag help, the agentFallbackTroubleshootingURL default, the prebuilds metric help text, examples/, and templatebuilder READMEs.
    • Regenerated files: CLI golden files, docs/reference/cli/templates/{create,edit}.md, scripts/metricsdocgen/generated_metrics, and the generated table in docs/admin/integrations/prometheus.md.

Stack: docs/ia-ai-sections → this PR → docs/ia-tutorials-nav.

Refs: Linear DOCS-1154, DOCS-1179.

Move map

Old New
docs/admin/templates/** (46 files) docs/templates/**
docs/tutorials/template-from-scratch.md docs/templates/template-from-scratch.md
docs/tutorials/testing-templates.md docs/templates/testing-templates.md

Redirects added

Source Destination
/docs/tutorials/template-from-scratch /docs/templates/template-from-scratch
/docs/tutorials/testing-templates /docs/templates/testing-templates
/docs/admin/templates/:path* /docs/templates/:path*

The wildcard also covers script-ordering, which is new on main.

Updated an existing rule to avoid a chain: /docs/admin/templates/extending-templates/dynamic-parameters now points to /docs/templates/extending-templates/parameters. It stays above the new wildcard so it still applies first.

coder.com redirects.json: I could not check it, because the file is not readable anonymously and the provided credentials cover only coder/coder. Someone with access should look for /docs destinations under /docs/admin/templates/... or /docs/tutorials/{template-from-scratch,testing-templates}.

Deviations from the proposal

  • tutorials/external-database.md is not in this PR. The proposal puts it under Templates, but the page is about pointing the Coder control plane at an external PostgreSQL database, not about templates. PR C moves it to install/server/external-database.md, next to postgres-ssl.md. If you want it under Templates, it's a one-line change.
  • Manifest position of the two tutorials. The proposal doesn't say where they go, so I placed them as described in the Summary.
  • Generated files belong to commit 2. Commit 1 doesn't edit generated docs. Those files change only through their sources and make gen, so lint/docs-gen-filter stays clean.
  • Left unchanged on purpose:
    • Database migrations, the notification .golden files rendered from them, and the matching site/src/testHelpers/entities.ts fixtures still contain coder.com/docs/admin/templates/... URLs. Existing migrations can't be edited, so those links rely on the wildcard redirect.
    • Test fixtures in scripts/docsredirectscheck, site/scripts/audit-docs-paths.test.mjs, and .github/workflows/test-docs-preview-mapper.sh are synthetic. Tool.stories.tsx uses https://coder.com/docs/admin/templates as a sample web search result.
    • The style guide's "What's next?" example in docs/.style/style-guide/word-choice.md shows a link to admin/templates/... inside a fenced code block. It is sample Markdown, not a live link.

Open questions for Nick

  1. Should external-database.md go under Install (as in PR C) or Templates (as in the proposal)?
  2. Templates keeps its picture.svg icon. Is that OK at the top level?
  3. Frontend review nits on existing code that this PR only touched; I didn't change them:
    • TemplatesFilter.tsx has a commented-out learnMoreLink to the #template-filtering anchor, which doesn't exist.
    • TemplateAlternatives.tsx hardcodes a https://coder.com/docs/... URL instead of using docs().
    • The CreateWorkspacePageView story's play function only asserts link attributes.

Validation run

  • make gen/docs-manifest: clean diff afterward.
  • make lint/docs-manifest, lint/docs-redirects (-base docs/ia-ai-sections: 15 rules OK), lint/docs-html, lint/emdash: pass.
  • pnpm check-docs (markdownlint + table formatter): pass.
  • Vale over docs/: the same 12 warnings and 1 error as main, all pre-existing (suggestions: 645, the same as PR A).
  • Local relative-link check over docs/**/*.md: 0 unresolved.
  • Pre-commit hook: make pre-commit-light on the docs commit, and the full make pre-commit on the chore commit. make gen left a clean tree. Targeted tests passed:
    • Go: go test ./cli -run 'TestCommandHelp|TestServerYAMLConfig', ./enterprise/cli -run TestEnterpriseCommandHelp, ./coderd/render, ./cli/cliui, ./agent/agentscripts, ./coderd/prebuilds, ./enterprise/coderd/prebuilds.
    • Site: Vitest for the touched directories (17 files, 188 tests), and the CreateWorkspacePageView story tests (14 tests).
  • Frontend deep review (all 8 roles) on the site/ diff: no blocking or should-fix findings, and every new docs() path and anchor resolves, except the pre-existing commented-out anchor in question 3.
  • Page counts: docs/**/*.md 486 → 486 (moves only); manifest.json routes 491 → 491.
  • Skipped: the docs-engine sync check, which was not available in this environment.
Implementation notes
  • Rebuilt on the new docs/ia-ai-sections, which is based on main at 9839406ff7 (2026-11-02).
  • The same one-shot move script as PR A did the move and link pass from a clean tree. Run on the old base, it reproduced the old commit exactly (apart from the generated files, which belong to commit 2), so no hand edits were needed in this PR's docs commit.
  • The chore commit uses the same rewrite over the files outside docs/ that link to moved pages. Its diff for site/, cli/cliui, and the other sources matches the earlier version of this branch line for line.
  • Changes from the earlier version of this branch: 1 more page moves (extending-templates/script-ordering.md), with its sidebar entry. docs/install/cli.md no longer exists on main (docs: add quick paths to the install landing page and retire the CLI page #31513), so its link fix is gone.

coder Bot added 2 commits November 2, 2026 21:02
Move docs/admin/templates to docs/templates and list Templates between
Install and User guides. Pull the template-from-scratch and
testing-templates tutorials into the new section, and redirect every
moved URL.
@github-actions github-actions Bot added the community Pull Requests and issues created by the community. label Nov 2, 2026
@coder
coder Bot requested a review from nickvigilante November 2, 2026 21:17
@nickvigilante nickvigilante added the cherry-pick/v2.39 Cherry-pick PR targeting release/2.39 label Nov 2, 2026
@nickvigilante
nickvigilante merged commit 17e54ad into docs/ia-ai-sections Nov 2, 2026
36 of 37 checks passed
@nickvigilante
nickvigilante deleted the docs/ia-templates branch November 2, 2026 21:58
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 2, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

cherry-pick/v2.39 Cherry-pick PR targeting release/2.39 community Pull Requests and issues created by the community.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant