Chronos Timeline: interactive timelines for Obsidian

Render interactive timelines in your Obsidian notes from simple Markdown. Make time make sense.

Powered by chronos-timeline-md, a markdown wrapper for vis-timeline.

Try it in the Live Playground

!demo

Features

• Portable plain text data
• Bases view
• Note linking
• Inline snippets
• Text-to-timeline with AI (multi-provider)
• Generate combined timeline from all Chronos items in folder
• Grouping
• Colors
• Render timelines anywhere outside Obsidian

Quickstart

Create timelines in your notes by opening a chronos codeblock and adding items

You can insert blank, basic, or advanced templates using the Command Pallete (ctrl/cmd + p, "Chronos")

Insert basic template

!palette example basic

Insert advanced template

!palette example advanced

Insert snippet widget

While editing inside a Chronos code block, use Insert snippet to add a point, event, period, marker, comment, or flag at the cursor.

You can click the button or press Mod+Shift+Enter (Ctrl+Shift+Enter on Windows/Linux, Cmd+Shift+Enter on macOS). This shortcut works only inside a Chronos code block; Tab keeps Obsidian's normal indentation behavior.

Generate timeline with AI

Highlight text in your notes and run the "Generate" command.

Choose a provider in Chronos settings. Cloud providers use a key selected from Obsidian SecretStorage. OpenRouter, Ollama, and LM Studio use OpenAI-compatible endpoints; the local model list is loaded from the server's /models endpoint. Set the base URL first, then use Refresh models if you change the server or model list. Ollama and LM Studio do not require an API key.

Input can be long text in your notes with time information, or vague like:

• "Detailed history of the Cold War"
• "Compare the life and works of Borges and C.S. Lewis"
• "Year and location of the past 20 Olympic games. Do not group. Do use points not events"

!genai example 2

Generate timeline from folder

Automatically create combined timelines from all Chronos items found in a folder.

NOTE: This is for statically generating a timeline from a folder. For dynamic timelines, use the Chronos Timeline Bases view.

!gen from folder example

Use the command palette (Cmd/Ctrl + P): Chronos > Generate Timeline from Folder

The plugin will:

1. Show you a list of folders that contain Chronos items
2. Extract all Chronos items from the selected folder
3. Generate a combined timeline using all these items
4. Insert the timeline code at your cursor position

• Visualizing collections of dated notes (journals, meetings, project milestones)
• Combining themed items (by topic, person, project, etc)
• Generating chronological overviews of any folder

Tip: Use inline chronos blocks in your notes for quickly collecting timeline items that you don't particularly care about rendering in respective notes

The below item will not render in your notes, but will be picked up in the "Generate Timeline from Folder"
chronos @ [2025~2026] Year of the Snake
If you omit the Chronos item type (Event -, Period @, Point * etc), it will default to an Event (-) in your combined timeline.
chronos [2025~2026] Year of the Snake
^ Event

Cheatsheet

After installing the Chronos Timeline plugin, paste the contents of this cheatsheet into a file in your vault to play with examples

Contents

• Chronos Timeline: interactive timelines for Obsidian

• Syntax Overview

• Obsidian Bases view
• Note linking (beta)
• Actions

• Localization

Syntax Overview

Chronos parses Markdown in chronos code blocks into objects on a timeline

The first character of each line in your chronos block determines the item type:

• Events (-)
• Periods (@)
• Points (*)
• Markers (=)
• Comments (#)
• Flags (>)

A note on dates

Chronos can visualize dates from the year down to the second level, using the syntax YYYY-MM-DDThh:mm:ss.

The only required component of a date is the year (YYYY). Beyond that, you can specify additional time granularity as needed for your use case.

If not explicitly provided:

• The month and day default to 01 (January and the 1st)
• The hour, minute, and second default to 00 (top of the hour or minute)

Examples

- [2020] A year
[2020-02] A month
[2020-02-28] A day
[2020-02-28T12] An hour
[2020-02-28T12:30] A minute
[2020-02-28T12:30:09] A second

Date ranges

Date ranges are separated by a tilde ~, NOT a hyphen! Look out :)

The start and end date must be in chronological order.

- [2020~2024]
[2024-02-28~2024-05-11]
[2024-02-28T05:30~2024-02-28T08:30]

BCE time

You can signify BCE times with the negative symbol (-)

- [-10000]    <--- 10000 BCE
[-550~-20]  <--- 550 ~ 20 BCE
[-550~550]  <--- 550 BCE ~ 550 CE

Limitations

• Dates must be between year 271,821 BCE and 275,761 CE, due to how Dates work in JS

Events -

Events can include a single date or a date range.

Events with a single date

Syntax

- [Date] Event Name

Only [Date] is required. If no Event Name is provided, the event title will default to the date or date range.

Example

!single date event example

Events with start and end dates

A date range is represented with a tilde (~) between the start and end dates.

