Repository navigation
Conversation
✅ Deploy Preview for calico-docs-preview-next ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview succeeded!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Four unresolved documentation and template issues leave the agent guidance incomplete and the reference-page templates grammatically unfinished.
4 open issues
What changed in this PR
Adds a standardized resource-reference template and converts the IPReservation, IPPool, and BGPPeer pages to demonstrate the new structure. It also adds contributor guidance, supporting content templates, agent instructions, and updates an IPPool selector link.
Changes:
- Adds contributor documentation and templates for documentation content types.
- Introduces the resource-reference template with consistent sections and field tables.
- Converts three Calico resource-reference pages to the new format.
- Updates selector-anchor references and agent guidance.
| File | Summary |
|---|---|
contributors/style-guide.md |
Adds contributor style-guide guidance. |
contributors/README.md |
Adds navigation for contributor documentation and templates. |
contributors/content-types/templates/tutorial.mdx |
Adds the tutorial template. |
contributors/content-types/templates/troubleshooting.mdx |
Adds the troubleshooting template. |
contributors/content-types/templates/resource.mdx |
Adds the standardized resource-reference template. |
contributors/content-types/templates/reference.mdx |
Adds the general reference template and resource-template guidance. |
contributors/content-types/templates/installation-guide.mdx |
Adds the installation-guide template. |
contributors/content-types/templates/how-to.mdx |
Adds the how-to template. |
contributors/content-types/templates/explanation.mdx |
Adds the explanation template. |
contributors/content-types/content-types.md |
Documents available content types and their intended uses. |
CLAUDE.md |
Points agents to repository instructions. |
calico/reference/resources/ipreservation.mdx |
Converts the IPReservation page to the resource-reference structure. |
calico/reference/resources/ippool.mdx |
Converts the IPPool page and updates behavior and selector sections. |
calico/reference/resources/bgppeer.mdx |
Converts the BGPPeer page with nested type sections and standardized tables. |
calico/reference/configure-calico-node.mdx |
Updates the IPPool selector anchor link. |
AGENTS.md |
Adds guidance for selecting content types and templates. |
This pull request is too complex or risky for automated approval.
Review effort: Lite
| ### Choose a content type | ||
|
|
||
| Every new page has one content type, chosen for what the reader is trying to do. | ||
| Read [content-types.md](contributors/content-types/content-types.md) and choose a type: how-to, explanation, tutorial, reference, installation guide, or troubleshooting. |
Comment on lines
+22
to
+24
| Every new page has one content type, chosen for what the reader is trying to do. | ||
| Read [content-types.md](contributors/content-types/content-types.md) and choose a type: how-to, explanation, tutorial, reference, installation guide, or troubleshooting. | ||
| If the request covers more than one type, such as steps plus a long explanation of how a feature works, suggest separate pages and ask before you write them. |
| They come to look up one fact, and they leave once they've found it. | ||
| A reference page must be accurate, complete, and easy to scan. | ||
|
|
||
| A reference page describes. |
| Readers come to it while writing or reviewing a manifest. | ||
| They look up one field and leave, so the page has to be complete, accurate, and easy to scan. | ||
|
|
||
| A resource reference page describes. |
The resource pages use 16 table layouts, 25 wordings for the definition heading, three ways to mark a required field, and six layouts for the supported operations table. The template fixes one structure: a lead paragraph that gives the scope and the owner, a sample manifest, a Definition section with Metadata, Spec, nested types, and Status, behavior sections after it, and additional resources. Every table has the same five columns. There is no supported operations table; the lead paragraph says what the reader can't do. Converts three Calico Open Source pages as worked examples: IP reservation, IP pool, and BGP peer. The conversions change structure and the metadata name rule, not the facts on the page.
ctauchen
force-pushed
the
docs-3100-resource-template
branch
from
November 5, 2026 16:40
003ecfd to
fa4b205
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
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 a template for resource reference pages, so that every page in reference/resources/ has the same sections, in the same order, with the same table columns. The 98 existing pages use 16 table layouts, 25 wordings for the definition heading, three ways to mark a required field, and six layouts for the supported operations table.
Jira: https://tigera.atlassian.net/browse/DOCS-3100
Changes:
Preview: