--- title: "Mermaid timeline in Markdown: syntax and examples" slug: markdown-mermaid-timeline excerpt: "A Mermaid timeline opens with the word timeline, then period : event lines. Runs on Mermaid 11.17.2 cover sections, direction and colon traps." quickAnswer: "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." keyTakeaways: - "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." publishedDate: 2026-11-01 dateModified: 2026-11-01 author: Bobby Huang cluster: B role: post status: published faq: - q: How do I put a colon inside Mermaid timeline text? a: "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." - q: Can a Mermaid timeline run top to bottom? a: "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." - q: How do I make every period in a timeline the same color? a: "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." related: - markdown-mermaid-diagrams - markdown-code-blocks - rendered-vs-raw-agent-markdown --- 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](markdown-mermaid-diagrams.md). ## The smallest timeline that drew The first test file, `minimal.mmd`: ```mermaid timeline 2024 : Jane Doe drafts the plan 2025 : Doe Holdings starts work 2026 : Review closes ``` The command: ```sh 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: ```mermaid 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: ```mermaid 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: ```mermaid 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 `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: ```mermaid --- 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: ```text 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: ```text 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: ```text 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`: ````markdown ```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. 1. Save this as `plan.mmd`: ```mermaid 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 ``` 2. 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. 3. Count periods with `grep -o 'class="taskWrapper"' plan.svg | wc -l`. It gave 4, one for each period line in the file. 4. 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. 5. Check that the direction word wasn't drawn: `grep -o '>TD<' plan.svg | wc -l` gave 0. 6. Check text with a colon, using three spaces between words: `grep -o '>Review at 16:00<' plan.svg | wc -l` gave 1. 7. 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.