roadmap-gen

roadmap-gen

🗺️ Professional HTML roadmap generator from YAML data

Transform your project roadmap into beautiful, interactive visualizations. Built with modern TypeScript and powered by Bun for lightning-fast performance.

✨ Features

• 🎨 Multiple Themes: Professional themes for different audiences
• 🔒 Internal/Public Control: Show/hide confidential content with --with-internal flag
• 📊 Interactive Visualizations: Project tracking across quarters with status indicators
• ⚡ Lightning Fast: Built with Bun runtime for optimal performance
• 🔧 Simple Configuration: YAML format for defining roadmaps
• 🚀 Dual Usage: CLI tool and programmatic API
• 📱 Responsive Design: Works on desktop, tablet, and mobile

🛠️ Installation

Package Manager

# Using Bun (recommended)
bun add roadmap-gen

# Using npm
npm install roadmap-gen

# Using yarn
yarn add roadmap-gen

Pre-compiled Binaries

Download from releases page for Linux, macOS, or Windows.

🚀 Quick Start

CLI Usage

# Basic usage
bunx roadmap-gen
npx roadmap-gen

# With custom source
roadmap-gen --source ./my-roadmap.yaml

# Include internal/confidential content
roadmap-gen --with-internal

# With all options
roadmap-gen -s ./my-roadmap.yaml -t themes/cards -o ./public --with-internal

# Show help
roadmap-gen --help

Programmatic API

import { build } from 'roadmap-gen';

await build(); // Uses defaults (public view)
await build('./data.yaml', 'themes/cards', './dist', true); // With internal content
await build('./data.yaml', 'themes/cards', './public');

📝 YAML Configuration

Create a roadmap.yaml file (see example.yml for complete reference):

title: 'Product Roadmap 2025'
vision: 'Building the future of our platform'
quarters: ['Q1-2025', 'Q2-2025', 'Q3-2025', 'Q4-2025']
next_quarters: ['Q2-2025'] # Highlighted quarters

categories:
  - name: 'Infrastructure'
    icon: '🏗️'
    projects:
      - name: 'Cloud Migration'
        responsible: 'DevOps Team'
        issue: 'https://github.com/org/repo/issues/123'
        # A project can be public or internal (0.4.0+)
        # internal: true
        quarters:
          Q1-2025:
            status: 'in-progress'
            description: 'Migrating core services'
            details:
              - 'Database migration completed'
              - text: 'Internal: Vendor contract details'
                internal: true # Hidden from public roadmaps (0.4.0+)
            progress: '60%'
            internal_notes: 'Budget approval pending' # Hidden from public roadmaps (0.4.0+)

🎨 Themes

Professional themes for different audiences:

• light - Clean minimal design
• cards - Project cards layout for visual presentations
• compact - Ultra-dense table for many projects
• mobile - Mobile-first responsive design
• timeline - Enhanced chronological visualization

See themes/README.md for details and custom theme creation.

🔧 Development

git clone https://github.com/davlgd/roadmap-gen.git
cd roadmap-gen
bun install
bun test

🤝 Contributing

• Fork the repository
• Create a feature branch
• Make your changes with tests
• Submit a pull request

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🚀 Built With

• Bun - Runtime and toolkit
• TypeScript - Type safety
• js-yaml - YAML parsing

Made with ❤️ and powered by Bun

⭐ Star this repo if you find it useful!

Changelog

[0.4.0] - 2025-08-11

Added

• 🔒 Internal/Public Content Control: Major new feature for controlling content visibility
  • --with-internal CLI flag to include confidential content
  • internal: true flag for projects, quarters, details, and metrics
  • internal_notes field for sensitive quarter information (always excluded from public view)
  • Granular control at multiple levels: entire projects, specific quarters, individual details, or metrics
  • Automatic filtering of empty categories after internal content removal

Enhanced

• TypeScript Types: Extended with DetailItem, MetricItem, and union types (DetailEntry, MetricEntry)
• HTML Generation: Updated utilities with detailEntriesToStrings() and metricEntriesToStrings() helpers
• Build Process: Enhanced filtering pipeline with comprehensive content processing
• Template System: Support for new data structures while maintaining backward compatibility

Technical

• New Filtering Logic: filterInternalContent() function with multi-level content filtering
• Helper Functions: filterDetailEntries() and filterMetricEntries() for granular filtering
• Code Quality: Refactored build function to reduce complexity (split into smaller functions)
• Test Coverage: 4 new comprehensive tests for internal content filtering scenarios

Security

• Content Privacy: Ensures sensitive information is never leaked to public roadmaps
• Default Behavior: Public-first approach - internal content hidden by default
• Validation: Comprehensive filtering at all data structure levels