gh-action-readme/docs/themes.md

Themes

gh-action-readme includes 5 built-in themes, each optimized for different use cases and visual preferences.

🎨 Available Themes

GitHub Theme

Best for: GitHub Marketplace actions, open source projects

gh-action-readme gen --theme github

Features:

• GitHub-style badges and shields
• Collapsible sections for better organization
• Table-based parameter documentation
• Action marketplace optimization
• GitHub-specific styling and layout

Example output:

• ✅ Professional badges
• 📊 Clean input/output tables
• 🔧 Copy-paste usage examples
• 📁 Collapsible troubleshooting sections

GitLab Theme

Best for: GitLab CI/CD integration, GitLab-hosted projects

gh-action-readme gen --theme gitlab

Features:

• GitLab CI/CD pipeline examples
• GitLab-specific badge integration
• Pipeline configuration snippets
• GitLab Pages optimization

Minimal Theme

Best for: Simple actions, lightweight documentation

gh-action-readme gen --theme minimal

Features:

• Clean, distraction-free layout
• Essential information only
• Faster loading and parsing
• Mobile-friendly design
• Minimal dependencies

Professional Theme

Best for: Enterprise actions, comprehensive documentation

gh-action-readme gen --theme professional

Features:

• Comprehensive table of contents
• Detailed troubleshooting sections
• Advanced usage examples
• Security and compliance notes
• Enterprise-ready formatting

Default Theme

Best for: Basic needs, backward compatibility

gh-action-readme gen --theme default

Features:

• Original simple template
• Basic parameter documentation
• Minimal formatting
• Guaranteed compatibility

🎯 Theme Comparison

Feature	GitHub	GitLab	Minimal	Professional	Default
Badges	✅ Rich	✅ GitLab	❌ None	✅ Comprehensive	❌ None
TOC	✅ Yes	✅ Yes	❌ No	✅ Advanced	❌ No
Examples	✅ GitHub	✅ CI/CD	✅ Basic	✅ Comprehensive	✅ Basic
Troubleshooting	✅ Collapsible	✅ Pipeline	❌ Minimal	✅ Detailed	❌ None
File Size	Medium	Medium	Small	Large	Small
Load Time	Fast	Fast	Fastest	Slower	Fast

🛠️ Theme Examples

Input Action

name: Deploy to AWS
description: Deploy application to AWS using GitHub Actions
inputs:
  aws-region:
    description: AWS region to deploy to
    required: true
    default: us-east-1
  environment:
    description: Deployment environment
    required: false
    default: production
outputs:
  deployment-url:
    description: URL of the deployed application
runs:
  using: composite
  steps:
    - run: echo "Deploying to AWS..."

GitHub Theme Output

# Deploy to AWS

