Explore Vithanco's Rich Library of Notations Timeline Notation

Timeline Notation

Estimated reading time: 4 minutes.

Why use Timelines?

Timelines allow you to visualize events across multiple tracks (e.g., countries, teams, departments) aligned to a shared time axis. They are useful for understanding how events in different domains relate to each other chronologically and causally.

Common use cases include:

Historical analysis across multiple countries or regions
Project management with parallel workstreams
Product roadmaps with multiple feature tracks
Incident timelines showing events across different systems

Timeline Notation Description

The Timeline notation uses a left-to-right layout where time flows horizontally. Events are aligned vertically using the alignGroup attribute, which ensures that events happening at the same time appear at the same horizontal position.

Node Types

Node Type	Description	Is Starting Point	Successors
TimePoint	An axis marker representing a point in time (e.g., a year, date, or phase). TimePoints are optional — alignment can be achieved with `alignGroup` alone.	Yes	TimePoint
Event	A generic event that can be aligned to a time point. Extend with `vnotation` for custom event types (e.g., Battle, Treaty, Release).	No	Event

Edge Types

Edge Type	Description	From	To
sequence	Creates the time axis by connecting TimePoints in chronological order. Rendered as a thin gray line.	TimePoint	TimePoint
influence	Shows dependencies or causal relationships between events, within or across tracks. Rendered as a dashed line with `constraint=false` so it does not distort time alignment.	Event	Event

Tracks with Groups

Use groups to create parallel tracks. Each group renders as a labeled cluster box containing its events. Groups are optional — simple timelines work without them.

Try Timeline Yourself

Create and visualise your own Timeline diagram right here in your browser. Edit the VGL (Vithanco Graph Language) text on the left and click "Render" to see your diagram:

Tip: Use Ctrl+Enter (or Cmd+Enter on Mac) to quickly render your graph while editing.

Want to learn more about the VGL syntax? Check out the complete VGL Guide for detailed documentation on creating graphs in text format, including syntax reference and examples for all supported notations.

Example

This example models 19th century European events across two country tracks:

A Timeline showing 19th Century European events

vgraph myTimeline: Timeline "19th Century Europe" {
    node t1800: TimePoint "1800" [alignGroup: "1800"]
    node t1850: TimePoint "1850" [alignGroup: "1850"]
    node t1871: TimePoint "1871" [alignGroup: "1871"]
    edge t1800 -> t1850: sequence
    edge t1850 -> t1871: sequence

    group germany "Germany" {
        node g1: Event "Napoleon defeats Prussia" [alignGroup: "1800"]
        node g2: Event "German Unification" [alignGroup: "1871"]
    }
    group england "England" {
        node e1: Event "Industrial Revolution peaks" [alignGroup: "1850"]
        node e2: Event "Franco-Prussian War impact" [alignGroup: "1871"]
    }

    edge g1 -> g2: influence "led to"
    edge e1 -> e2: influence
    edge e1 -> g2: influence "industrialization enabled"
}

Changing Layout Direction

The default Timeline layout is left-to-right, with time flowing horizontally. You can switch to a top-to-bottom layout using the layout directive in a vnotation block. In top-to-bottom mode, time flows vertically downward, and alignGroup aligns nodes at the same vertical position instead.

vnotation VerticalTimeline extends Timeline {
    layout: topToBottom
}

All four layout directions are supported: topToBottom, bottomToTop, leftToRight, rightToLeft.

Extending with vnotation

The base Timeline notation provides generic TimePoint and Event types. Use vnotation extends Timeline to define domain-specific event types with custom colors, icons, and categories. You can also change the layout direction in the same vnotation block.

Here is an example that defines a WarTimeline with Battle and Treaty event types, custom edge types (resolved_by and influenced), and a top-to-bottom layout:

vnotation WarTimeline extends Timeline {
    layout: topToBottom
    node type: Battle [nodeStyle: withCategory, color: "#883333", category: "Battle"]
    node type: Treaty [nodeStyle: withCategory, color: "#339933", category: "Treaty"]
    edge type: resolved_by from: Battle to: Treaty
    edge type: influenced from: Battle to: Battle
}
vgraph napoleonicWars: WarTimeline "Napoleonic Wars" {
    node t1805: TimePoint "1805" [alignGroup: "1805"]
    node t1812: TimePoint "1812" [alignGroup: "1812"]
    node t1815: TimePoint "1815" [alignGroup: "1815"]
    edge t1805 -> t1812: sequence
    edge t1812 -> t1815: sequence
        node f1: Battle "Battle of Austerlitz" [alignGroup: "1805"]
        node f2: Battle "Invasion of Russia" [alignGroup: "1812"]
        node f3: Battle "Battle of Waterloo" [alignGroup: "1815"]
        node e1: Treaty "Treaty of Pressburg" [alignGroup: "1805"]
        node e2: Treaty "Congress of Vienna" [alignGroup: "1815"]
    edge f1 -> e1: resolved_by
    edge f3 -> e2: resolved_by
    edge f1 -> f2: influenced "overconfidence"
    edge f2 -> f3: influenced "weakened army"
}

A WarTimeline showing the Napoleonic Wars with custom Battle and Treaty types in top-to-bottom layout

The alignGroup Attribute

The alignGroup attribute is the key mechanism for time alignment. Nodes with the same alignGroup value are placed at the same rank (same horizontal position in a left-to-right layout, or same vertical position in a top-to-bottom layout). This attribute is generic and available in all notations, not just Timeline.