Timeline diagram

About timelines

A timeline diagram arranges events along a shared time axis so that chronological relationships are immediately visible. Project managers use them to show sprint schedules and milestones; historians use them to place discoveries in context; journalists use them to reconstruct event sequences; clinical researchers use them to map treatment courses. The visual form has no single governing standard, but the conventions are universal: time runs left to right, events are marked at their dates, and spans show duration.

Schematex renders timelines in three visual styles — swimlane (events spread above and below an axis), gantt (horizontal duration bars, useful for project scheduling), and lollipop (dot-on-stick markers, useful for historical retrospectives). All three share the same DSL; the style config key switches between them.

1. Your first timeline

The smallest useful timeline: a title, two ordinary events, and a milestone.

Four rules cover 80% of usage:

1. Start with the keyword timeline, optionally followed by a quoted title.
2. Each event is DATE: "Label" — a date, a colon, then a quoted label. A milestone keyword before the label marks the event as a milestone.
3. Date ranges use DATE - DATE: or DATE .. DATE: (both are equivalent).
4. Add [key: value] properties after the quoted label to set color, side placement, shape, or category.

Comments must start with # or // on their own line.

2. Events

An event line places a labeled marker at a point in time (or a bar across a span).

2.1 Point events

2024-09-15: "Conference keynote"

2.2 Range events

2024-06-01 - 2024-08-31: "Q3 development sprint"
2024-06-01 .. 2024-08-31: "Q3 development sprint"

Both separators (- surrounded by spaces, or ..) are equivalent.

2.3 Milestones

2024-09-01: milestone "Public launch"

The milestone keyword before the quoted label switches the marker to a diamond shape.

2.4 Event properties

Properties go in [key: value, …] after the quoted label, before the newline.

