CIで検証する

このページは、Timeline DSL 利用者が自分のリポジトリで .tdsl ファイルを継続的に検証するための例です。Timeline DSL 本体やこのドキュメントサイトをデプロイする手順ではありません。

composite action を使う（推奨）

uses: keroway/timeline-dsl@v1 でインストールなしに .tdsl を SVG または HTML へレンダリングできます。Linux / macOS / Windows の全 runner に対応しています。

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/

インプット

インプット	必須	デフォルト	説明
file	✅	—	レンダリングする .tdsl ファイルのパス
format	—	svg	出力フォーマット: svg または html
output	—	<basename>.<format>	出力ファイルパス
offline	—	false	オフラインモード（Wikidata フェッチをスキップ）
interactive	—	false	インタラクティブ HTML 出力（format: html 時のみ）
theme	—	（CLI デフォルト）	テーマ: default / dark / print / pastel
scale	—	（CLI デフォルト）	水平軸のピクセル/年レート
version	—	latest	使用する tdsl バージョン（例: v1.6.0）

アウトプット

アウトプット	説明
output_path	生成された出力ファイルの絶対パス

PR で変更された .tdsl を SVG プレビューとしてアーティファクト化する例

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"

インタラクティブ HTML を 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

ダークテーマの SVG を生成してリリースに添付する例

タグ push などリリース起点のワークフローでの利用を想定した抜粋です。ジョブには actions/checkout ステップと permissions: contents: write（リリースへのアップロードに必要）を併せて設定してください。

- 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 }}

特定バージョンを固定して使う例

- uses: keroway/timeline-dsl@v1
  with:
    file: timeline.tdsl
    version: v1.5.0 # バージョンを固定

注意事項

• Wikidata フェッチ: import wikidata を使う .tdsl ファイルは offline: 'true' でなければ Wikidata API を呼び出します。CI での繰り返し実行には offline: 'true' + ローカルキャッシュの事前投入（tdsl cache コマンド）を推奨します。
• バージョン固定: 本番 CI では version: vX.Y.Z で固定することを推奨します。latest は常に最新版を取得します。
• GitHub Actions のキャッシュ: tdsl バイナリ自体は毎回ダウンロードします。ダウンロード時間を削減するには actions/cache でバイナリをキャッシュする構成も可能です。

tdsl CLI を直接インストールして使う

tdsl を複数のコマンドで使い回す場合は、インストールスクリプトで直接取得します。

GitHub Actionsでは、.tdsl ファイルに対して tdsl check、tdsl lint、必要に応じて tdsl build を実行します。Wikidataを使うファイルを安定して検証したい場合は、build に --offline を付けて静的項目だけを処理できます。

Ubuntu runnerで検証する例

Ubuntu runner ではインストールスクリプトで tdsl を取得し、~/.local/bin を 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

Homebrewでインストールする例

macOS runner では Homebrew で導入できます。

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

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

Wikidata import を含むファイル

ネットワーク取得を含めて検証する場合は通常の build または render を使います。CIの再現性を優先する場合は --offline を指定します。

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

search、inspect、resolve、scaffold wikidata はWikidataまたはWikipediaへのネットワーク接続が必要です。