レンダリングルールの詳細
このページでは EpoCanvas Docs のレンダリングルールを完全に説明します。1 つの Markdown ファイルがどの処理段階を経るのか、各構文がどんな見た目にレンダリングされるのか、どの構文が非対応なのか。ドキュメントを書く前に一通り読んでおくと、ほとんどのレイアウトの問題を避けられます。
レンダリングパイプライン：.md ファイルから公開ページまで
図：Markdown レンダリングパイプラインの 5 ステップ。各ステップはビルド時に順番に実行され、ビルド成果物は純粋な静的ファイルで、クライアント側に実行時のフレームワークオーバーヘッドはありません。
1 つの Markdown ファイルは、保存されてから読者の目に触れるまで、次の 5 つの段階を経ます。
- コンテンツの収集：Astro は起動時またはビルド時に
src/content/docs/ディレクトリを走査し、各.md/.mdxファイルをコンテンツエントリーとして登録し、Frontmatter を検証します（titleがないとその場でエラーになります）。 - Markdown のコンパイル：本文は Markdown コンパイラー（GFM 拡張を含む）によって HTML に変換されます。テーブル、タスクリスト、取り消し線などの拡張構文はこの段階で有効になります。
- コードブロックのハイライト：すべてのコードフェンスは Expressive Code に渡され、シンタックスハイライト、タイトルバー、行番号、コピーボタン付きのコードブロックとして生成されます。
- サイトレイアウトの適用：コンパイル済みの HTML は Starlight のページ骨格に組み込まれます。トップバー、左側のサイドバー、右側の目次は、いずれも
src/components/starlight/配下のカスタムコンポーネントがレンダリングします。 - インデックスと静的ファイルの生成：
pnpm run buildの実行時に Pagefind がすべての成果物ページを走査して全文検索のインデックスを抽出します。最終的にdist/ディレクトリ内の純粋な HTML は、どんな静的サーバーにもそのままホストできます。
Frontmatter のルール
titleは必須で、欠けているとビルド時にInvalidInputErrorが出ます。descriptionは記入を推奨します。検索エンジンの結果やシェアカードに表示されます。- Frontmatter はファイルの先頭にある有効な YAML ブロックでなければならず、ハイフン 3 つの行はどれも省略できません。
見出しのルール
| ルール | 説明 |
|---|---|
本文ではレベル 1 見出し # を書かない | Frontmatter の title がすでにページの大見出しとしてレンダリングされるため、本文でさらに # を書くと大見出しが 2 つ並んでしまう |
本文はレベル 2 見出し ## から始める | ## と ### は右側の「目次」に自動的に入る |
#### 以下は目次に入らない | より深いレベルは本文のスタイルとしてだけレンダリングされる |
| 見出しのテキストからアンカーが生成される | 日本語見出しのアンカーは日本語の文字そのものになる。例：#見出しのルール |
吹き出し（コールアウト）のルール (Asides)
吹き出し（コールアウト）は Starlight のコロン 3 つの構文を使用し、4 種類に対応しています。
:::note補足説明のヒント。:::
:::tip効率を上げるちょっとしたコツ。:::
:::caution注意すべきリスクやミスしやすい操作。:::
:::dangerデータ損失や不可逆な操作にかかわる危険度の高い警告。:::また、タイプの後にカスタムタイトルを付けられます：:::tip[インストールの高速化]。
図：4 種類の吹き出し（コールアウト）を上記の構文で書いたときの実際の表示。吹き出し・コードブロック・図表の例 ページから抜粋。
コードブロックのルール
コードフェンス（バッククォート 3 つ）は Expressive Code でレンダリングされ、以下の注記に対応しています（最初の行のバッククォートの後に書きます）。
| 注記の書き方 | 役割 | 例 |
|---|---|---|
| 言語識別子 | シンタックスハイライトの方式を決める | ```ts |
title="..." | ファイル名のタイトルバーを表示する | ```ts title=“src/config/site.ts” |
{2} / {2-4} | 指定した行をハイライトする | ```ts {2} |
lang="diff" または diff | 追加・削除行を赤と緑の対比で表示する | ```diff |
bash / sh などのターミナル言語 | ターミナル風の枠でレンダリングする | ```bash |
すべてのコードブロックには自動的にワンクリックのコピーボタンが付きます。コードのテキストは Pagefind によって検索インデックスに収録されるため、コード内のキーワードを直接検索できます。
画像のルール
- 画像は一括して
public/images/canvas/に置き、絶対パスで参照します：。 - アーキテクチャやフローの模式図は
.svgベクター形式、画面のスクリーンショットは圧縮した.pngを使います。 - 説明文（alt）は必ず記入します。画像の読み込みに失敗したときの代替テキストであり、アクセシビリティの根拠にもなります。
- 現在のバージョンでは Mermaid 図表のレンダリングは組み込まれていません：
```mermaidフェンスは通常のコードブロックとしてソースを表示するだけです。フローチャートが必要な場合は、まず mermaid.live などのツールで SVG を書き出し、画像として挿入します。
リンクのルール
- サイト内リンク：完全なパスを使い、
/で始まり/で終わる形にします（例：/canvas/deployment/）。ドキュメントのパスを変更した後は、旧パスをastro.config.mjsのredirectsテーブルにリダイレクトとして登録します。 - アンカーリンク：
/canvas/rendering/#コードブロックのルールでこのページのセクションへ直接移動できます。 - 外部リンク：完全な URL を書けばよく、本文中ではテーマカラーで表示されます。
その他のレンダリング挙動
| 構文 | レンダリング結果 |
|---|---|
**太字**、*斜体*、~~取り消し線~~ | 対応する文字スタイル |
インラインコード | テーマカラーの等幅フォントのカプセル |
| Ctrl+K の書き方 | キーキャップ風のキー表示 |
| GFM テーブル | 枠線とホバー時のハイライト付きのデータテーブル |
- [x] タスクリスト | 視覚的なチェックボックス（無効状態） |
[^名前] 脚注 | 本文の上付き番号 + ページ下部の脚注リスト。クリックで往復移動できる |
Markdown 引用ブロック > | 左側にテーマカラーの縦線 + 薄い背景色 |
区切り線 --- | 本文エリアを貫く細い分割線 |