asopi tech
asopi techIndie Developer
AstroのMarkdownにアニメーション図を埋め込む：Starch DSLと共通コンポーネント

【2026年8月版】

AstroのMarkdownにアニメーション図を埋め込む：Starch DSLと共通コンポーネント

公開日: 2026/08/19
読了時間: 約 7分

Astrostarchmarkdownfrontendanimation

ブログ記事で抽象的な概念や複雑な処理フローを分かりやすく説明するため、アニメーション表現を取り入れました。

本サイトでは、StarchのDSLで定義した図をMarkdownから表示する<animated-diagram>コンポーネントを追加しました。この記事では、実際の表示例と、Starchをどうラップして記事へ組み込んだかを紹介します。

Starchとは

Starchは、図形・経路・時間変化をテキストで定義し、その定義からブラウザー上にアニメーション図を描画するDSLです。

図形と経路をobjectsに、時間による変化をanimateに記述します。次の例では、線の上に置いたpacketを2秒かけて始点から終点へ移動させます。

DSL

name "Starch basics"
background #071015
viewport 480x260

style routeStyle
  stroke #557c50 width=3

objects
  route: path (60,120) (420,120) @routeStyle
  packet: ellipse 24x24 fill #a6d65f pathFollow=route pathProgress=0
  start: text "start" size=14 fill #eaf4f6 at 60,165
  end: text "end" size=14 fill #eaf4f6 at 420,165

animate 2 loop easing=linear autoKey=false
  0 packet.transform.pathProgress: 0
  2 packet.transform.pathProgress: 1

Starchのレンダリング結果

objectsで経路とパケットを定義し、animateでpathProgressを0から1へ変化させています。Starchはこの定義を読み込み、現在の時刻に対応する図をSVGとして描画します。

実際に表示した図

今回の例では、MCPのStateful構成とStateless構成を一つのアニメーション図で比較しています。セッション、Instance、認証経路、パケットの動きを一つの図で確認できます。

再生、一時停止、最初からの再生、再生位置の移動に対応しています。章を持つ図では前後の章へ移動でき、拡大ボタンから図を画面いっぱいに表示できます。

ブラウザーはDSLを読み込み、図の定義からその時刻のSVGを描画します。そのため、再生位置を移動して途中の状態も確認できます。

Markdownから表示する

今回の実装では、記事側にカスタム要素を書き、DSLの公開URLと図の説明を渡します。

<animated-diagram
  src="https://example.com/diagram.starch"
  aria-label="Stateful MCPとStateless MCPの比較アニメーション"
  autoplay
></animated-diagram>

srcでDSLの公開URLを指定し、aria-labelで図の内容を説明します。記事側には、図の定義と説明を渡す記述だけを置く形にしました。

Starchをどうラップしたか

Starchには図の描画を任せ、本サイトのコンポーネントで記事向けの表示と操作を加えました。カスタム要素がブラウザーへ接続されるとDSLを取得し、StarchDiagramに渡します。

実装の中心部分は次のコードです。

const source = this.getAttribute('src');
if (!source) {
  this.showError(`${this.copy.failed} src is required.`);
  return;
}

const response = await fetch(source, { signal: this.abortController.signal });
if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);

const dsl = await response.text();
this.diagram = new StarchDiagram(stage, {
  autoplay: false,
  onEvent: () => this.syncControls(),
});

const result = this.diagram.setDSL(dsl);
if (!result.ok) throw new Error(result.error);

this.dataset.ready = 'true';
this.dataset.warningCount = String(result.warnings.length);
this.dataset.duration = String(this.diagram.duration);
this.range.max = String(this.diagram.duration);

fetchでDSLを取得し、StarchDiagramを描画先のステージへ接続して、setDSLで解析します。解析に失敗した場合はエラーを表示し、成功した場合は再生時間をシークバーへ渡します。StarchがSVGを描画し、コンポーネントが記事に必要な操作を受け持つ分担です。

コンポーネントとして追加した機能

このコンポーネントには、アニメーション図のアクセシビリティを高め、再生・停止・シークなどを操作できるようにする機能をまとめました。

  • 再生、一時停止、最初からの再生、シーク、章移動、拡大表示
  • role="img"、aria-label、操作ボタンのラベル、再生状態の通知
  • prefers-reduced-motionが有効な環境での静止表示
  • 読み込みに失敗したときのエラー表示と、JavaScriptが無効なときの代替文
  • 画面幅に合わせた縮小表示と、ポインター操作で押しやすいボタン

図ごとに異なるのはStarchの定義と説明です。再生やアクセシビリティの処理は共通コンポーネントにまとめたため、記事ごとに同じ処理を実装せずに済みます。

VHSとStarchで埋め込み方を変えた理由

VHSでは、Astroのビルド時にVHSの台本からMP4・GIF・PNGを生成し、生成したファイルをHTMLとして記事に表示します。ブラウザーは生成済みのファイルを再生・表示します。

Starchでは、完成した動画ではなくDSLをブラウザーで読み込みます。<animated-diagram>がDSLを取得し、StarchDiagramへ渡して、その時刻のSVGを描画します。再生位置の変更や動きを減らす設定など、表示中の状態もコンポーネントが管理します。

この違いに合わせて、VHSでは生成済みメディアを指定するMarkdownのvideoコードブロックを使い、Starchではブラウザーで動くカスタム要素を使いました。StarchのDSL例は読みやすさのためコードブロックで示し、実際のアニメーション表示には<animated-diagram>を使っています。

まとめ

本サイトでは、抽象的な概念や複雑な処理フローを記事で説明するため、Starchのアニメーション図をMarkdownへ埋め込むコンポーネントを追加しました。

  • Starchで図形、経路、時間変化を定義する
  • コンポーネントがDSLを読み込み、StarchでSVGを描画する
  • 共通コンポーネントで操作、アクセシビリティ、エラー表示を提供する
  • MCPの構成と状態変化をアニメーションで説明する

参考