吹き出し・コードブロック・図表の例

最終更新日: 2026/09/13 / EpoCanvas 公式アーキテクチャ仕様

質の高い技術ドキュメントを書くには、分かりやすい文章だけでなく、目立つポイントの強調、きちんと整形されたコード例、ひと目で分かる模式図も必要です。このページのすべての例は実際に有効な構文であり、見えているものがそのままレンダリング結果です。このページ自体が生きたサンプルページです。

1. 4 種類のカラー吹き出し（コールアウト）

吹き出し（コールアウト）はコロン 3 つの構文を使います：:::タイプ で始め、::: で終え、間に内容を書きます。本サイトは Starlight をベースにしており、note、tip、caution、danger の 4 種類に対応しています。

吹き出しの中でも、リスト、コードブロック、テーブルなどの構文をそのまま使えます。

コードフェンスの最初の行に title="ファイルパス" を書き、{行番号} でポイントとなる行をハイライトします。

```typescript title="src/config/site.ts" {2}
export const siteConfig = {
  name: 'EpoCanvas Docs', // この行がハイライト背景で強調されます
  version: '1.2.0',
};
```

レンダリング結果：

export const siteConfig = {
  name: 'EpoCanvas Docs',
  version: '1.2.0',
};

設定の更新やコードのリファクタリングを見せるときは、diff 言語を使うと変更点がひと目で分かります。- で始まる行は削除、+ で始まる行は追加として表示されます。

```diff
  export default defineConfig({
-   site: 'http://localhost:3000',
+   site: 'https://docs.epocanvas.com',
  });
```

レンダリング結果：

export default defineConfig({
  site: 'http://localhost:3000',
  site: 'https://docs.epocanvas.com',
});

bash、sh、powershell などのターミナル言語は、ターミナル風の暗い枠でレンダリングされます。

pnpm run build

現在のバージョンでは Mermaid などのテキスト図表のレンダリングは組み込まれていません。```mermaid フェンスをそのまま書いても、通常のコードブロックとしてソースが表示されるだけで、図は生成されません。

おすすめの方法は、mermaid.live などのツールで図を書いて SVG ベクター画像として書き出し、public/images/canvas/ に保存してから画像の構文で挿入することです。本サイトのアーキテクチャ図や言語切り替えのフロー図も、この方法で作成しています。

システムアーキテクチャの模式図

図：SVG 画像として挿入したアーキテクチャの模式図。どの倍率で拡大してもぼやけません。

Mermaid のソースをどうしても直接レンダリングしたい場合は、プロジェクトに追加のレンダリングプラグイン（例：rehype-mermaid）を導入する必要があります。これはカスタマイズの範疇なので、メンテナンスコストを見極めてから導入してください。

- [x] シンタックスハイライト対応
- [x] ワンクリックコピー対応
- [ ] Mermaid レンダリングの組み込み（計画中）

チェック状態付きのリスト項目としてレンダリングされます。

出典や補足説明を付けたいときは、GFM の脚注構文を使えます。

静的インデックスは Pagefind がビルド時に生成します[^pagefind]。

[^pagefind]: [Pagefind 公式ドキュメント](https://pagefind.app/) — 静的サイト向けのローカル検索ライブラリ。

レンダリング結果： 本文の末尾には番号付きの上付きジャンプマーク¹が現れ、クリックするとページ下部の脚注リストへスムーズに移動します。

吹き出し（コールアウト）、コードの注記、模式図を上手に使い分けると、技術ドキュメントの読みやすさと専門性が大きく向上します。構文の取り決めの全体は レンダリングルールの詳細 を参照してください。