📖 Documentation Workflow Guide¶

This guide explains how to contribute to the Zer0-Mistakes documentation ecosystem, including when to use each documentation directory, content formats, and the conversion pipeline between technical and public documentation.

🎯 Documentation Strategy Overview¶

Zer0-Mistakes uses a dual documentation architecture that serves two distinct audiences:

Technical Documentation (/docs/) - For developers, contributors, and maintainers
Public Documentation (/pages/_docs/) - For end-users and theme adopters

📁 Directory Usage Decision Tree¶

graph TD
    A[New Documentation Content] --> B{Who is the primary audience?}
    B -->|Developers & Contributors| C[Technical Implementation?]
    B -->|End Users & Theme Adopters| D[General Technology Guide?]

    C -->|Yes - Build processes, architecture| E[/docs/ - MDX Format]
    C -->|No - User-focused tutorials| F[/pages/_docs/ - Markdown]

    D -->|Yes - Jekyll, Bootstrap basics| F
    D -->|No - Repository-specific| G{Content Type?}

    G -->|Feature usage for users| F
    G -->|Feature implementation| E

    E --> H[Rich MDX with components]
    F --> I[Standard Markdown]

🛠️ Technical Documentation (`/docs/`)¶

When to Use `/docs/`¶

System architecture and infrastructure documentation
Feature implementation guides for developers
Build processes and automation workflows
Component development (layouts, includes, plugins)
Testing procedures and quality assurance
Release management and version control processes
Docker configuration and containerization
CI/CD pipeline documentation

Content Format: MDX¶

Technical documentation uses MDX format for rich, interactive content:

---
title: "Feature Implementation Guide"
description: "Technical implementation of theme features"
type: "technical-documentation"
audience: "developers"
last_updated: "2025-11-16"
---

# Feature Implementation Guide

## Architecture Overview

This feature integrates with the Jekyll build process through:

<CodeBlock language="ruby">
```ruby
module JekyllThemeZer0
  class FeatureGenerator < Jekyll::Generator
    def generate(site)
      # Implementation details
    end
  end
end

Testing Implementation¶

./test/test_feature.sh

### File Organization

/docs/ ├── systems/ # Infrastructure & automation ├── features/ # Component implementation ├── configuration/ # Development setup ├── releases/ # Version management ├── jekyll/ # Jekyll-specific technical docs ├── templates/ # Documentation templates └── _includes/ # Reusable MDX components

## 📖 Public Documentation (`/pages/_docs/`)

### When to Use `/pages/_docs/`

- **User tutorials** and getting started guides
- **Theme customization** instructions for end-users
- **General technology guides** (Jekyll basics, Bootstrap usage)
- **Configuration examples** for typical use cases
- **Troubleshooting guides** for common user issues
- **API references** and option documentation
- **External documentation** imports (Jekyll docs, Bootstrap docs)

### Content Format: Markdown

Public documentation uses **standard Markdown** for Jekyll compatibility:

````markdown
---
title: "Getting Started with Theme Customization" description: "Learn how to customize the Zer0-Mistakes theme" layout: default categories: [tutorials, customization] tags: [jekyll, theme, bootstrap]
permalink: /docs/customization-guide/
---

# Getting Started with Theme Customization

This guide walks you through customizing the Zer0-Mistakes theme for your site.

## Basic Configuration

Edit your `_config.yml` file to customize theme settings:

```yaml
# Site configuration
title: "Your Site Name"
description: "Your site description"

# Theme settings
theme_config:
  navbar_style: "dark"
  enable_sidebar: true

## Customizing Colors

Override Bootstrap variables in your custom CSS:

```css
:root {
  --bs-primary: #your-color;
  --bs-secondary: #your-secondary-color;
}
```

```

### File Organization

```

/pages/\_docs/
├── index.md # Documentation library index
├── jekyll/ # Jekyll user guides
├── bootstrap/ # Bootstrap usage guides
├── customization/ # Theme customization
├── deployment/ # Hosting and deployment
└── troubleshooting/ # Common issues and solutions

🔄 Content Conversion Pipeline¶

MDX to Markdown Conversion¶

Technical documentation in /docs/ can be converted to public documentation:

1. Automated Conversion Script¶

#!/bin/bash
# scripts/convert_docs.sh

