Validate in CI

This page provides examples for continuously validating .tdsl files in your own repository. It is not a guide for deploying Timeline DSL itself or this documentation site.

Using the Composite Action (Recommended)

With uses: keroway/timeline-dsl@v1, you can render .tdsl files to SVG or HTML without any manual installation. It supports Linux, macOS, and Windows runners.

name: Render Timeline

on:
  push:
    paths: ["**/*.tdsl"]

jobs:
  render:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: keroway/timeline-dsl@v1
        with:
          file: examples/china_dynasties.tdsl
          format: svg
          output: output/china.svg

      - uses: actions/upload-artifact@v4
        with:
          name: timeline-svg
          path: output/

Inputs

Input	Required	Default	Description
file	✅	—	Path to the .tdsl file to render
format	—	svg	Output format: svg or html
output	—	<basename>.<format>	Output file path
offline	—	false	Offline mode (skip Wikidata fetching)
interactive	—	false	Interactive HTML output (only when format: html)
theme	—	(CLI default)	Theme: default / dark / print / pastel
scale	—	(CLI default)	Horizontal axis pixels-per-year rate
version	—	latest	The tdsl version to use (e.g. v1.6.0)

Outputs

Output	Description
output_path	Absolute path to the generated output file

Example: Artifact changed .tdsl files as SVG previews on PRs

name: TDSL Preview

on:
  pull_request:
    paths: ["**/*.tdsl"]

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: keroway/timeline-dsl@v1
        with:
          file: examples/china_dynasties.tdsl
          format: svg
          offline: "true"

      - uses: actions/upload-artifact@v4
        with:
          name: tdsl-preview
          path: "*.svg"

Example: Deploy interactive HTML to GitHub Pages

name: Deploy Timeline

on:
  push:
    branches: [main]
    paths: ["timelines/**/*.tdsl"]

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pages: write
      id-token: write
    steps:
      - uses: actions/checkout@v4

      - uses: keroway/timeline-dsl@v1
        with:
          file: timelines/main.tdsl
          format: html
          output: public/index.html
          interactive: "true"
          offline: "true"

      - uses: actions/upload-pages-artifact@v3
        with:
          path: public/

      - uses: actions/deploy-pages@v4

Example: Attach a dark-theme SVG to a release

This is an excerpt intended for release-triggered workflows such as a tag push. Configure the job with an actions/checkout step and permissions: contents: write (required to upload to the release).

- uses: keroway/timeline-dsl@v1
  id: render
  with:
    file: timeline.tdsl
    format: svg
    output: timeline-dark.svg
    theme: dark

- name: Upload to release
  uses: softprops/action-gh-release@v2
  with:
    files: ${{ steps.render.outputs.output_path }}

Example: Pin a specific version

- uses: keroway/timeline-dsl@v1
  with:
    file: timeline.tdsl
    version: v1.5.0 # Pin the version

Notes

• Wikidata fetching: .tdsl files that use import wikidata call the Wikidata API unless offline: 'true' is set. For repeated CI runs, we recommend offline: 'true' plus pre-populating the local cache (via the tdsl cache command).
• Version pinning: for production CI, we recommend pinning with version: vX.Y.Z. latest always fetches the newest release.
• GitHub Actions caching: the tdsl binary itself is downloaded on every run. To reduce download time, you can cache the binary with actions/cache.

Installing the tdsl CLI Directly

If you need to run multiple tdsl commands, install it directly via the install script.

In GitHub Actions, run tdsl check, tdsl lint, and optionally tdsl build against your .tdsl files. For stable validation of files that use Wikidata, add --offline to build to process only static items.

Example: Validate on an Ubuntu runner

On Ubuntu runners, install tdsl via the install script and add ~/.local/bin to PATH.

name: Timeline DSL

on:
  pull_request:
  push:
    branches: [main]

jobs:
  tdsl:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install tdsl
        run: |
          curl -sSfL https://raw.githubusercontent.com/keroway/timeline-dsl/main/install.sh | sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"

      - name: Check timeline
        run: tdsl check examples/china_dynasties.tdsl

      - name: Lint timeline
        run: tdsl lint examples/china_dynasties.tdsl --format json

      - name: Build JSON
        run: tdsl build examples/china_dynasties.tdsl --pretty --output timeline.json

Example: Install via Homebrew

On macOS runners, you can install via Homebrew.

jobs:
  tdsl:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install tdsl
        run: |
          brew tap keroway/tap
          brew install tdsl

Files with Wikidata Imports

Use the standard build or render to validate files including network fetching. Add --offline when you want reproducible CI runs.

tdsl build examples/china_with_import.tdsl --pretty
tdsl build examples/china_with_import.tdsl --offline --pretty

search, inspect, resolve, and scaffold wikidata require a network connection to Wikidata or Wikipedia.