Repository navigation
DOCS-3147: Add contributor content types and page templates - #3181
Merged
Merged
Conversation
Add a contributor guide that explains content types and gives a template for each one. Content types are based on Diataxis, with installation guides, troubleshooting, and release notes as specialized types.
✅ Deploy Preview succeeded!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview for calico-docs-preview-next ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Several templates can produce invalid YAML description arrays, and the installation guide omits the required platform-only sidebar label, leaving active correctness issues unresolved.
6 open issues
What changed in this PR
This pull request adds contributor guidance for selecting documentation content types and reusable MDX page templates based on Diátaxis, along with a placeholder style guide.
Changes:
- Adds contributor documentation indexes and content-type guidance.
- Defines core and specialized content types, including installation and troubleshooting pages.
- Adds templates and reviewer checklists for six page types.
- Adds an initial style-guide stub.
| File | Summary |
|---|---|
contributors/style-guide.md |
Initial placeholder for documentation style guidance. |
contributors/README.md |
Index linking to contributor guidance and templates. Nit (1 vote): Resolve the mismatch between the documented and actual style-guide path. |
contributors/content-types/templates/tutorial.mdx |
Tutorial-page template. Moderate (2 votes): Quote the description placeholder so it remains a YAML string. |
contributors/content-types/templates/troubleshooting.mdx |
Troubleshooting-page template. Moderate (2 votes): Quote the description placeholder so it remains a YAML string. |
contributors/content-types/templates/reference.mdx |
Reference-page template. Moderate (2 votes): Quote the description placeholder. Nit (1 vote): Use a language placeholder or untyped fence for examples that may be commands or YAML. |
contributors/content-types/templates/installation-guide.mdx |
Installation-guide template. Moderate (1 vote): Quote the description placeholder. Nit (3 votes): Add the sidebar_label field required by the guidance. |
contributors/content-types/templates/how-to.mdx |
How-to guide template. Moderate (2 votes): Quote the description placeholder so it remains a YAML string. |
contributors/content-types/templates/explanation.mdx |
Explanation-page template. Moderate (2 votes): Quote the description placeholder so it remains a YAML string. |
contributors/content-types/content-types.md |
Defines the supported documentation content types and their intended reader needs. |
Review effort: Lite
| @@ -0,0 +1,134 @@ | |||
| --- | |||
| description: [What the reader will understand after reading this page, in one sentence of 130 to 160 characters. Use the full product name.] | |||
| @@ -0,0 +1,192 @@ | |||
| --- | |||
| description: [What the reader will get done by following this page, in one sentence of 130 to 160 characters. Use the full product name.] | |||
| @@ -0,0 +1,138 @@ | |||
| --- | |||
| description: [What the reader can look up on this page, in one sentence of 130 to 160 characters. Use the full product name.] | |||
| @@ -0,0 +1,152 @@ | |||
| --- | |||
| description: [The problems this page helps the reader fix, in one sentence of 130 to 160 characters. Use the full product name.] | |||
| @@ -0,0 +1,166 @@ | |||
| --- | |||
| description: [What the reader will build or learn by following this tutorial, in one sentence of 130 to 160 characters. Use the full product name.] | |||
| @@ -0,0 +1,176 @@ | |||
| --- | |||
| description: [What the reader will install and on which platform, in one sentence of 130 to 160 characters. Use the full product name.] | |||
Quote the description placeholder in each template so that it parses as a string. Remove sidebar_label guidance from the installation guide template.
AGENTS.md applies only when an agent creates a new page. It points at the content types guide and the templates, and tells the agent not to restructure existing pages. CLAUDE.md imports it, so Claude Code reads the same file. Each template now sets content_type in its front matter, so a page copied from a template carries its type.
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
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.
Adds contributor guidance so that every docs page has one content type, chosen for what the reader is trying to do. The content types are based on Diátaxis.
Jira: https://tigera.atlassian.net/browse/DOCS-3147
Changes:
The contributors directory isn't built into the site, so there's no page to preview. Review the files on GitHub.