Timeline Builder
Generate beautiful interactive timeline HTML pages from JSON configuration data, with three layout modes:
- Vertical layout (
vertical) — A classic top-to-bottom timeline with event cards alternating on either side of the axis
- Horizontal layout (
horizontal) — A horizontally scrollable timeline, best for displaying fewer events
- 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
python3 scripts/generate_timeline.py --config timeline_data.json --output timeline.html
Read JSON from stdin
cat timeline_data.json | python3 scripts/generate_timeline.py --stdin --output timeline.html
Override layout mode (takes precedence over config file)
python3 scripts/generate_timeline.py --config data.json --layout horizontal --output timeline.html
JSON Configuration Format
{
"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
| Argument |
Description |
--config, -c |
Path to the JSON config file (mutually exclusive with --stdin) |
--stdin |
Read JSON from standard input |
--output, -o |
Output HTML file path (defaults to stdout) |
--layout, -l |
Override layout mode: vertical, horizontal, dual-side |
--title, -t |
Override the timeline title |
Event Fields
| Field |
Required |
Description |
date |
Yes |
Date label — any format works (e.g. 2024-01, Q1 2024, Phase One) |
title |
Yes |
Event title |
summary |
No |
Short description, always visible on the card |
details |
No |
Detailed content, revealed on click |
icon |
No |
Emoji or single-character icon (defaults to ●) |
category |
No |
Category tag displayed on the card |
color |
No |
Event node color (overrides the theme color) |
side |
No |
Only for dual-side layout: left or right |
Use Cases
- Project milestone displays
- Product release histories
- Company growth timelines
- Personal resume timelines
- Course syllabus outlines
- Any scenario requiring chronological information display
Dependencies
- Python 3.6+ (standard library only — no extra packages required)
1---2name: timeline-builder3description: 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.4license: MIT5---6
7# Timeline Builder
8
9Generate beautiful interactive timeline HTML pages from JSON configuration data, with three layout modes:
10
111. **Vertical layout (`vertical`)** — A classic top-to-bottom timeline with event cards alternating on either side of the axis
122. **Horizontal layout (`horizontal`)** — A horizontally scrollable timeline, best for displaying fewer events
133. **Dual-side layout (`dual-side`)** — Events are placed on the left or right based on the `side` field, great for side-by-side comparisons
14
15All layouts support:
16- Click to expand/collapse event details
17- Mobile-friendly responsive design
18- Custom theme colors, icons, and category labels
19- Pure static HTML with zero dependencies — opens directly in any browser
20
21## Usage
22
23### Basic: Generate from a JSON config file
24
25```bash
26python3 scripts/generate_timeline.py --config timeline_data.json --output timeline.html
27```
28
29### Read JSON from stdin
30
31```bash
32cat timeline_data.json | python3 scripts/generate_timeline.py --stdin --output timeline.html
33```
34
35### Override layout mode (takes precedence over config file)
36
37```bash
38python3 scripts/generate_timeline.py --config data.json --layout horizontal --output timeline.html
39```
40
41### JSON Configuration Format
42
43```json
44{
45 "title": "Project Milestones",
46 "layout": "vertical",
47 "theme": {
48 "primaryColor": "#2563eb",
49 "secondaryColor": "#7c3aed",
50 "backgroundColor": "#ffffff",
51 "textColor": "#1f2937",
52 "lineColor": "#d1d5db",
53 "fontFamily": "system-ui, -apple-system, sans-serif"
54 },
55 "events": [
56 {
57 "date": "2024-01-15",
58 "title": "Project Kickoff",
59 "summary": "Approval completed, core team assembled",
60 "details": "Detailed description text, shown when the card is expanded...",
61 "icon": "🚀",
62 "category": "Milestone",
63 "color": "#10b981",
64 "side": "left"
65 }
66 ]
67}
68```
69
70### CLI Arguments
71
72| Argument | Description |
73|----------|-------------|
74| `--config, -c` | Path to the JSON config file (mutually exclusive with `--stdin`) |
75| `--stdin` | Read JSON from standard input |
76| `--output, -o` | Output HTML file path (defaults to stdout) |
77| `--layout, -l` | Override layout mode: `vertical`, `horizontal`, `dual-side` |
78| `--title, -t` | Override the timeline title |
79
80### Event Fields
81
82| Field | Required | Description |
83|-------|----------|-------------|
84| `date` | Yes | Date label — any format works (e.g. `2024-01`, `Q1 2024`, `Phase One`) |
85| `title` | Yes | Event title |
86| `summary` | No | Short description, always visible on the card |
87| `details` | No | Detailed content, revealed on click |
88| `icon` | No | Emoji or single-character icon (defaults to `●`) |
89| `category` | No | Category tag displayed on the card |
90| `color` | No | Event node color (overrides the theme color) |
91| `side` | No | Only for dual-side layout: `left` or `right` |
92
93## Use Cases
94
95- Project milestone displays
96- Product release histories
97- Company growth timelines
98- Personal resume timelines
99- Course syllabus outlines
100- Any scenario requiring chronological information display
101
102## Dependencies
103
104- Python 3.6+ (standard library only — no extra packages required)
majiayu000