[![GitHub Action](https://img.shields.io/badge/GitHub%20Action-Deploy%20to%20AWS-blue)](https://github.com/marketplace)

> Deploy application to AWS using GitHub Actions

## 🚀 Usage

```yaml
- uses: your-org/deploy-aws@v1
  with:
    aws-region: us-west-2
    environment: staging

📋 Inputs

Input	Description	Required	Default
aws-region	AWS region to deploy to	Yes	us-east-1
environment	Deployment environment	No	production

```

Minimal Theme Output

# Deploy to AWS

Deploy application to AWS using GitHub Actions

## Usage

```yaml
- uses: your-org/deploy-aws@v1
  with:
    aws-region: us-west-2

Inputs

• aws-region (required): AWS region to deploy to
• environment (optional): Deployment environment (default: production)

Outputs

• deployment-url: URL of the deployed application

## 🎨 Custom Themes

### Creating Custom Themes

1. **Copy existing theme:**
```bash
cp -r templates/themes/github templates/themes/my-theme

1. Edit template files:

# Main template
vim templates/themes/my-theme/readme.tmpl

# Optional partials
vim templates/themes/my-theme/partials/header.tmpl

1. Use custom theme:

gh-action-readme gen --theme my-theme

Theme Structure

templates/themes/my-theme/
├── readme.tmpl           # Main template (required)
├── partials/            # Partial templates (optional)
│   ├── header.tmpl      # Header section
│   ├── inputs.tmpl      # Inputs table
│   ├── outputs.tmpl     # Outputs table
│   ├── examples.tmpl    # Usage examples
│   └── footer.tmpl      # Footer section
└── assets/              # Theme assets (optional)
    ├── styles.css       # Custom CSS
    └── images/          # Theme images

Template Variables

Available variables in templates:

type ActionData struct {
    Name          string                  // Action name
    Description   string                  // Action description
    Inputs        map[string]ActionInput  // Input parameters
    Outputs       map[string]ActionOutput // Output parameters
    Runs          map[string]interface{}  // Runs configuration
    Branding      *Branding              // Branding info

    // Enhanced data
    Repository    *Repository            // GitHub repo info
    Dependencies  []Dependency           // Analyzed dependencies
    Examples      []Example              // Usage examples
}

Template Functions

Built-in template functions:

// String functions
{{ .Name | title }}              // Title case
{{ .Description | truncate 100 }} // Truncate to 100 chars
{{ .Name | slug }}               // URL-friendly slug

// Formatting functions
{{ .Inputs | toTable }}          // Generate input table
{{ .Dependencies | toList }}      // Generate dependency list
{{ .Examples | toYAML }}         // Format as YAML

// Conditional functions
{{ if hasInputs }}...{{ end }}   // Check if inputs exist
{{ if .Branding }}...{{ end }}   // Check if branding exists

Advanced Template Example

{{/* Custom theme header */}}
# {{ .Name }}

{{ if .Branding }}
<p align="center">
  <img src="{{ .Branding.Icon }}" alt="{{ .Name }}" width="64">
</p>
{{ end }}

> {{ .Description }}

## 🚀 Quick Start

```yaml
- uses: {{ .Repository.FullName }}@{{ .Repository.DefaultBranch }}
  with:
    {{- range $key, $input := .Inputs }}
    {{- if $input.Required }}
    {{ $key }}: # {{ $input.Description }}
    {{- end }}
    {{- end }}

{{ if .Inputs }}

📋 Configuration

{{ template "inputs-table" . }} {{ end }}

{{ if .Dependencies }}

🔗 Dependencies

This action uses the following dependencies: {{ range .Dependencies }}

• [{{ .Name }}]({{ .SourceURL }}) - {{ .Description }} {{ end }} {{ end }}

{{/Include footer partial if it exists/}} {{ template "footer" . }}

## 🔧 Theme Configuration

### Set Default Theme
```bash
# Set globally
gh-action-readme config set theme professional

# Use environment variable
export GH_ACTION_README_THEME=github

Theme-Specific Settings

# ~/.config/gh-action-readme/config.yaml
theme: github
theme_settings:
  github:
    show_badges: true
    collapse_sections: true
    show_toc: true
  minimal:
    show_examples: true
    compact_tables: true
  professional:
    detailed_examples: true
    show_troubleshooting: true

Dynamic Theme Selection

# Select theme based on repository type
if [[ -f ".gitlab-ci.yml" ]]; then
  gh-action-readme gen --theme gitlab
elif [[ -f "package.json" ]]; then
  gh-action-readme gen --theme github
else
  gh-action-readme gen --theme minimal
fi

📱 Responsive Design

All themes support responsive design:

• Desktop: Full-width tables and detailed sections
• Tablet: Condensed tables with horizontal scrolling
• Mobile: Stacked layouts and collapsible sections

🎨 Theme Customization Tips

Colors and Styling

/* Custom CSS for HTML output */
.action-header { color: #0366d6; }
.input-table { border-collapse: collapse; }
.example-code { background: #f6f8fa; }

Badge Customization

{{/* Custom badges */}}
![Version](https://img.shields.io/badge/version-{{ .Version }}-blue)
![License](https://img.shields.io/badge/license-{{ .License }}-green)
![Downloads](https://img.shields.io/github/downloads/{{ .Repository.FullName }}/total)

Conditional Content

{{/* Show different content based on action type */}}
{{ if eq .Runs.Using "composite" }}
## Composite Action Steps
{{ range .Runs.Steps }}
- {{ .Name }}: {{ .Run }}
{{ end }}
{{ else if eq .Runs.Using "docker" }}
## Docker Configuration
- Image: `{{ .Runs.Image }}`
- Args: `{{ join .Runs.Args " " }}`
{{ end }}