gh-action-readme/docs/configuration.md

Configuration

Configure gh-action-readme with persistent settings, environment variables, and advanced options.

📁 Configuration File

Create persistent settings with XDG-compliant configuration:

gh-action-readme config init

Default Location

• Linux/macOS: ~/.config/gh-action-readme/config.yaml
• Windows: %APPDATA%\gh-action-readme\config.yaml

Configuration Format

# ~/.config/gh-action-readme/config.yaml
theme: github
output_format: md
output_dir: .
verbose: false
github_token: ""
dependencies_enabled: true
cache_ttl: 3600

🔧 Configuration Options

Core Settings

Option	Type	Default	Description
theme	string	default	Default theme to use
output_format	string	md	Default output format
output_dir	string	.	Default output directory
verbose	boolean	false	Enable verbose logging

GitHub Integration

Option	Type	Default	Description
github_token	string	""	GitHub personal access token
dependencies_enabled	boolean	true	Enable dependency analysis
rate_limit_delay	int	1000	Delay between API calls (ms)

Performance Settings

Option	Type	Default	Description
cache_ttl	int	3600	Cache TTL in seconds
concurrent_requests	int	3	Max concurrent GitHub API requests
timeout	int	30	Request timeout in seconds

🌍 Environment Variables

Override configuration with environment variables:

# Core settings
export GH_ACTION_README_THEME=github
export GH_ACTION_README_OUTPUT_FORMAT=html
export GH_ACTION_README_OUTPUT_DIR=docs
export GH_ACTION_README_VERBOSE=true

# GitHub settings
export GITHUB_TOKEN=your_token_here
export GH_ACTION_README_DEPENDENCIES=true

# Performance settings
export GH_ACTION_README_CACHE_TTL=7200
export GH_ACTION_README_TIMEOUT=60

Environment Variable Priority

1. Command line flags (highest priority)
2. Environment variables
3. Configuration file
4. Built-in defaults (lowest priority)

🎛️ Interactive Configuration

Use the interactive wizard for guided setup:

gh-action-readme config wizard

Wizard Features

• Auto-detection of project settings
• GitHub token setup with validation
• Theme preview with examples
• Export options (YAML, JSON, TOML)
• Real-time validation with suggestions

Wizard Example

$ gh-action-readme config wizard

✨ Welcome to gh-action-readme configuration wizard!

🔍 Detected project settings:
  Repository: ivuorinen/my-action
  Language: JavaScript/TypeScript

📋 Select your preferences:
  Theme: github, gitlab, minimal, professional, default
  >> github

  Output format: md, html, json, asciidoc
  >> md

🔑 GitHub Token (optional, for enhanced features):
  >> ghp_xxxxxxxxxxxx
  ✅ Token validated successfully!

💾 Export configuration as:
  Format: yaml, json, toml
  >> yaml

✅ Configuration saved to ~/.config/gh-action-readme/config.yaml

🎨 Theme Configuration

Built-in Themes

# List available themes
gh-action-readme config themes

# Set default theme
gh-action-readme config set theme github

Custom Themes

Create custom themes by copying existing ones:

# Copy existing theme
cp -r templates/themes/github templates/themes/custom

# Edit template
vim templates/themes/custom/readme.tmpl

# Use custom theme
gh-action-readme gen --theme custom

Theme Directory Structure

templates/themes/your-theme/
├── readme.tmpl           # Main template
├── partials/            # Optional partial templates
│   ├── header.tmpl
│   ├── inputs.tmpl
│   └── examples.tmpl
└── assets/              # Optional theme assets
    ├── styles.css
    └── logo.png

🔐 GitHub Token Configuration

Creating a Token

1. Go to GitHub Settings → Developer settings → Personal access tokens
2. Generate new token with public_repo scope
3. Copy token and save securely

Setting Token

# Environment variable (recommended)
export GITHUB_TOKEN=your_token_here

# Configuration file
gh-action-readme config set github_token your_token_here

# Command line (least secure)
gh-action-readme gen --github-token your_token_here

Token Benefits

• Higher rate limits (5000 requests/hour vs 60)
• Dependency analysis with detailed metadata
• Private repository access
• Enhanced error messages for API issues

📊 Cache Configuration

Cache Settings

# Cache configuration
cache_enabled: true
cache_dir: ~/.cache/gh-action-readme
cache_ttl: 3600  # 1 hour in seconds
cache_max_size: 100  # MB

Cache Management

# Clear cache
gh-action-readme config clear-cache

# Check cache status
gh-action-readme config cache-status

# Set cache TTL
gh-action-readme config set cache_ttl 7200  # 2 hours

🔧 Advanced Configuration

Custom Output Templates

# Custom output naming patterns
output_patterns:
  md: "${name}-README.md"
  html: "docs/${name}.html"
  json: "api/${name}-metadata.json"

Validation Rules

# Custom validation settings
validation:
  require_description: true
  require_examples: false
  max_input_count: 50
  enforce_semver: true

Template Variables

# Custom template variables
template_vars:
  organization: "my-org"
  support_email: "support@example.com"
  docs_url: "https://docs.example.com"

📝 Configuration Commands

View Configuration

# Show current config
gh-action-readme config show

# Show specific setting
gh-action-readme config get theme

Update Configuration

# Set individual values
gh-action-readme config set theme professional
gh-action-readme config set verbose true

# Reset to defaults
gh-action-readme config reset

# Remove config file
gh-action-readme config delete

Export/Import Configuration

# Export current config
gh-action-readme config export --format json > config.json

# Import configuration
gh-action-readme config import config.json

# Merge configurations
gh-action-readme config merge other-config.yaml

🔍 Debugging Configuration

Verbose Mode

# Enable verbose output
gh-action-readme gen --verbose

# Set in config
gh-action-readme config set verbose true

Configuration Validation

# Validate current configuration
gh-action-readme config validate

# Test configuration with dry run
gh-action-readme gen --dry-run --verbose

Troubleshooting

# Show effective configuration (merged from all sources)
gh-action-readme config effective

# Show configuration file locations
gh-action-readme config paths

# Reset corrupted configuration
rm ~/.config/gh-action-readme/config.yaml
gh-action-readme config init