pugz/docs/ORGANIZATION.md

Project Organization Summary

Documentation Rule

All documentation files (.md) must be saved to the docs/ directory.

This rule is enforced in CLAUDE.md to ensure consistent documentation organization.

Current Structure

pugz/
├── README.md                 # Main project README (only .md in root)
├── docs/                     # All documentation goes here
│   ├── INDEX.md             # Documentation index
│   ├── CLAUDE.md            # Development guide
│   ├── api.md               # API reference
│   ├── syntax.md            # Pug syntax guide
│   ├── EXAMPLES.md          # Examples overview
│   ├── DEMO_SERVER.md       # HTTP server guide
│   ├── CLI_TEMPLATES_DEMO.md
│   ├── FEATURES_REFERENCE.md
│   ├── PUGJS_COMPATIBILITY.md
│   ├── COMPILED_TEMPLATES.md
│   ├── COMPILED_TEMPLATES_STATUS.md
│   ├── CLI_TEMPLATES_COMPLETE.md
│   ├── VERIFICATION.md
│   ├── BUILD_SUMMARY.md
│   └── ORGANIZATION.md      # This file
├── src/                      # Source code
├── examples/                 # Example code (NO .md files)
│   ├── demo/                # HTTP server example
│   ├── cli-templates-demo/  # Feature examples
│   └── use_compiled_templates.zig
├── tests/                    # Test files
└── zig-out/                  # Build output
    └── bin/
        └── pug-compile      # CLI tool

Benefits of This Organization

1. Centralized Documentation

• All docs in one place: docs/
• Easy to find and browse
• Clear separation from code and examples

2. Clean Examples Directory

• Examples contain only code
• No README clutter
• Easier to copy/paste example code

3. Version Control

• Documentation changes are isolated
• Easy to review doc-only changes
• Clear commit history

4. Tool Integration

• Documentation generators can target docs/
• Static site generators know where to look
• IDEs can provide better doc navigation

Documentation Categories

Getting Started (5 files)

• README.md (root)
• docs/INDEX.md
• docs/CLAUDE.md
• docs/api.md
• docs/syntax.md

Examples & Tutorials (5 files)

• docs/EXAMPLES.md
• docs/DEMO_SERVER.md
• docs/CLI_TEMPLATES_DEMO.md
• docs/FEATURES_REFERENCE.md
• docs/PUGJS_COMPATIBILITY.md

Implementation Details (4 files)

• docs/COMPILED_TEMPLATES.md
• docs/COMPILED_TEMPLATES_STATUS.md
• docs/CLI_TEMPLATES_COMPLETE.md
• docs/VERIFICATION.md

Meta Documentation (2 files)

• docs/BUILD_SUMMARY.md
• docs/ORGANIZATION.md

Total: 16 documentation files

Creating New Documentation

When creating new documentation:

1. Always save to docs/ - Never create .md files in root or examples
2. Use descriptive names - FEATURE_NAME.md not doc1.md
3. Update INDEX.md - Add link to new doc in the index
4. Link related docs - Cross-reference related documentation
5. Keep README.md clean - Only project overview, quick start, and links to docs

Example Workflow

# ❌ Wrong - creates doc in root
echo "# New Doc" > NEW_FEATURE.md

# ✅ Correct - creates doc in docs/
echo "# New Doc" > docs/NEW_FEATURE.md

# Update index
echo "- [New Feature](NEW_FEATURE.md)" >> docs/INDEX.md

Maintenance

Regular Tasks

• Keep INDEX.md updated with new docs
• Remove outdated documentation
• Update cross-references when docs move
• Ensure all docs have clear purpose

Quality Checks

• All .md files in docs/ (except README.md in root)
• No .md files in examples/
• INDEX.md lists all documentation
• Cross-references are valid

Verification

Check documentation organization:

# Should be 1 (only README.md)
ls *.md 2>/dev/null | wc -l

# Should be 16 (all docs)
ls docs/*.md | wc -l

# Should be 0 (no docs in examples)
find examples/ -name "*.md" | wc -l

---

Last Updated: 2026-01-28
Organization Status: ✅ Complete
Total Documentation Files: 16