# Convert technical MDX to public Markdown
./scripts/mdx-to-markdown.sh \
  --source docs/features/component-guide.mdx \
  --output pages/_docs/customization/components.md \
  --audience user \
  --strip-technical-details \
  --add-user-examples
````

#### 2. Manual Conversion Process

1. **Source Analysis**: Review technical MDX content for user-relevant information
2. **Content Extraction**: Extract user-facing information and examples
3. **Simplification**: Remove implementation details, add explanatory content
4. **Format Conversion**: Convert MDX components to standard Markdown
5. **Testing**: Verify Jekyll rendering and link functionality

#### 3. Conversion Guidelines

**Technical → Public Conversion:**

- Remove implementation details and source code references
- Add explanatory text for user context
- Convert interactive MDX components to static examples
- Focus on "how to use" rather than "how it works"
- Include troubleshooting for user-facing issues

## 🔧 External Documentation Import

### Importing Official Documentation

Import external documentation using git submodules:

```bash
# Import Jekyll documentation
git submodule add https://github.com/jekyll/jekyll.git external/jekyll-docs

# Configure sparse checkout for relevant sections
cd external/jekyll-docs
git sparse-checkout init --cone
git sparse-checkout set docs/_docs

# Process and integrate
./scripts/import-external-docs.sh jekyll-docs docs/_docs pages/_docs/jekyll/

Processing External Content¶

Source Filtering: Extract relevant documentation sections
Content Cleanup: Remove external branding and navigation
Integration: Add Zer0-Mistakes front matter and styling
Cross-linking: Add references to theme-specific features
Testing: Verify Jekyll processing and site integration

📝 Writing Guidelines¶

Technical Documentation Standards¶

Code Examples: Include actual implementation code from source files
Architecture Diagrams: Use Mermaid for system visualization
Testing Instructions: Provide validation procedures for changes
Performance Notes: Document impact on build time and runtime
Security Considerations: Address potential security implications
Maintainer Context: Explain design decisions for future developers

Public Documentation Standards¶

User-Focused: Write for theme adopters and general users
Step-by-Step: Provide clear, sequential instructions
Practical Examples: Include real-world use cases and configurations
Troubleshooting: Address common issues and solutions
Cross-References: Link to related guides and external resources
Accessibility: Ensure content is readable and inclusive

🚀 Publication Workflow¶

Development Process¶

Local Development:

# Start development environment
docker-compose up

# Test documentation changes
open http://localhost:4000/docs/

Content Review:
Technical accuracy validation
User experience testing
Cross-reference verification
Accessibility compliance check
Integration Testing:

# Validate Jekyll processing
bundle exec jekyll build

# Test documentation links
./scripts/test-doc-links.sh

# Verify MDX conversion
./scripts/validate-conversion.sh

Publication Pipeline¶

graph LR
    A[Write Documentation] --> B[Local Testing]
    B --> C[Content Review]
    C --> D[Integration Testing]
    D --> E[Pull Request]
    E --> F[Automated CI/CD]
    F --> G[Deploy to GitHub Pages]
    G --> H[Published Documentation]

🤖 GitHub Copilot Integration¶

The documentation system is optimized for AI-assisted development:

Copilot-Optimized Structure¶

Front Matter: Comprehensive metadata for AI context
Component Documentation: Clear usage patterns and dependencies
Code Examples: Annotated implementation patterns
Cross-References: Explicit relationships between components

AI Development Assistance¶

Use GitHub Copilot for generating documentation templates
Leverage AI for code example generation and validation
Employ AI for consistency checking across documentation
Utilize AI for translation between technical and user documentation

📊 Quality Assurance¶

Documentation Testing¶

# Run documentation test suite
./test/test_documentation.sh

# Validate external links
./test/test_external_links.sh

# Check MDX to Markdown conversion
./test/test_conversion_pipeline.sh

# Verify Jekyll processing
./test/test_jekyll_build.sh

Metrics and Monitoring¶

Conversion Success Rate: Track MDX to Markdown conversion accuracy
Link Validation: Monitor external and internal link health
User Feedback: Collect feedback on documentation clarity and completeness
Search Analytics: Monitor documentation usage patterns

Last Updated: November 16, 2025 Maintained By: Zer0-Mistakes Documentation Team

📚 Related Guides: Contributing Guidelines • Technical Documentation Standards • Public Documentation Template