Chore: standardized frameworks and pages structure

[scode2277]

This PR refreshes docs/pages/config/template.mdx and the contributing guide to align with how the project actually works today and to give contributors a clearer, more structured starting point.

Template updates

• New tiered structure: required sections (key takeaway, intro, "the basics", content, further reading), optional "real-world examples", and a conditional "Pages" section for framework overviews.
• Inline instructions in [brackets] next to each section, so contributors see the rules where they write rather than scrolling between guidance and content.
• Key Takeaway rules tightened.
• "Common pitfalls" dropped as a standalone section; failure modes now anchor to specific recommendations within content sections.
• Top comment block flags required vs. optional structure.
• Dedicated checklist at the top for adding a whole new framework.
• Note on import path resolution for pages nested deeper than one level.

Contributing guide updates

• New "Add a new framework" section, written as a short delta against the page-contribution workflow rather than a parallel set of instructions.
• "Open an issue if unsure" guidance added to the Ways to contribute intro for contributors who aren't sure whether their idea is a page, a section, or a new framework.
• Page-contribution workflow reordered so attribution (frontmatter + contributors.json) happens before opening the PR.
• Corrected dev: true framing: it's set on all new content, not just during review. Reviewed content gets promoted to production periodically when develop merges into main. Added clarification that a new page should keep dev: true even when its parent category does not.
• Frontmatter section compressed to defer to the template as the source of truth.
• Stewardship promoted from a buried one-liner to a "Want to take on more?" subsection, with a mention in the intro and a link to the Spotlight Zone for finding stewards.
• "Contributor tasks beyond content changes" renamed to "Page requirements" and moved earlier in the document so workflow guidance flows in order.
• Bare mermaid example wrapped in <MermaidRenderer> so it actually renders.

[frameworks-volunteer]

Model: z-ai/glm-5.1 Reasoning: high Provider: openrouter

Review: Chore: standardized frameworks and pages structure

Security: PASS

No secrets, injection vectors, unsafe deserialization, dependency changes, or auth modifications. This is purely documentation (MDX + markdown).

QA Findings

1. Missing trailing newline (minor)

Both docs/pages/config/template.mdx and docs/pages/contribute/contributing.mdx are missing a final newline. Git diff shows \ No newline at end of file for both. Some tooling (cat, diffs, heredocs) behaves oddly without a trailing newline, and POSIX text files should end with one. Consider adding a blank line at the end of each file.

2. CONTRIBUTING.md mermaid example not wrapped in <MermaidRenderer> (minor)

The contributing.mdx correctly wraps its mermaid example in <MermaidRenderer> (the PR fixes the bare codeblock). However, CONTRIBUTING.md still uses a bare ```mermaid codeblock at line 366. While CONTRIBUTING.md is a GitHub-rendered file (not Vocs), the inconsistency means the two files that are supposed to mirror each other now diverge on this point. If the intent is to keep them in sync, the CONTRIBUTING.md mermaid example should also be updated to mention <MermaidRenderer>, or at minimum a comment should note that bare codeblocks work on GitHub but not in Vocs.

What looks good

• Template overhaul is a clear improvement: tiered required/optional structure, inline instructions in [brackets], cleaner Key Takeaway guidance, removal of standalone "pitfalls" section in favor of anchored warnings.
• "Add a new framework" section fills a real gap in the contributing guide.
• dev: true clarification (new pages keep the flag even in already-promoted categories) is an important clarification that was missing.
• Stewardship promoted from a buried one-liner to a "Want to take on more?" subsection with proper linking to Spotlight Zone.
• Workflow reordered so attribution (frontmatter + contributors.json) happens before opening the PR -- makes sense.
• Import path resolution note for nested pages is a practical addition.
• Frontmatter section compressed to defer to the template as source of truth -- reduces drift.

Verdict

Two minor issues, nothing blocking. Approving.

[cloudflare-workers-and-pages]

Deploying frameworks with    Cloudflare Pages

Latest commit:	d220974
Status:	✅  Deploy successful!
Preview URL:	https://59fbd9ae.frameworks-573.pages.dev
Branch Preview URL:	https://chore-template-file.frameworks-573.pages.dev

View logs

[scode2277]

@frameworks-volunteer end of file newline fixed. Regarding the mermaid component: that components is necessary only in .mdx files, mermaid code blocks work just fine in .md files

[frameworks-volunteer]

Model: z-ai/glm-5.1 Reasoning: high Provider: openrouter

Acknowledged on both points:

1. Trailing newline -- confirmed fixed (current diff no longer shows No newline at end of file).

2. Mermaid component -- you're right, my review was off on this one. <MermaidRenderer> is needed in .mdx files because Vocs doesn't natively render mermaid code blocks. CONTRIBUTING.md is a GitHub-rendered .md file where bare ```mermaid code blocks work out of the box. The two files serve different renderers, so the different mermaid handling is correct as-is, not an inconsistency. Retracting that finding.

Review stands approved -- no remaining issues.