How do I put a colon inside Mermaid timeline text?

In the test, a colon with no space after it, as in 09:30, stayed whole in event text. For a colon followed by a space, or any colon in a period, write #colon; instead. A plain colon followed by a space split the event in two, and a plain colon in a period was a parse error.

Can a Mermaid timeline run top to bottom?

On Mermaid 11.17.2, timeline TD stacked the periods one above another with their events to the right. On 10.9.8 the same line drew TD as an extra period, so check your version. timeline BT also drew BT as a period on 11.17.2.

How do I make every period in a timeline the same color?

Add a front matter config block above the timeline line that sets disableMulticolor to true under timeline. In the test, all six boxes then carried one color class. Without it, three periods carried three classes.

Mermaid timeline in Markdown: syntax and examples

Bobby Huang · 2026-11-01

A Mermaid timeline in Markdown is a fenced code block marked mermaid whose first diagram line is the word timeline. Each following line names a time period, then a colon and a space, then an event, as in 2024 : Plan drafted. Periods and events are plain text, so Q1 or Kickoff week work as well as a year. Add more colon-separated events to a line, or put them on their own lines starting with a colon. Group periods with section lines, add a title line, and set direction with timeline TD or timeline LR. In a test on Mermaid 11.17.2, a colon followed by a space split event text into two events, and a raw colon in a period failed to parse; #colon; drew a colon in both places.

Key takeaways

The word timeline, then lines of period : event, is enough for a diagram. Periods can be text such as Kickoff week as well as years.
A colon followed by a space starts a new event. 09:30 stayed whole in event text, while Note: lunch moved became two events.
A raw colon in a period failed to parse, with or without double quotes. Writing 09#colon;30 drew 09:30.
timeline TD stacked the periods vertically on 11.17.2. On 10.9.8, TD was drawn as a period with no error, and on 11.17.2 timeline BT did the same.
With the disableMulticolor setting on, all three periods and their events in the test shared one color class, against three classes without it.

This post tests the Mermaid timeline syntax you put in a Markdown fence: periods, events, sections, direction, color, and the places where a colon causes trouble. Most of it worked as Mermaid's timeline docs describe. Two results were worth more than the rest: a colon in the wrong spot changes the diagram or stops it, and a direction word Mermaid doesn't know gets drawn as a box with no error.

Every result below came from npx -y @mermaid-js/mermaid-cli@11, which reported version 11.17.1. An info diagram run through it printed v11.17.2, so that's the Mermaid version tested, on one Mac, with one older version as a comparison under Direction. Other viewers weren't tested, and their Mermaid version can differ. The output was checked by counting text in each SVG with grep, plus a look at three PNG renders. For fences in general, previews, and other diagram types, see Mermaid diagrams in Markdown.

The smallest timeline that drew

The first test file, minimal.mmd:

timeline
    2024 : Jane Doe drafts the plan
    2025 : Doe Holdings starts work
    2026 : Review closes

The command:

npx -y @mermaid-js/mermaid-cli@11 -i minimal.mmd -o minimal.svg

It exited 0. Each period's box sits in an SVG group with the class taskWrapper, and each event's in eventWrapper. Run on the SVG, grep -o piped to wc -l counted 3 of each, one pair for each source line.

Several events on one period

Events can share a period's line or start their own line with a colon. This file, multi.mmd, does both and adds a title:

timeline
    title Plan history
    Q1 : Draft written : Draft reviewed
    Q2 : Build starts
       : Tests added
       : Docs added

The counts were 2 periods and 5 events. Q1's two events and Q2's three all landed under their own period, based on the x position of each group in the SVG. Plan history appeared in the output as the title text.

Periods can be words

Periods aren't limited to numbers. This file drew 3 periods and 3 events:

timeline
    Before kickoff : Collect notes
    Kickoff week : Name the owner
    After launch : Write the review

One thing to know when you search the output: in the SVG text, words were separated by three spaces, as in Before kickoff. A grep for the phrase with one space won't find it.

Sections and a title

A section line groups the periods under it:

timeline
    title Doe Holdings rollout
    section Planning
        January : Scope agreed
        February : Budget set
    section Delivery
        March : Pilot starts
        April : Pilot ends

The counts were 4 periods and 4 events. Color follows the section here, not the period. A grep for timeline-node section--1 counted 5 and timeline-node section-0 counted 5: one section label, two periods and two events each. The PNG render showed Planning's boxes in one hue and Delivery's in another.

Without sections, each period got its own class. In the minimal.mmd output, three periods carried section--1, section-0 and section-1, each counted twice: the period and its event.

A colon inside the text

Colons are the separator, so they're where these files went wrong. Each row below is one test.

Source line	Exit	What the SVG held
`Morning : Standup at 09:30`	0	One event, with `09:30` intact
`Noon : Note: lunch moved`	0	Two events: `Note` and `lunch moved`
`Noon : Note#colon; lunch moved`	0	One event, with `Note:` in it
`Noon : Note#58; lunch moved`	0	One event, with `Note:` in it
`09:30 : Standup`	1	No SVG, parse error
`"09:30" : Standup`	1	No SVG, parse error
`09#colon;30 : Standup`	0	One period, drawn as `09:30`
`2024 :First event`	1	No SVG, parse error
`2024: First event`	0	Same bytes as the `2024 : First event` file

