Configuration

Timeline DSL does not require a dedicated configuration file. Behavior is controlled through declarations in your .tdsl file and CLI options.

Basic .tdsl Settings

The display name, unit, range, and calendar system for the entire timeline are declared in the timeline block.

timeline "Chinese Dynasties" {
    title "Chinese Dynasties";
    unit year;
    range -500..2000;
    calendar proleptic_gregorian;
}

Lane categories (vertical axis) are defined with lane. span, event, and event_range reference already-defined lanes.

lane "Han" as han { kind dynasty; order 20; }

span han -206..220 "Han" { tags ["dynasty"]; source wd:Q7209; id "span:han"; };
event han -209 "Dazexiang Uprising" {};
event_range han 184..204 "Yellow Turban Rebellion" { tags ["war"]; };

Wikidata Fetching

build and render perform network fetching when processing .tdsl files that include Wikidata imports.

tdsl build china_with_import.tdsl --pretty
tdsl render china_with_import.tdsl --output china.html

Use --offline to process only static items without network access.

tdsl build china_with_import.tdsl --offline --pretty

Use --no-cache to re-fetch without the cache, or --cache-ttl <seconds> to change the cache TTL. The default TTL is 86400 seconds.

HTML Rendering

tdsl render outputs a standalone HTML file. Display adjustments are specified via CLI options.

tdsl render sample.tdsl \
  --output sample.html \
  --scale 5 \
  --lane-height 60 \
  --left-gutter 120 \
  --top-margin 40 \
  --theme pastel

--theme accepts default, dark, print, or pastel. To inject additional CSS, use --custom-css path/to/custom.css.

Choosing an Output Format

tdsl render can output HTML / SVG / PNG / PDF, switched via --format. Choose based on your use case.

| Format | Option | Characteristics | Typical use | | ------ | -------------- | ----------------- | ------------------------------ | | HTML | (default) | Standalone HTML | Web display, browser preview | | SVG | --format svg | Vector / scalable | Web embedding, articles | | PNG | --format png | Raster (v1.10.0+) | Social sharing, previews | | PDF | --format pdf | Vector (v1.11.0+) | Print, high-resolution display |

PNG is a raster image, so you can adjust its resolution. Use --dpi <N> (default 96) to scale from SVG user units by dpi / 96, or --png-scale <factor> to specify the multiplier directly. The two cannot be combined (v1.11.0+).

tdsl render sample.tdsl --format png --dpi 192 --output sample.png
tdsl render sample.tdsl --format png --png-scale 2.0 --output sample.png

PDF is emitted as a vector format, so it does not degrade when printed or displayed at high resolution (v1.11.0+).

tdsl render sample.tdsl --format pdf --output sample.pdf

See render in Commands for details on each option.

Lint

tdsl lint supports text and json output formats.

tdsl lint sample.tdsl
tdsl lint sample.tdsl --format json
tdsl lint sample.tdsl --fix

--fix applies safe fixes to the file, including: removing duplicate tags, removing empty tags, swapping start and end when they are in the wrong order, and generating stable IDs for entries without one.