Timeline Visualization Guide

Reference for transforming date-ranged data into Mermaid Gantt charts.

Input Data Format

Timeline data should be a JSON array of records:

[
  {
    "label": "Project Alpha",
    "startDate": "2024-01-15",
    "endDate": "2024-03-20",
    "category": "Development"
  },
  {
    "label": "Project Beta",
    "startDate": "2024-02-01",
    "endDate": "2024-04-15",
    "category": "Development"
  }
]

Required fields:

• label - Display name for the item
• startDate - ISO date (YYYY-MM-DD)
• endDate - ISO date (YYYY-MM-DD)

Optional fields:

• category - For grouping into sections
• id - Custom ID (auto-generated if not provided)

Mermaid Gantt Syntax

Basic structure:

gantt
    title Project Timeline
    dateFormat YYYY-MM-DD

    section Category A
        Task 1    :id1, 2024-01-01, 2024-01-15
        Task 2    :id2, 2024-01-10, 2024-01-25

    section Category B
        Task 3    :id3, 2024-01-20, 2024-02-05

Syntax rules:

• dateFormat YYYY-MM-DD is required
• Each task: Label :id, start_date, end_date
• IDs must be unique - no spaces allowed
• Sections group related items
• Indentation is 4 spaces

ID Generation

Create unique IDs without spaces:

Label	Category	Year	Generated ID
USA	Travel	2024	usa24a
France	Travel	2024	fr24
USA	Travel	2024	usa24b
Project Alpha	Dev	2024	alpha24

Pattern: {shortLabel}{year}{letter}

• Lowercase, no spaces
• Add letter suffix for duplicates in same year

Grouping Strategies

By year (history/retrospective):

section 2024
    ...items from 2024...
section 2023
    ...items from 2023...

Order: most recent first

By category (parallel streams):

section Development
    ...dev items...
section Marketing
    ...marketing items...

Order: logical grouping

By phase (sequential project):

section Planning
    ...planning items...
section Execution
    ...execution items...

Order: chronological phases

Handling Edge Cases

Overlapping ranges:

• Mermaid handles overlaps automatically
• Items render on separate rows within a section
• No special handling needed

Single-day items:

• Use same date for start and end
• Renders as a thin bar

Gaps in data:

• Don't fill gaps artificially
• Let the chart show actual coverage
• Note significant gaps in summary

Long timelines (3+ years):

• Group by year to avoid clutter
• Consider showing only highlights
• Warn if >50 items (chart may be crowded)

Travel-Specific Patterns

For travel timelines, aggregate to country level:

Input (flights):

[
  {"from": "SFO", "to": "CDG", "date": "2024-01-15"},
  {"from": "CDG", "to": "FRA", "date": "2024-01-22"},
  {"from": "FRA", "to": "SFO", "date": "2024-01-25"}
]

Output (country spans):

section 2024
    USA       :usa24a, 2024-01-01, 2024-01-15
    France    :fr24, 2024-01-15, 2024-01-22
    Germany   :de24, 2024-01-22, 2024-01-25
    USA       :usa24b, 2024-01-25, 2024-12-31

Logic: After arriving, user stays in that country until next departure.

Output

The rendered chart is an SVG image. Embed in markdown:

![Timeline](https://your-hosted-url/timeline.svg)

SVGs scale cleanly at any size and support both light and dark backgrounds.