Repository navigation
docs: promote Templates to a top-level sidebar section - #31646
Merged
Merged
Conversation
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.
nickvigilante
approved these changes
Nov 2, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 todocs/templates/**withgit mv: 46 files, including pages that are not in the sidebar, such asextending-templates/external-auth.md, andextending-templates/script-ordering.md, which was added tomainafter the first version of this PR.main, and both move into the new section.template-from-scratch.mdgoes after "Creating templates" andtesting-templates.mdgoes before "Troubleshoot templates". Their Tutorials sidebar entries are removed.docs/manifest/admin/templates.ymlanddocs/manifest/admin/templates/move todocs/manifest/templates.ymlanddocs/manifest/templates/.admin.ymlno longer includes them, andindex.ymlliststemplates.ymlafterinstall.yml. The Script ordering entry frommainmoves with them.docs/, such as../../../examples/templates, whose depth changed.docs/images/stays where it is.chore: point in-product docs links at the new docs paths, updates docs URLs outsidedocs/, then regenerates the files built from them withmake gen. You can drop that commit; the redirects cover the old URLs.site/docs()links,cli/cliuitroubleshooting links, CLI flag help, theagentFallbackTroubleshootingURLdefault, the prebuilds metric help text,examples/, and templatebuilder READMEs.docs/reference/cli/templates/{create,edit}.md,scripts/metricsdocgen/generated_metrics, and the generated table indocs/admin/integrations/prometheus.md.Stack:
docs/ia-ai-sections→ this PR →docs/ia-tutorials-nav.Refs: Linear DOCS-1154, DOCS-1179.
Move map
docs/admin/templates/**(46 files)docs/templates/**docs/tutorials/template-from-scratch.mddocs/templates/template-from-scratch.mddocs/tutorials/testing-templates.mddocs/templates/testing-templates.mdRedirects added
/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 onmain.Updated an existing rule to avoid a chain:
/docs/admin/templates/extending-templates/dynamic-parametersnow 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 onlycoder/coder. Someone with access should look for/docsdestinations under/docs/admin/templates/...or/docs/tutorials/{template-from-scratch,testing-templates}.Deviations from the proposal
tutorials/external-database.mdis 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 toinstall/server/external-database.md, next topostgres-ssl.md. If you want it under Templates, it's a one-line change.make gen, solint/docs-gen-filterstays clean..goldenfiles rendered from them, and the matchingsite/src/testHelpers/entities.tsfixtures still containcoder.com/docs/admin/templates/...URLs. Existing migrations can't be edited, so those links rely on the wildcard redirect.scripts/docsredirectscheck,site/scripts/audit-docs-paths.test.mjs, and.github/workflows/test-docs-preview-mapper.share synthetic.Tool.stories.tsxuseshttps://coder.com/docs/admin/templatesas a sample web search result.docs/.style/style-guide/word-choice.mdshows a link toadmin/templates/...inside a fenced code block. It is sample Markdown, not a live link.Open questions for Nick
external-database.mdgo under Install (as in PR C) or Templates (as in the proposal)?picture.svgicon. Is that OK at the top level?TemplatesFilter.tsxhas a commented-outlearnMoreLinkto the#template-filteringanchor, which doesn't exist.TemplateAlternatives.tsxhardcodes ahttps://coder.com/docs/...URL instead of usingdocs().CreateWorkspacePageViewstory'splayfunction 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.docs/: the same 12 warnings and 1 error asmain, all pre-existing (suggestions: 645, the same as PR A).docs/**/*.md: 0 unresolved.make pre-commit-lighton the docs commit, and the fullmake pre-commiton the chore commit.make genleft a clean tree. Targeted tests passed:go test ./cli -run 'TestCommandHelp|TestServerYAMLConfig',./enterprise/cli -run TestEnterpriseCommandHelp,./coderd/render,./cli/cliui,./agent/agentscripts,./coderd/prebuilds,./enterprise/coderd/prebuilds.CreateWorkspacePageViewstory tests (14 tests).site/diff: no blocking or should-fix findings, and every newdocs()path and anchor resolves, except the pre-existing commented-out anchor in question 3.docs/**/*.md486 → 486 (moves only);manifest.jsonroutes 491 → 491.Implementation notes
docs/ia-ai-sections, which is based onmainat9839406ff7(2026-11-02).docs/that link to moved pages. Its diff forsite/,cli/cliui, and the other sources matches the earlier version of this branch line for line.extending-templates/script-ordering.md), with its sidebar entry.docs/install/cli.mdno longer exists onmain(docs: add quick paths to the install landing page and retire the CLI page #31513), so its link fix is gone.