Timeline diagrams

Overview

Timeline diagrams in Sirena represent chronological events and milestones arranged along a time axis. Timelines are ideal for visualizing historical progressions, project milestones, or any sequence of events that occur over time.

Timelines are useful for:

Documenting historical events and developments
Visualizing project roadmaps and milestones
Showing product release schedules
Mapping organizational changes over time
Creating biographical or company history visualizations

Syntax specification

Diagram declaration

Timelines are declared using the timeline keyword:

timeline
    <diagram-content>

Title declaration

Optional title can be added:

timeline
    title My Timeline Title
    <events>

Event syntax

Events are defined with a time/date and one or more descriptions:

<time> : <description>

Multiple descriptions for the same time:

<time> : <description1> : <description2> : <description3>

Continuation entries (adds to previous event):

<time> : <description1>
     : <description2>

Section grouping

Events can be organized into sections:

timeline
    section <section-name>
    <events>
    section <section-name>
    <events>

Task entries

Sections can contain tasks (items without timestamps):

timeline
    section Tasks
    task1
    task2
    task3

Examples

Simple timeline

Example 1. Basic timeline with events

timeline
    title History of Social Media Platforms
    2002 : LinkedIn
    2004 : Facebook
    2005 : YouTube
    2006 : Twitter

This creates a simple horizontal timeline showing the founding years of major social media platforms.

Timeline with multiple events per year

Example 2. Multiple events at same time

timeline
    title Tech Milestones 2004
    2004 : Facebook launched : Google IPO
    2005 : YouTube founded
    2006 : Twitter created

This demonstrates how to show multiple events that occurred in the same year.

Timeline with sections

Example 3. Organized by historical periods

timeline
    title History of Flight
    section 20th Century
    1903 : Wright Brothers first flight
    1927 : Lindbergh crosses Atlantic
    1969 : Moon landing
    section 21st Century
    2004 : SpaceX founded
    2020 : Crew Dragon Demo-2

This shows how sections can organize events into logical groupings (centuries, in this case).

Timeline with continuation entries

Example 4. Using continuation syntax

timeline
    title Product Releases 2020
    Jan 2020 : Version 1.0 released
            : Mobile app launched
    Jun 2020 : Version 2.0 released
            : Desktop app launched
            : API v2 available
    Dec 2020 : Year-end update

This demonstrates the continuation syntax for adding multiple descriptions to an event.

Timeline with tasks in sections

Example 5. Project phases with tasks

timeline
    title Project Milestones
    section Planning Phase
    Requirements gathering
    Design mockups
    Architecture planning
    section Development Phase
    Backend implementation
    Frontend development
    Testing and QA
    section Deployment Phase
    Production release
    Monitoring setup
    Documentation

This shows how sections can contain tasks (non-timestamped items) for project phases.

Features

Accessibility support

Timelines support accessibility features:

timeline
    accTitle: Project Timeline
    accDescr: A timeline showing major project milestones
    2020 : Project start
    2021 : Beta release
    2022 : General availability

Special characters

Timeline content supports special characters:

timeline
    title ;Special;Characters;
    section ;Phase-1;
    ;Task-1; : ;Event-1;

Flexible time formats

Time values can be years, dates, or any text:

timeline
    2020 : Year only
    2020-01 : Year and month
    2020-01-15 : Full date
    Q1 2020 : Quarter notation
    Jan 2020 : Month notation

Best practices

Use clear time markers

Choose a consistent time format throughout your timeline:

timeline
    %% Good - consistent format
    2020 : Event A
    2021 : Event B
    2022 : Event C

    %% Less clear - mixed formats
    2020 : Event A
    Jan 2021 : Event B
    2022-03-15 : Event C

Organize with sections

For long timelines, use sections to group related periods:

timeline
    section Early Development
    1990 : Project conceived
    1995 : First prototype
    section Growth Period
    2000 : Market entry
    2005 : International expansion

Limit event descriptions

Keep descriptions concise to maintain readability:

timeline
    %% Good
    2020 : Product launched

    %% Too verbose
    2020 : Our amazing product was successfully launched to the market after years of development

Choose appropriate granularity

Match time granularity to the timeline scope:

Years for long historical timelines (decades/centuries)
Months for project timelines (6-24 months)
Days/weeks for sprint or detailed project plans

Rendering behavior

Timeline positioning

Events are positioned chronologically along a horizontal axis based on their time values. The renderer:

Extracts numeric values from time strings (e.g., "2004" → 2004)
Calculates relative positions along the timeline
Distributes events proportionally based on their time values

Section visualization

When sections are used:

Each section gets its own timeline axis
Sections are stacked vertically
Different colors distinguish sections

Task distribution

Tasks (items without timestamps) are distributed evenly along the timeline axis within their section.

Limitations

Currently not supported

The following features are not yet supported:

Custom styling for individual events
Click events or interactions
Complex date calculations
Time period ranges (start-end dates for events)

Known issues

Very long event descriptions may overflow
Non-numeric time values may not position correctly
Overlapping events at the same time may cause crowding

Testing

The timeline implementation includes comprehensive test coverage:

16/17 Mermaid fixtures passing (94.1% success rate)
The single failing fixture contains invalid syntax ("Timeline diagram" instead of "timeline")
Full support for sections, events, tasks, and styling
HTML tags in descriptions handled correctly
Special characters (semicolons, hashtags) supported

Run tests with:

bundle exec rspec spec/sirena/parser/timeline_spec.rb