docs: group registry sidebar by subcategory - #426
Open
matifali wants to merge 2 commits into
Open
Conversation
matifali
force-pushed
the
docs/registry-subcategories
branch
from
August 25, 2026 16:17
c3874e4 to
588ce80
Compare
ethanndickson
force-pushed
the
docs/registry-subcategories
branch
from
August 26, 2026 13:25
588ce80 to
b5316cd
Compare
ethanndickson
approved these changes
Aug 26, 2026
ethanndickson
left a comment
ethanndickson
left a comment
Member
There was a problem hiding this comment.
I dedupe'd the tmpl files, lgtm
matifali
force-pushed
the
docs/registry-subcategories
branch
from
August 27, 2026 11:02
9cd92fc to
630ac8e
Compare
ethanndickson
force-pushed
the
docs/registry-subcategories
branch
from
August 27, 2026 12:15
630ac8e to
7e8b401
Compare
Member
|
@codex review |
|
Codex Review: Didn't find any major issues. More of your lovely PRs please. Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
Add per-resource tfplugindocs templates (templates/resources/<name>.md.tmpl, templates/data-sources/<name>.md.tmpl) that set a subcategory front-matter field per resource/data source, so the Terraform Registry sidebar groups coderd_* pages into Agents, AI Governance, Deployment, Identity & Access Management, and Templates instead of listing them flat. The templates are copies of tfplugindocs' default resource template, minus the HasImportIDConfig/HasImportIdentityConfig branches: no resource ships import-by-string-id.tf or import-by-identity.tf example files, so those branches were always-false dead code. Data-source templates drop the import section entirely. Stacked on org-chat-models/default-model (#423), which now includes the renamed coderd_agents_default_model and coderd_agents_system_prompt. Regenerated docs/ with make gen; only the subcategory line changed per file.
tfplugindocs does not expose Registry subcategories through provider schema, so the previous implementation copied its complete default template for every resource and data source. That made a metadata-only change appear as hundreds of duplicated lines and required new pages to copy the rendering markup again. Replace the page-specific copies with generic resource and data source fallback templates that select the subcategory from the Terraform type name. This keeps the generated documentation unchanged while centralizing the workaround in two maintainable templates.
ethanndickson
force-pushed
the
docs/registry-subcategories
branch
from
August 27, 2026 12:37
120a8b2 to
5cab842
Compare
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 join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
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.
Problem
All
coderd_*resources and data sources render on the Terraform Registry with an emptysubcategory, so the sidebar lists every resource/data source flat with no grouping.Fix
Add per-resource doc templates under
templates/resources/<name>.md.tmplandtemplates/data-sources/<name>.md.tmpl(the tfplugindocs conventional paths, matching the pattern used by hashicorp/aws, azurerm, google). Each is a copy of tfplugindocs' default template with a hardcodedsubcategory, grouping pages into:agents_mcp_server,agents_model,agents_system_prompt,agents_default_modelai_providerlicense,oauth2_provider_settings,provisioner_key,workspace_proxyorganization,organization_group_sync,organization_sync_settings,group,usertemplateThe templates also drop the
HasImportIDConfig/HasImportIdentityConfigbranches from tfplugindocs' default template: no resource in this repo shipsimport-by-string-id.tf/import-by-identity.tfexample files, so those branches were always-false dead code. Resource templates keep a singleHasImport(terraform import) section; data-source templates have no import section (data sources are never imported).Regenerated
docs/withmake gen; the diff against the base branch is exactly thesubcategoryline per file (19 files), nothing else changed.Stacking
Stacked on #423 (which stacks on #422). Covers the stack's org-scoped
coderd_agents_default_modelrename (subcategory: Agents); the base already includes the #425agents_system_promptrename.Note for future resources
With per-resource templates, a new resource/data source added without a matching
templates/file falls back to tfplugindocs' embedded default (subcategory: "") and renders uncategorized at the top of the sidebar. Copy a sibling template and set the right subcategory when adding one.Testing
make build,make fmt, andmake gen(idempotent, no drift) are all clean.tfplugindocs validate --provider-name coderdpasses.make linthas 15 pre-existingusetestingfindings, unchanged from the base (verified viagit stash); unrelated to this change.