Syntax

- [Date~Date] Event Name

Example

!event with range example

Events with descriptions

You can add additional information to an event by adding a pipe | after the Event name. This text will appear in a popup when you hover over an event.

Example

!event with range example

Periods @

Periods are spans of time displayed with a semi-transparent background. Periods must be a range with a start and end date. Period Name is optional

@ [Date~Date] Period Name

Example

!period example

Points *

Points are ideal for marking a point in time. You can optionally add a Description that will appear on hover.

* [Date] Point Name | Description

!point example

Markers =

Markers can be used to highlight a key milestone in time. Markers must be a single date. Marker Name is optional

= [Date] Marker Name

Example

!marker example

Comments #

Chronos will ignore any line that starts with #. You can use this to write comments to yourself or block out items.

Example

!comment example

Flags >

You can add flags to your timeline by using the > symbol. Flags are parsed on separate lines, and are case insenstive. You can use multiple flags.

Example: The timeline below uses the NOTODAY and ORDERBY flags, to hide the current time marker and to order the stack of overlapping items by start date.

NOTODAY flag

Hide the vertical bar that marks today's time

> NOTODAY

(without flag)

!notday without flag example

(with flag)

!notday with flag example

HEIGHT flag

Set a fixed height for a given timeline (in pixels).

If needed, you can vertically scroll your timleline by clicking and dragging up or down

> HEIGHT <number of pixels>

!height example

ORDERBY flag

By default, Chronos ordering is set by the stacking of the elements in the timeline.

The ORDERBY flag can be used to specify an ordering

[!WARNING]

Ordering can make the timeline laggy when there are many items. Use with precaution

> ORDERBY start|-content

• You can use any of these fields: start | end | content | color | description.

• You can stack them by joining them with a pipe | to add another sorting level.
• You can prepend a dash - to any of the fields to order in descending order on this field.

Example

Order by start date

!order by start date

Order by color and start

!order by color and start date

DEFAULTVIEW flag

Use the > DEFAULTVIEW start|end flag to specify default start and end dates for your timeline's initial load. You can use YYYY-MM-DD timestamps for the start and end date, with the minimum requirement being YYYY.

> DEFAULTVIEW  -3000|3000
[2024] AGI

Modifiers

Modifiers #color and {Group} can be added to Events (-) and Periods (@) with the following optional syntax.

- [Date-Date] #color {Group Name} Name | Description

The modifiers must go in this order: between Dates and Name, with color first if both color and group are used.

Colors #color

By default, Chronos matches your Obsidian theme color.

To give items a specific color, you can include an available color after the date: #red | #orange | #yellow | #green | #blue | purple | #pink | #cyan

Example

!color example

Groups {}

Events and Periods can be grouped into "swimlanes" by specifying a Group Name in curly brackets {} after the Date (or Color, if present). Group names are case sensitive and may contain spaces.

The order of items does not matter, but the example below lumps items together by group for human legibility.

Example

!groups example

Advanced example

This example combines Events, Periods, Markers, Comments, Descriptions, Groups and Colors

!advanced example

Obsidian Bases view

By adding frontmatter properties to your notes or using formulas, you can easily make dynamic and highly portable timelines! Any note with at least a start property will show. Properties marked with ? below are optional

start           (Chronos date)
end?            (Chronos date)
content?        (Optional alternate title - defaults to note name)
type?           (event|point|period|marker - defaults to event)
color?          (red|orange|yellow|green|blue|purple|pink|cyan|<hexcode>)
description?

!example: Chronos Timeline View in Obsidian Bases

Bases: Adding a Chronos Timelines Bases view

1. From a base, click "Add View" from the Views dropdown

1. Select "Chronos Timeline" view and give a custom name

