FAQ

What can Timeline DSL output?

tdsl build outputs IR JSON, and tdsl render outputs standalone HTML. You can open the HTML in a browser to view the timeline.

What use cases is it good for?

It suits timelines where you want the source (.tdsl text) to be the single source of truth and to manage diffs and reviews in Git. You can build histories, project timelines, biographies, or product release histories from hand-written data or from Wikidata / CSV.

• Try it quickly: the browser-only Playground lets you write DSL and render it instantly with no install.
• Produce a deliverable: the CLI’s tdsl render outputs standalone HTML (with theme and custom CSS support).
• Operate it continuously: wire tdsl check / tdsl lint into CI to review timelines like any other code.

If your main goal is a real-time, continuously updating dashboard or an interactive editing UI, that is outside this tool’s scope.

Can I use it without Wikidata?

Yes. Static .tdsl files written by hand using timeline, lane, span, event, and event_range can be validated, built, and rendered locally. For files that include Wikidata imports, adding --offline to build and render processes only the static items.

Which command should I start with?

Use tdsl init when creating manually, or tdsl search and tdsl inspect when creating from Wikidata. If you just need to check an existing file, use tdsl check and tdsl lint.

How do I write BCE years?

Use negative integers. For example, 206 BCE is -206, and 221 BCE is -221.

span qin -221..-206 "Qin dynasty" { tags ["dynasty"]; };

Negative integers can also be used for the start of a range:

timeline "Ancient History" {
    range -500..500;
}

Can I define multiple lanes?

Simply list multiple lane declarations. Use order to control the display order (lower numbers appear higher).

lane "Qin"       as qin    { kind dynasty; order 10; }
lane "Han"       as han    { kind dynasty; order 20; }
lane "Three Kingdoms" as sanguo { kind dynasty; order 30; }

kind is a classification label; you can freely specify values like dynasty, person, nation, etc. If you do not provide an explicit as ID, an ASCII slug is auto-generated from the label (for labels with only non-ASCII characters, names like lane_1, lane_2, … are assigned automatically).

Can I import from CSV?

Yes, tdsl import-csv is available. The CSV must be UTF-8 and requires a header row of lane,type,start,end,time,label,tags,id. The source / origin columns are optional additions, and it accepts the 10-column CSV produced by tdsl export-csv as-is.

tdsl import-csv items.csv
tdsl import-csv items.csv --append manual.tdsl

What should I run in CI?

The basics are tdsl check and tdsl lint. If you want to verify artifact generation as well, add tdsl build --pretty --output timeline.json. Use --offline if you want to avoid Wikidata fetching.

Can I reset the Wikidata fetch cache?

Yes. The Wikidata fetch cache is stored under ~/.cache/tdsl/ and managed with the tdsl cache command.

tdsl cache status
tdsl cache clear
tdsl cache clear --older-than 30

Can I choose an HTML theme?

Use tdsl render --theme to specify default, dark, print, or pastel. Custom CSS can be added with --custom-css.

Can I always show every label, for printing or listing?

Yes. Use the CLI’s tdsl render --show-event-labels, or the Playground toolbar’s “Always show labels (print/listing)” toggle, to draw labels for every Event / EventRange without hovering (v1.17.0+). The Gallery sample list has the same toggle for print/listing previews.