2024-09-01: milestone "Launch day" [color: #E53935, side: above]
2024-07-15: "Beta ships" [icon: 🚀, category: "product"]

3. Date formats

All date formats can appear anywhere a date is expected — in events, eras, and ranges.

4. Eras (background spans)

An era line draws a shaded background band across the time axis. It always requires a date range.

era 2020 - 2022: "Foundation Phase"
era 2022 .. 2025: "Growth Phase" [color: #E8F5E9]

The [color: …] property is optional. Overlapping eras stack into separate bands automatically.

5. Tracks (swimlane grouping)

A track block groups related events into a named swimlane. Indented event lines (2 spaces) belong to the track.

track "Engineering":
  2024-01-15 - 2024-03-31: "API design"
  2024-04-01 - 2024-07-31: "Implementation"

track "Marketing":
  2024-06-01: "Campaign kick-off"
  2024-09-01: milestone "Launch campaign" [color: #1B5E20]

Tracks are most useful in gantt style, where each track becomes its own labeled row.

6. Notes

A note: line indented under an event attaches a tooltip annotation to it.

2024-06-01: "Beta launch"
  note: "First external users; NPS target 40+"

Notes work both for flat events and for events inside tracks.

7. Configuration

config: lines tune the layout and visual style. Each is its own line in the form config: key = value.

Style notes:

• swimlane — events alternate above and below a horizontal axis; side: controls per-event placement. Eras add colored background bands. Best for roadmaps and biographies.
• gantt — each named track becomes a horizontal bar lane; milestones become pins above the bars. gantt-project is an alias. Best for project scheduling.
• lollipop — a center axis with labeled cards on alternating stems. Best for historical retrospectives with sparse, memorable events.

Swimlane — roadmaps, product timelines, biographies. Eras add color bands; events alternate above and below.

Gantt — parallel tracks with horizontal duration bars and milestone pins. Best for project scheduling.

Lollipop — sparse milestones on a centered axis with alternating cards. Best for historical retrospectives and brand stories.

8. Labels & comments

• Title: timeline "My Title" — first line only.
• Event label: quoted string after the colon: DATE: "Label".
• Milestone label: DATE: milestone "Label".
• Era label: era DATE - DATE: "Label".
• Track name: track "Name":.
• Note: note: "text" indented under an event.
• Comments: # or // at the start of a line (after leading whitespace).

9. Reserved words & escaping

Reserved at line start: timeline (header), config:, era, track, note:.

Date range separators: - (space-hyphen-space) and .. — avoid these sequences inside label text that appears before the colon.

BC years as negative integers: -753 is the year 753 BC. The parser distinguishes the negative sign from a range separator by checking for surrounding whitespace — - (with spaces) is a range; -753 (no leading space after a colon) is a BC year.

Property blocks: [key: value] must appear after the quoted label on the same line. The closing ] must be present; unclosed brackets produce a parse error.

10. Common mistakes

11. Grammar (EBNF)

document     = header ( blank | comment | config | era | track | event )*

header       = "timeline" ( WS quoted-string )? NEWLINE
quoted-string = '"' any-char-but-quote* '"'

config       = "config:" WS key WS "=" WS value NEWLINE
key          = "style" | "orientation" | "scale" | "axis"

era          = "era" WS date-range ":" WS quoted-string ( WS props )? NEWLINE
track        = "track" WS quoted-string ":" NEWLINE
                 ( INDENT≥2 event | INDENT≥2 note )*

event        = date-spec ":" WS event-body ( WS props )? NEWLINE
               ( INDENT note )?
event-body   = ( "milestone" WS )? quoted-string
date-spec    = date ( ( " - " | ".." ) date )?

note         = "note:" WS quoted-string NEWLINE

props        = "[" prop-list "]"
prop-list    = prop ( "," prop )*
prop         = key ":" WS value
             | key ":" WS quoted-string

date         = iso-date | year-month | year | quarter | bc-year | geological
iso-date     = digit{4} "-" digit{2} "-" digit{2}
year-month   = digit{4} "-" digit{2}
year         = "-"? digit{1,5}
quarter      = digit{4} "-"? "Q" [1-4]
bc-year      = digit+ ( "BC" | "BCE" )
geological   = number ( "Ma" | "Ga" | "ka" )

comment      = ( "#" | "//" ) any NEWLINE

Authoritative source: src/diagrams/timeline/parser.ts. If this diverges from the parser, the parser wins — please open an issue.

12. Standard compliance

Timeline diagrams have no single governing standard. Schematex follows established visualization conventions:

• Swimlane style — adapted from the horizontal timeline convention used in academic historiography and project management (PMI PMBOK).
• Gantt style — follows the Gantt chart form introduced by Henry Gantt (1910–1915); bar-per-track layout matches the ISO 21500 project scheduling convention.
• Lollipop style — follows the dot plot / stem plot convention common in data journalism and infographics.

What is implemented today:

• ✅ Three visual styles: swimlane, gantt, lollipop
• ✅ Horizontal and vertical orientation
• ✅ Three scale modes: proportional, equidistant, log
• ✅ Point events, range events (bars), and milestone markers
• ✅ Eras (background shading bands)
• ✅ Named tracks (swimlane rows)
• ✅ Event notes
• ✅ Six date formats: full date, year-month, year, quarter, BC year, geological (Ma/Ga/ka)
• ✅ Event properties: color, side, icon, shape, category
• ⏳ Vertical orientation rendering (parsed, layout not yet implemented)
• ⏳ log scale rendering (parsed, layout treats as proportional today)
• ⏳ Axis tick labels with custom format strings
• ⏳ Event connectors (arrows between related events)

References:

• Gantt, H.L. (1910). Work, Wages, and Profits. Engineering Magazine.
• Tufte, E.R. (1983). The Visual Display of Quantitative Information. — Timeline as small multiples.

13. Roadmap

Planned — not yet parseable. Do not use these in generated DSL today; the parser will reject or ignore them.

• Event connectors — connect ev1 -> ev2 [label: "causes"] arrows linking two events across time.
• Repeat / recurrence — every 2024-Q1 .. 2024-Q4 monthly: "Sprint review" for regular events.
• Axis tick format — config: tickFormat = "%b %Y" for custom date display on the axis.
• Vertical orientation — config: orientation = vertical with events left/right of a vertical axis (parsed; rendering deferred).
• Log scale — config: scale = log for geological or deep-history spans that need compressed recent years (parsed; layout deferred).

Track in the GitHub issues if you need any of these sooner.