Your notes already contain a timeline

What a note needs

A date, in one form or another. Everything else it already has.

---
title: Kickoff workshop
date: 2026-01-15
duration: 2d
status: open
categories: [discovery]
---

Notes from the workshop go here, as usual.

The scan looks for a date in the frontmatter fields you configure — by default date, then scheduled, then created — and falls back to a date pattern in the filename, so a daily note named 2026-01-15-standup.md lands on the right day without any frontmatter at all. A note where none of that resolves is left out, and the build says how many it skipped.

Views are saved queries over the notes

A single folder of notes usually holds several timelines. Rather than splitting the folder, you define views in the configuration file, and each one filters the same scan:

{
  "notesDir": "~/notes",
  "dateFields": ["date", "scheduled", "created"],
  "views": [
    {
      "id": "research",
      "name": "Research",
      "filter": { "categories": ["research"], "draft": false },
      "groupBy": "categories[0]"
    },
    {
      "id": "meetings",
      "name": "Meetings",
      "filter": { "filenameContains": "meeting" },
      "dateFields": ["scheduled", "date"],
      "groupBy": "status"
    }
  ]
}

Filters combine folder, filename, status, categories, tags and draft state, and nest with anyOf, allOf and not. groupBy picks the frontmatter field that becomes the lane, so the same notes can be grouped by category in one view and by owner in the next.

Why keep it one-directional

Zeitlines never writes into the notes folder. That is a deliberate limit rather than a missing feature: a Markdown note is a document a person is editing, and a tool that rewrites frontmatter underneath an open editor produces conflicts that are hard to even notice. If a date is wrong, you fix it in the note, and the timeline follows on the next save.

The consequence worth planning around is that notes-driven views are read-only in the browser. When you want to drag items around, use a file-based plan or a database-backed timeline instead.

Setting it up

# point at your notes folder…
export TIMELINES_NOTES_DIR=~/notes
npm run dev

# …or set "notesDir" in timelines.config.json

A missing notes folder is a warning, not a failure — the build continues with zero notes, so a fresh clone of the repository still starts. That matters more than it sounds: it is what lets someone try Zeitlines before deciding which folder to point it at.

Related

• A hand-written project plan instead
• Self-hosting Zeitlines
• Date extraction in the documentation

Frequently asked questions

Can I build a timeline from my Obsidian vault?

Yes. Zeitlines reads plain Markdown with YAML frontmatter, which is what an Obsidian vault is on disk. Point it at the vault folder and every note carrying a resolvable date becomes an item. Nothing is written back, so the vault stays exactly as your editor left it.

Which frontmatter field is used as the date?

By default date, then scheduled, then created, and finally a date pattern in the filename such as 2026-01-09-…. The order is configurable, and a single view can override it — so one view can sort by when something is scheduled while another sorts by when it was written.

What happens to notes without a date?

They are skipped, and the build reports how many. A timeline of notes is a timeline of the ones that belong on it; silently placing an undated note at an invented position would be worse than leaving it out.

Can a note span a range instead of a single day?

Yes. A duration in the frontmatter (7d, 2w, 90m) extends the start into a bar, or an end / end_date / until field gives the end date directly.

Does the timeline update while I write?

Yes. The development server watches the notes folder and rebuilds whenever a Markdown file changes, so saving a note updates the timeline in the browser.