TypeDoc Theme Firstbreath

A modern, beautiful TypeDoc theme with seamless integration of typedoc-umlclass and typedoc-plugin-coverage. Built with React, Tailwind CSS, and designed to match the Firstbreath brand colors from my-app.

✨ Features

• 🎨 Modern Design: Beautiful, clean interface with gradient accents and smooth animations
• 📊 UML Diagrams: Fully styled integration with typedoc-umlclass for visual class diagrams
• 📈 Coverage Reports: Enhanced display for typedoc-plugin-coverage with beautiful metrics cards
• 🎯 Firstbreath Colors: Matches the blue color scheme from your main application
• 📱 Responsive: Mobile-first design that works on all screen sizes
• 🌗 Dark Mode: Automatic dark mode support based on system preferences
• ⚡ Performance: Optimized CSS with Tailwind for minimal file size
• 🖨️ Print-Friendly: Special styles for printing documentation

📦 Installation

For my-app project

cd /Users/nathandelenclos/Project/EIP/my-app
npm install --save-dev typedoc typedoc-plugin-coverage typedoc-umlclass
npm install --save-dev ../typedoc-theme-firstbreath

Or with a symlink for local development:

cd /Users/nathandelenclos/Project/EIP/my-app
npm link ../typedoc-theme-firstbreath

For other projects

npm install --save-dev @firstbreath/typedoc-theme-firstbreath typedoc-plugin-coverage typedoc-umlclass

🚀 Usage

Configuration

Create a typedoc.json file in your project root:

{
  "entryPoints": ["./src/**/*.ts"],
  "out": "docs",
  "theme": "firstbreath",
  "plugin": [
    "typedoc-plugin-coverage",
    "typedoc-umlclass"
  ],
  "name": "My Project Documentation"
}

Generate Documentation

Add to your package.json:

{
  "scripts": {
    "docs": "typedoc",
    "docs:serve": "npx serve docs"
  }
}

Then run:

npm run docs

🎨 Theme Features

Coverage Integration

The theme automatically styles coverage reports with:

• Animated progress bars with gradient fills
• Color-coded metrics (green for high, amber for medium, red for low)
• Dashboard-style cards for key metrics
• Enhanced tables with hover effects
• Status indicators for documentation coverage

UML Class Diagrams

UML diagrams are displayed with:

• Card-based layout with shadows and hover effects
• Gradient headers in Firstbreath blue
• Icon indicators for methods (⚡) and properties (📦)
• Hover animations for better interactivity
• Relation styling with different line types for inheritance, composition, etc.

Modern TypeDoc Elements

• Gradient title headers with text gradients
• Enhanced navigation with smooth transitions
• Code blocks with modern syntax highlighting
• Signature blocks with hover effects
• Search box with icon and focus states
• Badge system for different element types (Class, Interface, Function, etc.)

🎨 Color Scheme

The theme uses the Firstbreath blue palette, aligned with my-app:

• Primary: #2563eb (Blue 600)
• Primary Dark: #1d4ed8 (Blue 700)
• Primary Light: #60a5fa (Blue 400)
• Accent: #3b82f6 (Blue 500)

CSS Variables

Available CSS custom properties:

--fb-primary: #2563eb;
--fb-primary-dark: #1d4ed8;
--fb-primary-light: #60a5fa;
--fb-accent: #3b82f6;
--fb-coverage-high: #22c55e;
--fb-coverage-medium: #f59e0b;
--fb-coverage-low: #ef4444;

🛠️ Development

Build the theme

# Build both web assets and TypeScript
npm run build

# Build only web assets (CSS/JS)
npm run build:web

# Build only TypeScript
npm run build:theme

# Development mode for web assets
npm run dev:web

Project Structure

typedoc-theme-firstbreath/
├── src/
│   ├── theme/
│   │   └── FirstbreathTheme.ts    # Main theme class
│   └── index.ts                    # Plugin entry point
├── web/
│   └── src/
│       ├── index.css               # Tailwind CSS with custom styles
│       └── main.tsx                # React components (if needed)
├── web-dist/                       # Built CSS/JS assets
├── dist/                           # Compiled TypeScript
└── example/                        # Example configuration

📋 Requirements

• TypeDoc >= 0.28.0
• Node.js >= 18.0.0
• typedoc-plugin-coverage >= 4.0.0
• typedoc-umlclass >= 0.10.0

🎯 Best Practices

1. Document your code: The theme works best with well-documented TypeScript code
2. Use JSDoc comments: Add descriptions, examples, and parameter docs
3. Enable coverage: Set a coverage minimum in your config (e.g., 70%)
4. Organize with categories: Use @category tags to group related items
5. Add UML diagrams: The theme automatically styles class diagrams beautifully

📖 Example Documentation Structure

/**
 * User authentication service
 * 
 * @category Services
 * @example
 * ```typescript
 * const auth = new AuthService();
 * await auth.login('[email protected]', 'password');
 * ```
 */
export class AuthService {
  /**
   * Authenticate a user with email and password
   * 
   * @param email - User's email address
   * @param password - User's password
   * @returns Authentication token
   * @throws {AuthError} If credentials are invalid
   */
  async login(email: string, password: string): Promise<string> {
    // Implementation
  }
}

🤝 Contributing

1. Fork the repository
2. Create your feature branch
3. Make your changes
4. Build and test: npm run build
5. Submit a pull request

📄 License

MIT © Firstbreath

🔗 Links

• TypeDoc Documentation
• typedoc-plugin-coverage
• typedoc-umlclass
• Tailwind CSS

Made with ❤️ for the Firstbreath project