# Markdown Templates & Examples > **Agent role**: Reference this file for document templates, structure, > and examples when creating new documentation. > > **Focus**: Create educational content that increases human competence, > not just technical descriptions. ## Document Templates ### Standard Document Template ```markdown # Document Title **Author**: Matthew Raymer **Date**: YYYY-MM-DD **Status**: 🎯 **STATUS** - Brief description ## Overview Brief description of the document's purpose and scope. **Educational Goal**: What will the reader learn and how will it increase their competence? ## Current State Description of current situation or problem. **Why This Matters**: Explain the business value and user benefit of addressing this situation. ## Implementation Plan ### Phase 1: Foundation - [ ] Task 1 - [ ] Task 2 **Learning Context**: What concepts should the reader understand before proceeding with implementation? ## Next Steps 1. **Review and approve plan** 2. **Begin implementation** 3. **Test and validate** **Continued Learning**: Where can the reader go next to deepen their understanding? --- **Status**: Ready for implementation **Priority**: Medium **Estimated Effort**: X days **Dependencies**: None **Stakeholders**: Development team ``` ### Technical Specification Template ```markdown # Technical Specification: [Feature Name] **Author**: Matthew Raymer **Date**: YYYY-MM-DD **Status**: 🎯 **DRAFT** - Under Review ## Overview Brief description of the technical specification. **Business Context**: Why is this specification needed and what problem does it solve for users? ## Requirements ### Functional Requirements - [ ] Requirement 1 - [ ] Requirement 2 ### Non-Functional Requirements - [ ] Performance requirement - [ ] Security requirement ## Technical Design ### Architecture Description of the technical architecture. **Design Rationale**: Why was this architecture chosen over alternatives? What are the trade-offs and benefits? ### Data Models ```typescript interface ExampleModel { id: string; name: string; createdAt: Date; } ``` ### API Design ```typescript interface APIResponse { success: boolean; data: T; error?: string; } ``` ## Testing Strategy - [ ] Unit tests **Learning from Testing**: What insights does testing provide about the system's behavior and design? --- ## Educational Documentation Template ### **Concept Explanation Template** ```markdown ## What is [Concept Name]? Brief, clear definition of the concept. ## Why Does [Concept Name] Matter? Explain the business value and user benefit. ## How Does [Concept Name] Work? High-level explanation of the mechanism. ## When Would You Use [Concept Name]? Real-world scenarios and use cases. ## Common Misconceptions Address typical misunderstandings. ## Examples Concrete examples that illustrate the concept. ## Next Steps Where to learn more about related concepts. ``` ### **Tutorial Template** ```markdown ## Learning Objective What the reader will accomplish by the end. ## Prerequisites What the reader should know before starting. ## Step-by-Step Guide 1. **Step 1**: What to do and why 2. **Step 2**: What to do and why 3. **Step 3**: What to do and why ## Verification How to confirm the tutorial was successful. ## Troubleshooting Common issues and how to resolve them. ## What You've Learned Summary of key concepts and skills. ## Next Steps Where to apply this knowledge next. ``` - [ ] Integration tests - [ ] E2E tests --- **Status**: Draft **Priority**: High **Estimated Effort**: X days **Dependencies**: None **Stakeholders**: Development team ``` ## Content Examples ### JSON Examples ```json { "property": "value", "nested": { "property": "value" } } ``` ### Shell Commands ```bash # Command with comment npm run build:web # Multi-line command VITE_GIT_HASH=`git log -1 --pretty=format:%h` \ vite build --config vite.config.web.mts ``` ### TypeScript Examples ```typescript // Function with JSDoc const getEnvironmentConfig = (env: string) => { switch (env) { case 'prod': return { /* production settings */ }; default: return { /* development settings */ }; } }; ``` ## File Structure Standards ### Document Header ```markdown # Document Title **Author**: Matthew Raymer **Date**: YYYY-MM-DD **Status**: 🎯 **STATUS** - Brief description ## Overview Brief description of the document's purpose and scope. ``` ### Section Organization Standard sections: Overview, Current State, Implementation Plan, Technical Details, Testing & Validation, Next Steps ## Common Patterns Standard implementation plans follow Phase 1 (Foundation), Phase 2 (Features), Phase 3 (Testing & Polish) structure. ## Model Implementation Checklist ### Before Using Templates - [ ] **Template Selection**: Choose appropriate template for document type - [ ] **Structure Review**: Understand required sections and organization - [ ] **Content Planning**: Plan what information goes in each section - [ ] **Audience Analysis**: Ensure template matches target audience needs ### During Template Usage - [ ] **Section Completion**: Fill in all required sections completely - [ ] **Example Integration**: Include relevant code examples and patterns - [ ] **Formatting Consistency**: Apply markdown standards from core rules - [ ] **Cross-references**: Link to related documentation and resources ### After Template Usage - [ ] **Content Review**: Verify all sections contain appropriate content - [ ] **Formatting Check**: Run `npm run markdown:check` for compliance - [ ] **Template Validation**: Confirm document follows template structure - [ ] **Quality Assessment**: Ensure content meets project standards ### Template-Specific Requirements - [ ] **Standard Documents**: Include all required metadata and sections - [ ] **Technical Specs**: Complete all requirement and design sections - [ ] **Implementation Plans**: Define clear phases and milestones - [ ] **Examples**: Provide relevant, working code examples --- **See also**: - `.cursor/rules/meta_documentation.mdc` for comprehensive documentation workflow - `.cursor/rules/docs/markdown_core.mdc` for core formatting standards - `.cursor/rules/docs/markdown_workflow.mdc` for validation workflows **Status**: Active templates and examples **Priority**: Medium **Estimated Effort**: Ongoing reference **Dependencies**: markdown_core.mdc **Stakeholders**: Documentation team, Development team