Output formats - HelixCommit

Overview

HelixCommit supports five output formats: Markdown, HTML, plain text, JSON, and YAML. Each format is optimized for different use cases, from GitHub releases to programmatic integrations.

Markdown format

The default format, perfect for documentation sites, GitHub releases, and version control.

helixcommit generate --format markdown --out RELEASE_NOTES.md

Example output

## Release v1.2.1
_Released on 2025-11-13_

### Features
- **api**: Add user authentication endpoint (abc123)
- **ui**: Implement dark mode toggle (def456)
- Add support for custom templates (ghi789)

### Bug Fixes
- **parser**: Fix handling of multiline commit messages (jkl012)
- Resolve rate limiting in GitHub client (mno345)

### Breaking Changes
- **api**: Remove deprecated /v1/users endpoint (pqr678)

### Documentation
- Update API reference with new endpoints (stu901)

[View full changelog](https://github.com/owner/repo/compare/v1.2.0...v1.2.1)

Features

GitHub-compatible

Renders perfectly in GitHub releases and README files

Human-readable

Clean, scannable format for developers and users

Linkable commits

Commit SHAs are included for easy reference

Categorized sections

Organized by commit type (features, fixes, etc.)

Use cases

GitHub releases: Copy directly to release descriptions
CHANGELOG.md: Maintain version history
Documentation sites: Embed in Mintlify, Docusaurus, etc.
Pull request descriptions: Reference changes

Markdown format includes compare URLs when GitHub integration is enabled, making it easy to see all changes between versions.

HTML format

Professional HTML output ready for embedding in websites or sending via email.

helixcommit generate --format html --out changelog.html

Example output

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>Release Notes - v1.2.1</title>
  <style>
    body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; }
    .release { margin: 2rem 0; }
    .section { margin: 1.5rem 0; }
    h2 { color: #1a202c; }
    h3 { color: #2d3748; }
    ul { list-style: none; padding: 0; }
    li { margin: 0.5rem 0; }
    .commit-sha { color: #718096; font-family: monospace; }
  </style>
</head>
<body>
  <div class="release">
    <h2>Release v1.2.1</h2>
    <p class="date">Released on November 13, 2025</p>
    
    <div class="section">
      <h3>Features</h3>
      <ul>
        <li><strong>api:</strong> Add user authentication endpoint <span class="commit-sha">(abc123)</span></li>
        <li><strong>ui:</strong> Implement dark mode toggle <span class="commit-sha">(def456)</span></li>
      </ul>
    </div>
    
    <div class="section">
      <h3>Bug Fixes</h3>
      <ul>
        <li><strong>parser:</strong> Fix handling of multiline commit messages <span class="commit-sha">(jkl012)</span></li>
      </ul>
    </div>
  </div>
</body>
</html>

Features

Styled output

Includes CSS for professional appearance

Embeddable

Drop into any website or email

Responsive

Looks great on desktop and mobile

Printable

Print-friendly layout

Use cases

Product websites: Embed in /changelog pages
Email campaigns: Send formatted updates to users
Internal dashboards: Display recent changes
PDF generation: Convert to PDF for stakeholders

HTML output includes semantic markup for accessibility and SEO.

Customization

The HTML formatter uses Jinja2 templates. You can customize the styling by modifying the template:

Locate the HTML formatter

# In your HelixCommit installation
src/helixcommit/formatters/html.py

Modify the CSS

Edit the CSS section in the template to match your brand:

# html.py
def render_html(changelog):
    template = """
    <style>
        body { font-family: 'Your Font', sans-serif; }
        h2 { color: #your-color; }
        /* Add your styles */
    </style>
    """

Use programmatically

from helixcommit.formatters import html
# Your custom formatter logic

Text format

Plain text output for terminals, logs, and simple notifications.

helixcommit generate --format text --out CHANGES.txt

Example output

================================================================================
Release v1.2.1
Released on 2025-11-13
================================================================================

FEATURES
--------
* api: Add user authentication endpoint (abc123)
* ui: Implement dark mode toggle (def456)
* Add support for custom templates (ghi789)

BUG FIXES
---------
* parser: Fix handling of multiline commit messages (jkl012)
* Resolve rate limiting in GitHub client (mno345)

BREAKING CHANGES
----------------
* api: Remove deprecated /v1/users endpoint (pqr678)

DOCUMENTATION
-------------
* Update API reference with new endpoints (stu901)

Full changelog: https://github.com/owner/repo/compare/v1.2.0...v1.2.1

Features

Terminal-friendly

Perfect for CLI output and logs

Universal

Works everywhere, no formatting dependencies

Scriptable

Easy to parse with shell scripts

Lightweight

Minimal file size

Use cases

Slack/Discord bots: Post updates to team channels
Email (plain text): Send simple text notifications
Log files: Record releases in application logs
Git commit messages: Include in merge commits
Terminal display: Quick review during development

Text format uses ASCII art for visual hierarchy without requiring special rendering.

JSON format

Machine-readable JSON output for programmatic use, CI/CD pipelines, and custom tooling.

helixcommit generate --format json --out changelog.json

Example output

{
  "version": "v1.2.1",
  "date": "2025-11-13T12:00:00+00:00",
  "sections": [
    {
      "title": "Features",
      "items": [
        {
          "title": "Add user authentication endpoint",
          "type": "feat",
          "scope": "api",
          "breaking": false,
          "summary": null,
          "details": null,
          "notes": [],
          "references": {
            "commit": "abc123def",
            "pr": "https://github.com/owner/repo/pull/42"
          },
          "metadata": {
            "pr_number": 42
          }
        },
        {
          "title": "Implement dark mode toggle",
          "type": "feat",
          "scope": "ui",
          "breaking": false,
          "summary": null,
          "details": null,
          "notes": [],
          "references": {
            "commit": "def456ghi"
          },
          "metadata": {}
        }
      ]
    },
    {
      "title": "Bug Fixes",
      "items": [
        {
          "title": "Fix handling of multiline commit messages",
          "type": "fix",
          "scope": "parser",
          "breaking": false,
          "summary": null,
          "details": null,
          "notes": [],
          "references": {
            "commit": "jkl012mno"
          },
          "metadata": {}
        }
      ]
    }
  ],
  "metadata": {
    "compare_url": "https://github.com/owner/repo/compare/v1.2.0...v1.2.1"
  }
}

Features

Machine-readable

Parse directly with any JSON library

Complete data

Access all metadata, references, and details

Programmatic use

Build custom tools and integrations

CI/CD friendly

Easy to process in automated pipelines

Use cases

API responses: Serve changelog data from your backend
CI/CD pipelines: Parse and process release data programmatically
Custom tooling: Build dashboards, notifications, or reports
Data analysis: Aggregate and analyze release patterns
Slack/Discord bots: Transform JSON into custom message formats

JSON format preserves all structured data including PR numbers, commit references, breaking change flags, and custom metadata.

Processing JSON output

# Extract just the version
helixcommit generate --format json | jq '.version'

# List all breaking changes
helixcommit generate --format json | jq '.sections[].items[] | select(.breaking == true)'

# Count items per section
helixcommit generate --format json | jq '.sections[] | {title: .title, count: (.items | length)}'

YAML format

Human-readable structured output for configuration files, CI/CD pipelines, and tools that prefer YAML.

helixcommit generate --format yaml --out changelog.yaml

Example output

version: v1.2.1
date: '2025-11-13T12:00:00+00:00'
sections:
  - title: Features
    items:
      - title: Add user authentication endpoint
        type: feat
        scope: api
        breaking: false
        summary: null
        details: null
        notes: []
        references:
          commit: abc123def
          pr: https://github.com/owner/repo/pull/42
        metadata:
          pr_number: 42
      - title: Implement dark mode toggle
        type: feat
        scope: ui
        breaking: false
        summary: null
        details: null
        notes: []
        references:
          commit: def456ghi
        metadata: {}
  - title: Bug Fixes
    items:
      - title: Fix handling of multiline commit messages
        type: fix
        scope: parser
        breaking: false
        summary: null
        details: null
        notes: []
        references:
          commit: jkl012mno
        metadata: {}
metadata:
  compare_url: https://github.com/owner/repo/compare/v1.2.0...v1.2.1

Features

Human-readable

Easier to read than JSON with cleaner syntax

Configuration-friendly

Native format for many CI/CD tools and configs

Complete data

Access all metadata, references, and details

Programmatic use

Parse with any YAML library in any language

Use cases

CI/CD pipelines: Native format for GitHub Actions, GitLab CI, etc.
Configuration files: Store release data alongside other YAML configs
Kubernetes: Generate release metadata for deployments
Ansible/Terraform: Integrate release data into infrastructure automation
Custom tooling: Parse and process release data programmatically

YAML format preserves all structured data like JSON but with a cleaner, more readable syntax that’s easier to edit manually.

Processing YAML output

# Extract just the version using yq
helixcommit generate --format yaml | yq '.version'

# List all breaking changes
helixcommit generate --format yaml | yq '.sections[].items[] | select(.breaking == true)'

# Count items per section
helixcommit generate --format yaml | yq '.sections[] | {"title": .title, "count": (.items | length)}'

Format comparison

Feature	Markdown	HTML	Text	JSON	YAML
GitHub releases	✅ Best	⚠️ Renders but less common	⚠️ Works but plain	❌ Not readable	❌ Not readable
Websites	✅ Good (with processor)	✅ Best	❌ Not recommended	✅ API responses	✅ API responses
Emails	⚠️ Requires client support	✅ Best	✅ Good (universal)	❌ Not readable	❌ Not readable
Terminal	✅ Good	❌ Not readable	✅ Best	⚠️ Parseable	✅ Good
Chat apps	✅ Good (Slack, Discord)	⚠️ Limited support	✅ Good	❌ Not readable	❌ Not readable
Documentation sites	✅ Best	✅ Good	❌ Not styled	❌ Not readable	❌ Not readable
Programmatic use	⚠️ Requires parsing	⚠️ Requires parsing	⚠️ Requires parsing	✅ Best	✅ Best
CI/CD pipelines	✅ Good	⚠️ Limited	✅ Good	✅ Best	✅ Best (native)
File size	Small	Medium	Smallest	Small	Small
Customizable	Limited	Highly	Limited	Via post-processing	Via post-processing

Selecting the right format

For GitHub releases and repositories

Use Markdown

helixcommit generate --format markdown --out RELEASE_NOTES.md

Markdown is the native format for GitHub and renders beautifully in releases, README files, and issue comments.

For product websites and blogs

Use HTML

helixcommit generate --format html --out public/changelog.html

HTML gives you complete control over styling and integrates seamlessly into websites.

For Slack, Discord, or chat notifications

Use Text or Markdown

# Plain text for maximum compatibility
helixcommit generate --format text

# Or Markdown if the platform supports it
helixcommit generate --format markdown

Most chat platforms support basic Markdown formatting.

For email notifications

Use HTML for rich emails, Text for plain text

# HTML version for rich email clients
helixcommit generate --format html --out email.html

# Text version for plain text email
helixcommit generate --format text --out email.txt

Send both versions using multipart MIME for best compatibility.

For CI/CD logs and scripts

Use Text or JSON

# Plain text for logs
helixcommit generate --format text

# JSON for programmatic processing
helixcommit generate --format json

Plain text displays well in logs, while JSON is ideal for parsing and automation.

For APIs and programmatic use

Use JSON or YAML

helixcommit generate --format json --out changelog.json
# or
helixcommit generate --format yaml --out changelog.yaml

JSON and YAML provide structured data that can be easily parsed by any programming language or tool. YAML is more readable, while JSON is more universal.

For CI/CD pipelines and configuration

Use YAML

helixcommit generate --format yaml --out changelog.yaml

YAML is the native format for GitHub Actions, GitLab CI, and many other CI/CD tools, making it easy to integrate release data.

Advanced formatting options

Controlling scopes

Show or hide commit scopes in all formats:

# With scopes (default)
helixcommit generate --include-scopes --format markdown
# Output: "**api**: Add authentication"

# Without scopes
helixcommit generate --no-include-scopes --format markdown
# Output: "Add authentication"

Handling empty sections

HelixCommit automatically hides empty sections (e.g., if there are no breaking changes).

Compare URLs

When GitHub integration is enabled, all formats include compare URLs:

helixcommit generate --format markdown
# Includes: [View full changelog](https://github.com/owner/repo/compare/v1.0.0...v2.0.0)

Output examples

See complete examples for each format:

Markdown
HTML
Text
JSON
YAML

## Release v2.0.0
_Released on 2025-11-13_

### Breaking Changes
- **api**: Change authentication flow to OAuth2 (abc123)

### Features
- **ui**: Add dashboard analytics (def456)
- **api**: Implement rate limiting (ghi789)

### Bug Fixes
- Fix memory leak in background tasks (jkl012)

[View full changelog](https://github.com/owner/repo/compare/v1.0.0...v2.0.0)

<!DOCTYPE html>
<html>
<head>
  <title>Release v2.0.0</title>
  <style>
    body { max-width: 800px; margin: 0 auto; padding: 2rem; }
    h2 { border-bottom: 2px solid #e2e8f0; padding-bottom: 0.5rem; }
  </style>
</head>
<body>
  <h2>Release v2.0.0</h2>
  <p><em>Released on November 13, 2025</em></p>
  <!-- ... -->
</body>
</html>

================================================================================
Release v2.0.0
Released on 2025-11-13
================================================================================

BREAKING CHANGES
----------------
* api: Change authentication flow to OAuth2 (abc123)

FEATURES
--------
* ui: Add dashboard analytics (def456)
* api: Implement rate limiting (ghi789)

BUG FIXES
---------
* Fix memory leak in background tasks (jkl012)

{
  "version": "v2.0.0",
  "date": "2025-11-13T00:00:00+00:00",
  "sections": [
    {
      "title": "Breaking Changes",
      "items": [
        {
          "title": "Change authentication flow to OAuth2",
          "type": "feat",
          "scope": "api",
          "breaking": true,
          "references": { "commit": "abc123" }
        }
      ]
    },
    {
      "title": "Features",
      "items": [
        {
          "title": "Add dashboard analytics",
          "type": "feat",
          "scope": "ui",
          "breaking": false,
          "references": { "commit": "def456" }
        },
        {
          "title": "Implement rate limiting",
          "type": "feat",
          "scope": "api",
          "breaking": false,
          "references": { "commit": "ghi789" }
        }
      ]
    },
    {
      "title": "Bug Fixes",
      "items": [
        {
          "title": "Fix memory leak in background tasks",
          "type": "fix",
          "scope": null,
          "breaking": false,
          "references": { "commit": "jkl012" }
        }
      ]
    }
  ],
  "metadata": {
    "compare_url": "https://github.com/owner/repo/compare/v1.0.0...v2.0.0"
  }
}

version: v2.0.0
date: '2025-11-13T00:00:00+00:00'
sections:
  - title: Breaking Changes
    items:
      - title: Change authentication flow to OAuth2
        type: feat
        scope: api
        breaking: true
        references:
          commit: abc123
  - title: Features
    items:
      - title: Add dashboard analytics
        type: feat
        scope: ui
        breaking: false
        references:
          commit: def456
      - title: Implement rate limiting
        type: feat
        scope: api
        breaking: false
        references:
          commit: ghi789
  - title: Bug Fixes
    items:
      - title: Fix memory leak in background tasks
        type: fix
        scope: null
        breaking: false
        references:
          commit: jkl012
metadata:
  compare_url: https://github.com/owner/repo/compare/v1.0.0...v2.0.0

Next steps

Configuration

Customize output with configuration options

Examples

See format selection in real-world scenarios

GitHub integration

Add PR links and compare URLs

CLI reference

Complete list of formatting options

​Overview

​Markdown format

​Example output

​Features

GitHub-compatible

Human-readable

Linkable commits

Categorized sections

​Use cases

​HTML format

​Example output

​Features

Styled output

Embeddable

Responsive

Printable

​Use cases

​Customization

​Text format

​Example output

​Features

Terminal-friendly

Universal

Scriptable

Lightweight

​Use cases

​JSON format

​Example output

​Features

Machine-readable

Complete data

Programmatic use

CI/CD friendly

​Use cases

​Processing JSON output

​YAML format

​Example output

​Features

Human-readable

Configuration-friendly

Complete data

Programmatic use

​Use cases

​Processing YAML output

​Format comparison

​Selecting the right format

​Advanced formatting options

​Controlling scopes

​Handling empty sections

​Compare URLs

​Output examples

​Next steps

Configuration

Examples

GitHub integration

CLI reference

Overview

Markdown format

Example output

Features

Use cases

HTML format

Example output

Features

Use cases

Customization

Text format

Example output

Features

Use cases

JSON format

Example output

Features

Use cases

Processing JSON output

YAML format

Example output

Features

Use cases

Processing YAML output

Format comparison

Selecting the right format

Advanced formatting options

Controlling scopes

Handling empty sections

Compare URLs

Output examples

Next steps