> ## Documentation Index
> Fetch the complete documentation index at: https://lunr-f6858e75.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Output formats
> Choose the right format for your release notes
## 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.
```bash theme={}
helixcommit generate --format markdown --out RELEASE_NOTES.md
```
### Example output
```markdown theme={}
## 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
Renders perfectly in GitHub releases and README files
Clean, scannable format for developers and users
Commit SHAs are included for easy reference
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.
```bash theme={}
helixcommit generate --format html --out changelog.html
```
### Example output
```html theme={}
Release Notes - v1.2.1
Release v1.2.1
Released on November 13, 2025
Features
api: Add user authentication endpoint (abc123)
ui: Implement dark mode toggle (def456)
Bug Fixes
parser: Fix handling of multiline commit messages (jkl012)
```
### Features
Includes CSS for professional appearance
Drop into any website or email
Looks great on desktop and mobile
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:
```bash theme={}
# In your HelixCommit installation
src/helixcommit/formatters/html.py
```
Edit the CSS section in the template to match your brand:
```python theme={}
# html.py
def render_html(changelog):
template = """
"""
```
```python theme={}
from helixcommit.formatters import html
# Your custom formatter logic
```
## Text format
Plain text output for terminals, logs, and simple notifications.
```bash theme={}
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
Perfect for CLI output and logs
Works everywhere, no formatting dependencies
Easy to parse with shell scripts
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.
```bash theme={}
helixcommit generate --format json --out changelog.json
```
### Example output
```json theme={}
{
"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
Parse directly with any JSON library
Access all metadata, references, and details
Build custom tools and integrations
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
```bash theme={}
# 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.
```bash theme={}
helixcommit generate --format yaml --out changelog.yaml
```
### Example output
```yaml theme={}
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
Easier to read than JSON with cleaner syntax
Native format for many CI/CD tools and configs
Access all metadata, references, and details
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
```bash theme={}
# 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
**Use Markdown**
```bash theme={}
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.
**Use HTML**
```bash theme={}
helixcommit generate --format html --out public/changelog.html
```
HTML gives you complete control over styling and integrates seamlessly into websites.
**Use Text or Markdown**
```bash theme={}
# 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.
**Use HTML for rich emails, Text for plain text**
```bash theme={}
# 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.
**Use Text or JSON**
```bash theme={}
# 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.
**Use JSON or YAML**
```bash theme={}
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.
**Use YAML**
```bash theme={}
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:
```bash theme={}
# 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:
```bash theme={}
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 theme={}
## 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)
```
```html theme={}
Release v2.0.0