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.

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.

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 choose an HTML theme?

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