Timeline DSL — VS Code Extension

Syntax highlighting and language intelligence for Timeline DSL (.tdsl) files.

Timeline DSL is a domain-specific language for building historical timelines with Wikidata integration.

• Landing page: https://timeline-dsl-lp.pages.dev/
• Try online (WebUI): https://keroway.github.io/timeline-dsl/
• GitHub: https://github.com/keroway/timeline-dsl

Features

Syntax Highlighting

• Keywords — the full, up-to-date list is generated from the single source of truth apps/webui/src/lang-tdsl/keywords.json (see BLOCK_KEYWORDS / ITEM_KEYWORDS / MISC_KEYWORDS); this extension's grammar (syntaxes/tdsl.tmLanguage.json) is regenerated from it via npm run prebuild in apps/webui
• String literals, comments (// and /* */)
• Wikidata entity IDs (Q123), property IDs (P569), and references (wd:Q123)
• Wikidata expressions: claim(P571).year, label@ja
• Numeric literals including negative years (e.g. -221 for 221 BCE)

Language Server (LSP) — requires tdsl binary

When the tdsl CLI is installed, this extension automatically starts the LSP server (tdsl lsp) and provides:

• Diagnostics — error and warning highlighting, updated on every edit
• Completion — context-aware keyword and snippet suggestions (e.g. claim(P123), label@ja inside map {})
• Hover — lane label/kind/order on hover; QID hover shows cached entity info (cache is populated by tdsl build or tdsl render; shows a hint if not cached)
• Go to Definition — jump to lane declarations
• Find References — find all usages of a lane ID
• Rename — rename a lane and all its references (only lanes declared with an explicit as <alias>; auto-slug lanes are not renameable)
• Code Actions — quick fixes from tdsl lint
• Document Symbols — outline view and breadcrumb navigation
• Formatting — format the document (comments are preserved like tdsl fmt; comments inside blocks may be relocated to canonical positions)

Installing the tdsl binary

# Homebrew (macOS / Linux)
brew tap keroway/tap
brew install tdsl

# Cargo
cargo install --git https://github.com/keroway/timeline-dsl tdsl-cli

See the installation guide for other platforms and options.

Configuration

Commands — requires tdsl binary

The preview runs tdsl render once per refresh rather than keeping tdsl render --watch alive: a long-lived child process would have to be torn down on every window close, workspace switch, and extension reload, and a missed teardown leaves the process running.

The preview requires a saved file (the CLI takes a path). Scripts are disabled in the Webview (default-src 'none'); interactive features live in the WebUI.

Example

// Chinese Dynasties Timeline

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

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

span qin -221..-206 "Qin Dynasty" { source wd:Q7183; };
span han -206..220  "Han Dynasty" { source wd:Q7209; };

event qin -221 "Unification of China" {};

// Import from Wikidata
import wikidata as wd {
    entity Q7209 as han_entity;
}
map wd.han_entity to span {
    lane han;
    label label@en;
    start claim(P571).year;
    end   claim(P576).year;
}

Usage

Install the Timeline DSL CLI to compile .tdsl files:

# Build to JSON IR
tdsl build my_timeline.tdsl --pretty

# Render to HTML/SVG
tdsl render my_timeline.tdsl -o output.html

# Check for errors
tdsl check my_timeline.tdsl

Links

• GitHub Repository
• Landing Page
• WebUI
• DSL Specification
• Report an Issue

License

MIT © keroway