🛠️ Zer0-Mistakes Technical Documentation Center

This directory contains repository-specific technical documentation for the Zer0-Mistakes Jekyll theme, designed for maintainers, contributors, and developers working with the theme’s source code.

🎯 Purpose & Scope

The /docs/ directory serves as the developer documentation hub containing:

• Repository Architecture: Build processes, component structure, and system design
• Technical Implementation: How features are built, maintained, and tested
• Development Workflows: CI/CD, testing, release processes, and automation
• Stack Technologies: Jekyll, Bootstrap, Docker, Ruby, and framework specifics
• MDX Source Files: Rich documentation with interactive components and code examples

This documentation is source-code focused and targets technical audiences who need to understand, modify, or extend the theme itself.

📍 For Published Documentation: See pages/_docs/ for rendered online documentation targeting end-users and general technology guides.

📁 Directory Structure & Content Types

🏗️ /systems/ - Core System Architecture

Documentation for repository infrastructure and automation:

• Automated Version System - Semantic versioning and release automation
• CI/CD Pipelines - GitHub Actions, testing, and deployment workflows
• Gem Publication System - Ruby gem packaging and distribution
• Build & Testing - Docker, Jekyll compilation, and quality assurance

✨ /features/ - Theme Feature Implementation

Technical documentation for theme features and components:

• Component Architecture - How _layouts/ and _includes/ are structured
• Feature Implementation - Mermaid integration, PostHog analytics, sitemaps
• Enhancement Guides - Adding new features and extending functionality
• Integration Instructions - Bootstrap 5, Jekyll plugins, and third-party services

🔧 /configuration/ - Development & Setup Guides

Environment setup and configuration for contributors:

• Development Environment - Docker, local Jekyll setup, and tooling
• URL Configuration - Routing, permalinks, and hosting setup
• Theme Customization - Overriding defaults and extending styles
• Integration Patterns - How to integrate with external services

📦 /releases/ - Version & Release Documentation

Historical documentation tracking theme evolution:

• Release Notes - Version-specific changes and feature additions
• Migration Guides - Breaking changes and upgrade instructions
• Publication Records - RubyGems releases and distribution
• Version Summaries - High-level overviews of major releases

📝 /templates/ - Documentation Standards

Standardized templates for maintaining documentation quality:

• Feature Documentation Template - Standard format for new features
• Release Notes Template - Consistent changelog and release structure
• Change Tracking Template - How to document modifications
• Issue Templates - Bug reports and feature request formats

🧩 /jekyll/ - Jekyll Ecosystem Documentation

Jekyll-specific technical implementation guides:

• Performance Optimization - Speed and efficiency improvements
• Security Best Practices - Safe Liquid templating and input validation
• Plugin Integration - Custom plugins and third-party extensions
• Advanced Configuration - Complex Jekyll setups and customizations

🎨 /_includes/ - Reusable Documentation Components

Modular documentation components (MDX format):

• Code Examples - Interactive code snippets and demos
• Diagrams & Charts - Technical architecture visualizations
• Reusable Sections - Shared content across multiple docs
• Footer & Navigation - Documentation site structure

📋 Documentation Standards & Formats

🔧 Technical Documentation Format

• Primary Format: MDX (Markdown + JSX) for rich, interactive content
• Code Examples: Live, executable examples with syntax highlighting
• Architecture Diagrams: Mermaid diagrams and technical visualizations
• Interactive Components: Collapsible sections, tabs, and dynamic content

📝 Naming Conventions

• Systems: system-name-architecture.mdx, automation-workflow.mdx
• Features: feature-name-implementation.mdx, component-guide.mdx
• Releases: vX.Y.Z-release-notes.md, vX.Y.Z-technical-summary.mdx
• Configuration: setup-guide.mdx, integration-pattern.mdx
• Templates: documentation-template.mdx, feature-template.mdx

🏗️ Content Guidelines for Technical Documentation

• Architecture First: Start with system design and component relationships
• Implementation Details: Include actual code from _layouts/, _includes/, and _sass/
• Testing Instructions: How to test changes and validate functionality
• Performance Considerations: Impact on build time, runtime, and user experience
• Security Implications: Validate Liquid templates, input sanitization, and dependencies
• Maintainer Notes: Context for future developers about design decisions

🔗 Cross-Reference Standards

• Internal Links: Link to related technical documentation within /docs/
• Source Code References: Direct links to files in _layouts/, _includes/, scripts/
• External Dependencies: Document Bootstrap, Jekyll, Ruby gem dependencies
• API References: Jekyll APIs, Liquid filters, and custom plugin interfaces

🔄 Documentation Workflow & Contribution

📝 Adding New Technical Documentation

1. Choose Directory: Place in appropriate subdirectory based on content type
2. Use MDX Format: Create .mdx files for rich, interactive documentation
3. Follow Templates: Use templates from /templates/ for consistency
4. Include Front Matter: Add metadata for proper categorization and SEO
5. Test Locally: Verify MDX rendering and component functionality
6. Cross-Reference: Link to related source code and documentation

🔧 Working with Source Code Documentation

• Component Documentation: Document _layouts/ and _includes/ with usage examples
• Script Documentation: Explain automation scripts in /scripts/ with parameter details
• Testing Documentation: Document test cases and validation procedures
• Configuration Documentation: Explain Jekyll configs, Docker setup, and environment variables

🚀 Publishing Process

1. Technical Review: Ensure accuracy of implementation details
2. Code Examples: Verify all code snippets are current and functional
3. Testing: Validate that documented procedures work correctly
4. Version Control: Tag documentation with appropriate version numbers

🌐 Documentation Ecosystem

📚 Related Documentation Locations

🔀 Content Flow & Conversion

• Source: Technical documentation written in MDX format in /docs/
• Processing: MDX files converted to Markdown for public consumption
• Publication: Processed content placed in /pages/_docs/ for online rendering
• Distribution: Jekyll builds and serves content to users via GitHub Pages

📖 Quick Reference

Recent Releases

• v0.5.0 - Comprehensive Sitemap Integration
• v0.4.0 - Statistics Dashboard
• v0.3.0 - Mermaid Integration

Key Features

• Statistics Dashboard
• Sitemap Integration
• Automated Version System

Configuration

• URL Configuration
• Development Setup

Last Updated: October 26, 2025
Maintained By: Zer0-Mistakes Development Team