# Timeline Builder

Generate beautiful interactive timeline HTML pages from JSON data, with vertical...

- Repository: https://github.com/zebbern/claude-code-guide (4691 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add zebbern/claude-code-guide --skill timeline-builder -g -a claude-code -y`
Codex: `npx skills add zebbern/claude-code-guide --skill timeline-builder -g -a codex -y`
Cursor: `npx skills add zebbern/claude-code-guide --skill timeline-builder -g -a cursor -y`
Gemini CLI: `npx skills add zebbern/claude-code-guide --skill timeline-builder -g -a gemini-cli -y`

## Description

Generate beautiful interactive timeline HTML pages from JSON data, with vertical, horizontal, or dual-side layouts, collapsible details, and custom colors. Ideal for project milestones, company histories, or resumes. Triggered when a user mentions 'timeline', 'history of events', 'project milestones', 'release log', or asks to visualize a chronological sequence of data.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Timeline Builder

Generate beautiful interactive timeline HTML pages from JSON configuration data, with three layout modes:

1. **Vertical layout (`vertical`)**, A classic top-to-bottom timeline with event cards alternating on either side of the axis
2. **Horizontal layout (`horizontal`)**, A horizontally scrollable timeline, best for displaying fewer events
3. **Dual-side layout (`dual-side`)**, Events are placed on the left or right based on the `side` field, great for side-by-side comparisons

All layouts support:
- Click to expand/collapse event details
- Mobile-friendly responsive design
- Custom theme colors, icons, and category labels
- Pure static HTML with zero dependencies, opens directly in any browser

## Usage

### Basic: Generate from a JSON config file

```bash
python3 scripts/generate_timeline.py --config timeline_data.json --output timeline.html
```

### Read JSON from stdin

```bash
cat timeline_data.json | python3 scripts/generate_timeline.py --stdin --output timeline.html
```

### Override layout mode (takes precedence over config file)

```bash
python3 scripts/generate_timeline.py --config data.json --layout horizontal --output timeline.html
```

### JSON Configuration Format

```json
{
  "title": "Project Milestones",
  "layout": "vertical",
  "theme": {
    "primaryColor": "#2563eb",
    "secondaryColor": "#7c3aed",
    "backgroundColor": "#ffffff",
    "textColor": "#1f2937",
    "lineColor": "#d1d5db",
    "fontFamily": "system-ui, -apple-system, sans-serif"
  },
  "events": [
    {
      "date": "2024-01-15",
      "title": "Project Kickoff",
      "summary": "Approval completed, core team assembled",
      "details": "Detailed description text, shown when the card is expanded...",
      "icon": "🚀",
      "category": "Milestone",
      "color": "#10b981",
      "side": "left"
    }
  ]
}
```

### CLI Arguments

The rest: https://github.com/zebbern/claude-code-guide/blob/HEAD/skills/timeline-builder/SKILL.md