DocBuilder Documentation

Welcome to the DocBuilder documentation! This documentation follows the Diátaxis framework, organizing content by user needs.

Documentation Structure

📚 Tutorials

Learning-oriented - Step-by-step lessons to get you started.

• Getting Started - Your first DocBuilder project
• Multi-Repository Setup - Aggregate docs from multiple repos
• Theme Customization - Customize your Hugo theme

Best for: First-time users, learning the basics

🛠️ How-To Guides

Task-oriented - Practical guides for specific tasks.

• Add Content Transforms - Create custom markdown transformations
• Add Theme Support - Integrate a new Hugo theme
• Configure Forge Namespacing - Set up multi-forge projects
• Customize Index Pages - Tailor index page generation
• Enable Hugo Render - Configure Hugo rendering
• Prune Workspace Size - Optimize disk usage
• Run Incremental Builds - Speed up builds

Best for: Users with specific goals, solving problems

📖 Reference

Information-oriented - Technical specifications and API documentation.

• CLI Reference - Command-line interface documentation
• Configuration Reference - Complete config file specification
• Index File Handling - How index files are processed and precedence rules
• Build Report Reference - Build report format and fields

Best for: Looking up specific information, API details

💡 Explanation

Understanding-oriented - Conceptual documentation and design rationale.

Architecture Documentation

• Architecture Documentation Index - Start here for architecture overview
• Comprehensive Architecture - Complete system design
• Architecture Diagrams - Visual system representations
• Package Architecture Guide - Detailed package documentation
• Architecture Overview - Quick reference guide
• Namespacing Rationale - Forge namespacing design
• Renderer Testing - Hugo rendering tests

Architecture Decision Records (ADRs)

• ADR-000: Uniform Error Handling
• ADR-001: Forge Integration Daemon

Best for: Understanding why things work the way they do, architectural decisions

Quick Start Guide

New Users

1. Start with Getting Started Tutorial
2. Review CLI Reference for commands
3. Check Configuration Reference for options

Developers/Contributors

1. Read Architecture Documentation Index
2. Study Comprehensive Architecture
3. Review Package Architecture Guide
4. Check Contributing Guide

Operations/DevOps

1. Review Getting Started Tutorial
2. Check How-To: Run Incremental Builds
3. Review Build Report Reference
4. Study operational considerations in Comprehensive Architecture

Documentation by Feature

Basic Usage

• Getting Started Tutorial
• CLI Reference
• Configuration Reference

Multi-Repository Aggregation

• Multi-Repository Setup Tutorial
• Configure Forge Namespacing
• Namespacing Rationale

Theme Integration

• Theme Customization Tutorial
• Add Theme Support
• Relearn Theme Configuration

Performance Optimization

• Run Incremental Builds
• Prune Workspace Size
• Change Detection

Customization

• Add Content Transforms
• Customize Index Pages
• Index File Handling
• Theme Customization Tutorial
• Configuration Reference

Advanced Topics

• Comprehensive Architecture
• Package Architecture Guide
• Architecture Diagrams

Additional Resources

Project Documentation

• README - Project overview and quick reference
• CHANGELOG - Version history and changes
• CONTRIBUTING - Contribution guidelines
• LICENSE - Project license

Architecture & Planning

• Architecture Migration Plan - Migration status
• Plan Directory - Feature plans and ADRs
• Docs Archive - Historical documentation

Examples

• Examples Directory - Sample configurations and tools
• Example Configs - Ready-to-use configurations

Documentation Principles

This documentation follows these principles:

1. User-Centric - Organized by what users want to achieve
2. Progressive Disclosure - Start simple, add complexity as needed
3. Searchable - Clear structure, consistent terminology
4. Maintained - Updated with code changes
5. Tested - Examples are verified to work

Contributing to Documentation

We welcome documentation contributions! When contributing:

1. Follow the Diátaxis framework structure
2. Use clear, concise language
3. Include code examples where applicable
4. Test all commands and configurations
5. Update index files when adding new documents

See Contributing Guide for details.

Getting Help

• Questions: Open a GitHub Discussion
• Issues: Report bugs or feature requests via GitHub Issues
• Architecture Questions: Review Architecture Documentation first
• Usage Help: Start with Tutorials and How-To Guides

Documentation Status

Last Major Update: December 2025

Coverage:

• ✅ Getting Started Tutorial
• ✅ CLI Reference
• ✅ Configuration Reference
• ✅ Build Report Reference
• ✅ Comprehensive Architecture Documentation
• ✅ Package-Level Documentation
• ✅ Visual Architecture Diagrams
• ✅ How-To Guides
• ⏳ Additional tutorials (in progress)

Feedback: Documentation feedback is highly appreciated! Please open an issue if you find areas that need improvement.