@confytome/html

Professional styled HTML documentation generator for confytome. Generates clean, responsive HTML documentation from OpenAPI specifications with modern styling and navigation.

✨ Features

• 🎨 Professional Styling - Clean, modern design with responsive layout
• 📱 Mobile-First Design - Works perfectly on desktop, tablet, and mobile
• 🏷️ Organized by Tags - Groups endpoints by API sections for easy navigation
• 🎯 Method Color Coding - Visual distinction for GET, POST, PUT, DELETE operations
• 📄 Self-contained - Single HTML file with embedded CSS and no external dependencies
• 🌍 Unicode Support - Full international character support
• 🖨️ Print-friendly - Optimized for both screen and print media

📦 Installation

# Global installation
npm install -g @confytome/html

# Or use with npx (no installation)
npx @confytome/html --help

🚀 Usage

Standalone Usage (Recommended)

# Use existing OpenAPI spec - No additional dependencies required
npx @confytome/html --spec ./path/to/your-api-spec.json --output ./docs

With confytome.json Configuration

# Generate from API code - Requires @confytome/core
npx @confytome/html --config ./confytome.json --output ./api-docs

⚙️ Options

| Option | Short | Description | Default | |--------|-------|-------------|---------| | --config | -c | Path to confytome.json config file | ./confytome.json | | --output | -o | Output directory for generated files | ./docs | | --spec | | Path to existing OpenAPI spec file | | | --version | -V | Show version number | | | --help | -h | Show help information | | | --no-brand | | Exclude confytome branding from documentation | |

🎯 Two Usage Scenarios

✅ Scenario 1: Standalone with Existing Spec

Perfect when you already have an OpenAPI specification file.

npx @confytome/html --spec ./my-api-spec.json

• ✅ No additional dependencies
• ✅ Works immediately
• ✅ Perfect for CI/CD pipelines

⚙️ Scenario 2: Generate from Code

When you need to generate the OpenAPI spec from your API code first.

npx @confytome/html --config ./confytome.json

• ⚠️ Requires @confytome/core for spec generation
• ✅ Full workflow from code to documentation
• ✅ Automatic spec generation

If @confytome/core is not installed, you'll see helpful guidance:

💡 You have two options:
   1. Install @confytome/core:
      npm install -g @confytome/core
   2. Provide existing OpenAPI spec:
      npx @confytome/html --spec path/to/spec.json

📁 Generated Output

Creates api-docs.html in the specified output directory - a professional HTML documentation file with:

• API information panel with version and contact details
• Server configuration display
• Organized endpoint documentation grouped by tags
• Parameter details with types and validation
• Response code documentation
• Print-friendly styling

Generated File Structure

docs/
├── api-docs.html
├── api-spec.json

Content Features

• Color-coded HTTP methods (GET=green, POST=blue, PUT=yellow, DELETE=red)
• Collapsible sections for better organization
• Syntax highlighting for code elements
• Responsive navigation for large APIs
• Information panels for API metadata

🔧 Dependencies

• commander: CLI argument parsing

When using --spec option: No additional dependencies required When using --config option: Requires @confytome/core for OpenAPI spec generation

💡 Examples

Basic Usage

# Simple generation with existing spec
npx @confytome/html --spec ./docs/api-spec.json --output ./public

CI/CD Integration

#!/bin/bash
# Generate HTML documentation in CI
npx @confytome/html \\
   --spec ./build/api-spec.json \\
   --output ./dist/docs

Multiple Environments

# Production docs
npx @confytome/html \\
   --spec ./specs/prod-api.json \\
   --output ./docs/prod

# Staging docs
npx @confytome/html \\
   --spec ./specs/staging-api.json \\
   --output ./docs/staging

"Specified OpenAPI spec file not found"

# Check file path exists
ls -la ./path/to/your-spec.json

# Use absolute path if needed
npx @confytome/html --spec $(pwd)/api-spec.json

"OpenAPI spec not found, generating it first"

This means you're using config mode but don't have @confytome/core installed.

# Option 1: Install core
npm install -g @confytome/core

# Option 2: Use existing spec instead
npx @confytome/html --spec ./path/to/existing-spec.json

🌟 Part of confytome Ecosystem

@confytome/html is part of the confytome documentation ecosystem:

• @confytome/core - Plugin system & OpenAPI generator
• @confytome/markdown - Confluence-friendly Markdown docs
• @confytome/html - Professional HTML docs
• @confytome/swagger - Interactive Swagger UI
• @confytome/postman - Postman collections

📄 License

MIT License - see the LICENSE file for details.

Generate beautiful HTML documentation from OpenAPI specifications in seconds.