The second row is the quiet one. It exited 0 and the diagram looks fine, but the event count was 3 for the file where the author meant 2. The file with #colon; counted 2. In this run, what mattered after a colon was the space: a colon followed by a space started an event, and a colon followed by anything else in a period line failed. Quotes around the period didn't help.

A related check, on strikethrough: 2024 : ~~Old plan~~ New plan kept both pairs of tildes as literal text in the SVG, with 0 matches for <del and 0 for line-through.

Direction: TD and LR

Here is the test for TD. The LR file differs only in its first line.

timeline TD
    2024 : First event
    2025 : Second event

All of these ran on 11.17.2 unless the row says otherwise.

First line	Periods counted	Layout or result
`timeline`	2	Periods side by side, events below them
`timeline LR`	2	Same bytes as plain `timeline`
`timeline TD`	2	Periods stacked, events to the right
`timeline td`	2	Same bytes as `timeline TD`
`timeline BT`	3	`BT` drawn as a period
`timeline TD` on 10.9.8	3	`TD` drawn as a period

Both of the 3-period rows matched >BT< or >TD< once in the SVG, and neither printed an error. That's the failure to look for on an older viewer: an extra box at the start of the timeline, labeled with the direction word. Plain timeline TD on 11.17.2 counted 0 for >TD<.

The older result came from mermaid-cli 10.9.1, whose info diagram printed v10.9.8. Versions between 10.9.8 and 11.17.2 weren't narrowed down. Trying mermaid-cli 11.12.0 didn't help with that, because its info diagram also printed v11.17.2, so an older CLI doesn't always mean an older Mermaid. Run info to see the Mermaid version you actually got.

One color with disableMulticolor

The setting goes in a front matter block above the diagram:

---
config:
  timeline:
    disableMulticolor: true
---
timeline
    2024 : First event
    2025 : Second event
    2026 : Third event

All 6 boxes carried section--1. The same three lines without the block carried section--1, section-0 and section-1, twice each. The PNG showed one color across all three periods, with the event boxes in a lighter shade of it. This test used front matter only, not the older %%{init} directive form.

What a broken timeline prints

A misspelled type line, timelin, exited 1 and wrote no SVG:

UnknownDiagramError: No diagram type detected matching given configuration for text: timelin
    2024 : First event

The colon failures from the table printed a parse error that points at the character:

Error: Parse error on line 2:
timeline    09:30 : Standup    12
--------------^
Expecting 'EOF', 'SPACE', 'NEWLINE', 'title', 'acc_title', 'acc_descr', 'acc_descr_multiline_value', 'section', 'period', 'event', got 'INVALID'

A bare section line with no name, followed by a period, also exited 1, with a less helpful message that doesn't name the line:

TypeError: Cannot read properties of undefined (reading 'events')

Inside a Markdown fence

So far the tests were .mmd files. In a Markdown file the same text goes in a fence marked mermaid:

```mermaid
timeline
    title Plan history
    2024 : Jane Doe drafts the plan
    2025 : Doe Holdings starts work
```

Given a Markdown file holding that fence with a line of prose above and below it, the tool printed Found 1 mermaid charts in Markdown input. It wrote fence-out-1.svg, with 2 periods and 2 events, and fence-out.md. In that output file the fence was replaced by ![diagram](./fence-out-1.svg), and both prose lines were still there.

Steps to check a timeline before you share it

Each step was run in this order on a file that combines the features above. The counts are from that run.

Save this as plan.mmd:

timeline TD
    title Doe Holdings rollout
    section Planning
        Q1 : Scope agreed : Budget set
        Q2 : Owner named
    section Delivery
        Q3 : Pilot starts
           : Pilot ends
        Q4 : Review at 16#colon;00

Render it with npx -y @mermaid-js/mermaid-cli@11 -i plan.mmd -o plan.svg. It exited 0. In these tests, exit 1 came with an error message and no SVG, so read the message.
Count periods with grep -o 'class="taskWrapper"' plan.svg | wc -l. It gave 4, one for each period line in the file.
Count events with grep -o 'class="eventWrapper"' plan.svg | wc -l. It gave 6. A higher count than you wrote points to a colon that split an event.
Check that the direction word wasn't drawn: grep -o '>TD<' plan.svg | wc -l gave 0.
Check text with a colon, using three spaces between words: grep -o '>Review at 16:00<' plan.svg | wc -l gave 1.
Put the same text in a mermaid fence in plan.md, then run npx -y @mermaid-js/mermaid-cli@11 -i plan.md -o plan-out.md. It wrote plan-out-1.svg and a plan-out.md that links to it.

Where Sashmark fits

Sashmark is a Markdown reader and editor for people whose AI agents write Markdown. It is in development; nothing has been released. There are no AI features in the app.

Questions

How do I put a colon inside Mermaid timeline text?: In the test, a colon with no space after it, as in 09:30, stayed whole in event text. For a colon followed by a space, or any colon in a period, write #colon; instead. A plain colon followed by a space split the event in two, and a plain colon in a period was a parse error.
Can a Mermaid timeline run top to bottom?: On Mermaid 11.17.2, timeline TD stacked the periods one above another with their events to the right. On 10.9.8 the same line drew TD as an extra period, so check your version. timeline BT also drew BT as a period on 11.17.2.
How do I make every period in a timeline the same color?: Add a front matter config block above the timeline line that sets disableMulticolor to true under timeline. In the test, all six boxes then carried one color class. Without it, three periods carried three classes.