1. (Optional) Select filters for notes (ex: all notes in a given folder, all notes with tag #history, etc...)

Note: Only notes with start property will show up in the timeline - other notes will be ignored.

Dragging your Bases view into the right or left side panels allows you to watch your timeline update in realtime as you add notes and update properties.

You can also create properties with Formulas. See Formulas section.

Bases: Adding properties to notes

At the very top of a note you'd like to see in the Chronos Timeline Bases view, add properties by typing --- on the first line (Figure A). Or by using the properties wizard if it is already showing (Figure B).

Figure A

Figure B

start           (Chronos date)
end?            (Chronos date)
content?        (Optional alternate item title - defaults to note name)
type?           (Option: event|point|period|marker - defaults to event)
color?          (Optional: red|orange|yellow|green|blue|purple|pink|cyan|<hexcode>)
description?    (Optional)

Bases: Changing property values

You can change the default values for properties using the Item Property Sources configuration.

You can configure the default property names for new Bases views in the plugin Settings.

Bases: Using Formulas to calculate custom values for properties

You can use Obsidian's formulas feature in Bases to implement custom logic for your properties.

This can be useful for creating custom logic for coloring or event types, for example.

See Obsidian's Formula documentation for more.

Bases: Grouping

Groups in the Chronos Timeline view can be created in one of two ways:

1. Via the Bases "Group by" query selector under "Sort"
2. By adding a group value in the Item Property Sources

The group property (or formula) will be used if no "Group by" query selector is chosen, but note that it must be selected in the property list in order to work.

Using the "Group by" method

You can use Formulas for more flexible grouping. For a trivial example, let's say you wanted to group items by some property like author:

1. (Optional) Add a filter to target specific items. In this example, we target a folder.

1. Select a property to group by in the "Sort" menu, such as author in this example

Using manual "group" property on notes

You can also add a property named group (or custom name in settings) to notes directly, and select that property in your Chornos Timelines view for Bases.

Using formulas for grouping

Formulas also allow for more complex logic to determine groups. For example, if you want to assign group labels based on the folder a given note is in:

if(file.folder.contains("Japan"), "Japan", if(file.folder.contains("China"), "China", ""))

See Obsidian's Formula documentation for more.

Bases: How Chronos Timeline Bases view resolves properties

There are two rules to know:

1. The Chronos Timeline Bases view will only display properties that are selected.

1. If two properties of the same name are selected (ex: group in a note frontmatter, and group as a custom formula) the Formula value will override the note frontmatter.

Bases: Interacting with the Chronos Timeline view

The Chronos Timeline Bases view automatically links to the related note.

You can hover on an item and hold Cmd/Ctrl to see a note preview before jumping.

You can also Copy the generated markdown (to paste in chronos blocks in your notes), or Copy a shareable link (stripped of wikilinks) that you can send your friends online

Note linking (beta)

Link to other notes in your vault by adding a wiki link to either the item name or description. Type [ then a few characters in your note title for Obsidan to auto-suggest a path to insert. Chronos will link to the first link provided in an item.

![example: note linking

Examples:

!example: note linking 2

You can link directly to a section heading in a note by adding #section name to the path

Note: Moving or renaming a note SOMETIMES updates links in your Chronos timeline blocks, if the path is used for the link (not an alias, ex: just note instead of path/to/note). I'm working on updating alias links safely

Previewing links

While hovering a timeline item with a link, press Control or Command to show a preview of the linked note

!example: link preview

Dynamic Timelines

Turn your Obsidian notes into living, breathing timelines that update automatically as you work. By combining Chronos with Dataview, you can create timelines that dynamically reflect your notes, tasks, or any other data in your vault.

Prerequisites

• Dataview plugin installed
• JavaScript queries enabled in Dataview settings

Basic Example

Create a timeline of birthdays from notes in the directory Contacts and also link the notes:

let events = pages .map((p) => { const date = new Date(p["birthday"]).toISOString().split(".")[0]; const title = p.file.name; return - [${date}] ${title} | [[${title}]]; }) .join("\n");

const chronosBlock = \\\chronos\n${events}\n\\\; dv.paragraph(chronosBlock);

Advanced Usage

Create a timeline of all contacts' birthdays, with family members highlighted in blue:

// Generate events with family members in blue let events = contacts .map((p) => { const date = new Date(p.birthday).toISOString().split("T")[0]; const isFamily = p.tags?.includes("family"); const color = isFamily ? "#blue" : ""; return - [${date}] ${color} ${p.file.name} | [[${p.file.path}]]; }) .join("\n");

// Add some styling const chronosBlock = \\\chronos

ORDERBY start

Combining Dynamic and Static Events

You can mix dynamically generated events with static timeline entries. Here's an example that combines dynamic birthdays with fixed holidays and periods:

// Generate birthday events let birthdayEvents = contacts .map((p) => { const date = new Date(p.birthday).toISOString().split("T")[0]; const isFamily = p.tags?.includes("family"); const color = isFamily ? "#blue" : ""; return - [${date}] ${color} ${p.file.name} | [[${p.file.path}]]; }) .join("\n");

// Combine with static events const chronosBlock = \\\chronos

ORDERBY start

Tips

• Use frontmatter dates for consistent formatting (also for ranges)
• Style events with dynamic colors and groups using any Dataview query logic
• Mix with static events and periods
• Leverage Dataview's full query capabilities to generate timeline events

Actions

Edit

To enter Edit mode an update your chronos Markdown, hover over the timeline and click the code icon that appears in the upper-right corner.

!edit example !edit example - markdown mode

Refit

Click the Refit button (crosshairs icon) in the lower-right corner to adjust all items to fit within the view window.

!refit example

Toggle width

Hover on the timeline and click the width toggle in the upper left to expand the timeline to the width of your editor.

!chronos-width-expand

Localization

You can choose your preferred language for dates, from the Chronos Timeline plugin settings.

Available options depend on your system's language settings.

!localization example - settings menu

!localization example - tooltip