Markdown 執筆と整形ガイド

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

EpoCanvas Docs でのドキュメントの追加や編集はとても簡単です。本文はすべて標準の Markdown 構文で書かれており、Markdown が書ければすぐにドキュメントの執筆と保守に参加できます。

このページはサイト全体で使えるフォーマットの完全な一覧です。3 節で基礎 Markdown のフォーマットを 1 つずつ挙げ、4 節でこのサイトが追加でサポートする拡張構文を紹介します。各項目には「書き方」と「レンダリング結果」の対照を載せており、いま見えている表示がそのまま実際のレンダリング結果です。

1. ドキュメントファイルはどこに置く？

すべてのドキュメントファイルは、プロジェクトの src/content/docs/ ディレクトリに保存します:

src/content/docs/
├── index.mdx          # サイトのトップランディングページ
├── canvas/            # コアドキュメントの章（簡体字中国語、デフォルト言語）
│   ├── index.md       # 製品概要
│   ├── deployment.md  # クイックスタート
│   ├── layout.md      # ページレイアウト
│   ├── ...            # その他のドキュメント
└── en/ ja/ ...        # 他の 9 言語の翻訳。ディレクトリ構成は中国語版と完全に対応

ファイル名のルール: 小文字の英字とハイフンを使います（例: quickstart-guide.md）。日本語などのマルチバイト文字やスペースは含めないでください。ファイル名がアクセスパスを決めます: canvas/deployment.md は /canvas/deployment/ に対応します。
拡張子: 普段はプレーンな .md ファイルで十分です。記事の中にインタラクティブなコンポーネント（トップページのカードグリッドなど）を組み込みたい場合は .mdx 形式を使います。
サイドバーへの登録: 新しいファイルを作ったら、astro.config.mjs の sidebar 配列に登録する必要があります。登録しないと左側の目次に表示されません。
多言語の翻訳: 他言語の翻訳は src/content/docs/<言語>/ ディレクトリに置き、サブディレクトリ構成は中国語版と同じにします（例: en/canvas/deployment.md は英語版のクイックスタートに対応）。翻訳がまだ用意できていないページは、自動でフォールバックして中国語が表示されます。

2. 先頭のメタデータ (Frontmatter) の書き方

すべての Markdown ドキュメントの先頭には、3 つのハイフン --- で囲んだ YAML メタデータブロックが必須です:

---
title: クイックスタート (3分で起動)
description: EpoCanvas Docs のローカル環境準備、依存関係のインストールとサーバー起動ガイド。
---

フィールドの説明

フィールド名	必須かどうか	説明
`title`	必須	記事のメインタイトル。ページ上部の大見出しとしてレンダリングされ、ブラウザタブのタイトルにもなります。
`description`	記入を推奨	記事の短い要約。検索結果や SNS 共有カードの説明文に使われます。
`template`	トップページのみ	`splash` を指定すると、サイドバーのないランディングページテンプレートが使われます。

3. 基礎 Markdown フォーマット一覧

このサイトは GFM 拡張入りの標準 Markdown でレンダリングします。次のフォーマットはすべて使えます。まず一覧を見て、その後に書き方とレンダリング結果の対照を順番に確認してください:

フォーマット	簡単な書き方	用途
見出し	`## 小見出し`	章の構成を作り、右側の「目次」に自動収録
段落と改行	空行で段落分け	本文の基本単位
太字 / 斜体 / 打ち消し線	`太字` `斜体` `~~打ち消し線~~`	重要な文字を強調
インラインコード	`コマンド`	コマンド、ファイル名、ショートカットキーを示す
キーボードキー	`<kbd>Ctrl</kbd>`	キーキャップ風のキー表示
箇条書き / 番号付きリスト	`- 項目` / `1. 項目`	並列の内容や手順を列挙
タスクリスト	`- [x] 完了`	チェックボックス付きのチェックリスト
引用ブロック	`> 引用文`	原文の引用や補足の注記
コードブロック	バッククォート 3 つで囲む	複数行コード。ハイライトとコピーボタン付き
テーブル	縦棒で列を区切る	パラメータの対照やデータの羅列
リンク	`[テキスト](URL)`	サイト内の他ページや外部サイトへのジャンプ
画像	`![説明](パス)`	スクリーンショットやアーキテクチャ図の挿入
水平線	`---`	大きな区切りの作成

3.1 見出しのレベル

本文ではレベル 1 見出し（#）を書かないでください。Frontmatter の title がすでにページの大見出しとして自動レンダリングされるため、本文にさらに # を書くとページに大見出しが 2 つできてしまいます。各セクションはレベル 2 見出し（##）から始めます:

## レベル 2 の大見出し（章）

### レベル 3 の小見出し（セクション）

レンダリング結果: いま読んでいるこのページがそのまま実例です。「3. 基礎 Markdown フォーマット一覧」がレベル 2 見出し、このセクション「3.1 見出しのレベル」がレベル 3 見出しで、どちらも右側の「目次」に表示されています。レベル 4 見出し（####）は本文のスタイルとしてのみ扱われ、目次には入らないため、目次に載せたくない細かいセクションに向いています。

3.2 段落と改行

Markdown は空行で段落を分けます。ここは初心者がつまずきやすいポイントです:

これは 1 段落目です。2 つの文の間で Enter を 1 回しか押していないため、
レンダリング後も同じ段落の中にあります。

この行は上の文と空行 1 つを挟んでいるので、レンダリングすると新しい段落に分かれます。

この行の末尾にはバックスラッシュが\
あるため、その次の行は実際に改行されます。

レンダリング結果:

これは 1 段落目です。2 つの文の間で Enter を 1 回しか押していないため、レンダリング後も同じ段落の中にあります。

この行は上の文と空行 1 つを挟んでいるので、レンダリングすると新しい段落に分かれます。

この行の末尾にはバックスラッシュが
あるため、その次の行は実際に改行されます。

ルールのまとめ: Enter 1 回 = 同じ段落内でのソース上の改行になり、段落は分かれない。新しい段落にしたいときは空行を入れます。段落内で強制的に改行したいときは、行末のバックスラッシュか行末のスペース 2 つを使います。

3.3 文字の強調とインラインスタイル

これは**太字**、これは*斜体*、これは***太字斜体***、これは~~打ち消し線~~です。

インラインコードでコマンドやファイル名を示します: `pnpm run dev` を実行して開発サーバーを開きます。

キーボードのキーは HTML タグで示します: <kbd>Ctrl</kbd> + <kbd>K</kbd> でサイト全体検索を開きます。

レンダリング結果:

これは太字、これは斜体、これは太字斜体、これは~~打ち消し線~~です。

インラインコードでコマンドやファイル名を示します: pnpm run dev を実行して開発サーバーを開きます。

キーボードのキーは HTML タグで示します: Ctrl + K でサイト全体検索を開きます。

3.4 リストとタスクリスト

箇条書き。子項目はスペース 2 つでインデントします:
- コア機能その 1
- コア機能その 2
  - その 2 のサブ機能
  - その 2 のもう 1 つのサブ機能

番号付きリスト:
1. ステップ 1: Node.js をインストール
2. ステップ 2: リポジトリをクローン
3. ステップ 3: 開発サーバーを起動

タスクリスト:
- [x] シンタックスハイライト対応
- [x] ワンクリックコピー対応
- [ ] 未完了のタスク

レンダリング結果:

箇条書き。子項目はスペース 2 つでインデントします:

コア機能その 1
コア機能その 2
- その 2 のサブ機能
- その 2 のもう 1 つのサブ機能

番号付きリスト:

ステップ 1: Node.js をインストール
ステップ 2: リポジトリをクローン
ステップ 3: 開発サーバーを起動

タスクリスト:

シンタックスハイライト対応
ワンクリックコピー対応
未完了のタスク

3.5 引用ブロック

> これは引用です。原文の抜粋、背景説明、補足の注記に向いています。
> 複数行続けて 1 つの引用ブロックにまとめられます。

> > 引用の中にさらに引用を入れ子にできます。

> 引用の中にはリストも入れられます:
>
> - 1 番目
> - 2 番目

レンダリング結果:

これは引用です。原文の抜粋、背景説明、補足の注記に向いています。複数行続けて 1 つの引用ブロックにまとめられます。

引用の中にさらに引用を入れ子にできます。

引用の中にはリストも入れられます:

1 番目

2 番目

3.6 コードブロック

バッククォート 3 つで囲み、最初の行のバッククォートの後ろに言語を書くとシンタックスハイライトが有効になります。各コードブロックの右側にはワンクリックコピーボタンが付いています:

```js
export function formatBytes(bytes) {
  return `${(bytes / 1024).toFixed(1)} KB`;
}
```

レンダリング結果:

export function formatBytes(bytes) {
  return `${(bytes / 1024).toFixed(1)} KB`;
}

言語の指定によってハイライト方式が決まります。よく使う js、ts、bash、json、yaml、html、css、python などに対応しています。bash などのターミナル向け言語は、ターミナル風の濃い色の枠でレンダリングされます:

pnpm run build

コードブロックへのファイル名タイトルの表示や指定行ハイライトなどの応用方法は 4.2 節を参照してください。

3.7 テーブル

ヘッダー行の下の横線にコロンを置いて揃え方を制御します（左にコロンで左揃え、両側にコロンで中央揃え、右にコロンで右揃え）:

| コマンド | パラメータ | 説明 |
| :--- | :---: | ---: |
| `astro dev` | `--host` | 左揃えの例 |
| `astro build` | なし | 中央揃えの例 |
| `astro preview` | `--port` | 右揃えの例 |

レンダリング結果:

コマンド	パラメータ	説明
`astro dev`	`--host`	左揃えの例
`astro build`	なし	中央揃えの例
`astro preview`	`--port`	右揃えの例

3.8 リンク

サイト内リンク: [クイックスタート](/canvas/deployment/)

外部リンク: [Astro 公式サイト](https://astro.build)

このページのアンカー: [「テーブル」へジャンプ](#37-テーブル)

自動リンク: <https://github.com/shijianus/epocanvas-docs>

レンダリング結果:

サイト内リンク: クイックスタート

外部リンク: Astro 公式サイト

このページのアンカー: 「テーブル」へジャンプ

自動リンク: https://github.com/shijianus/epocanvas-docs

書き方の約束事:

サイト内リンクは完全なパスを使い、/ で始まり / で終わる形にします（例: /canvas/deployment/）。相対パスは書かないでください。
アンカーは見出しテキストから変換された ID です。日本語の見出しなら、アンカーはそのまま日本語になります（記号は取り除かれ、スペースはハイフンに置き換わります）。ブラウザのアドレスバーの URL をコピーすれば、アンカー付きリンクを取得できます。
リンクテキストは行き先が分かるように書き、「こちらをクリック」のような書き方は避けてください。

3.9 画像と図注

ドキュメントで使う画像アセットは public/images/canvas/ ディレクトリにまとめて置き、参照するときは / で始まる絶対パスを使います:

![クイックスタートページのローカル開発サーバー上での実際のレンダリング結果](/images/canvas/ui-quickstart.png)

*図：画像の直後の行に書いた斜体テキストは図注として表示されます。*

レンダリング結果:

クイックスタートページのローカル開発サーバー上での実際のレンダリング結果

図：クイックスタートページの実際のレンダリング結果。ここでは表示のデモとして載せています。

画像のルール:

アーキテクチャ図・フローチャート: .svg のベクター画像で保存します。スマートフォンや高解像度スクリーンで拡大してもにじみません。このサイトのアーキテクチャ図は public/images/canvas/docs-*.svg にあります。
UI スクリーンショット: 圧縮した .png で保存し、幅は 1440 ピクセル程度で十分です。数十 MB の元画像をそのままアップロードしないでください。
説明文は必須: ![ ] の中のテキストは画像の代替テキストとしてレンダリングされます。画像の内容をきちんと記述し、空のままにしないでください。

画像を挿入したら必ずブラウザで実際のレンダリング結果を確認し、パスが正しく画像が正常に表示されることを確かめてから提出してください。

3.10 水平線

ハイフン 3 つ以上を 1 行に書くと水平線としてレンダリングされ、大きな区切りを作るのに使います:

ここまでで上の話題は終わりです。

---

ここから新しい話題です。

レンダリング結果:

ここまでで上の話題は終わりです。

ここから新しい話題です。

4. 拡張フォーマット：このサイトの拡張構文

以下のフォーマットは、標準 Markdown に加えてこのサイトが追加でサポートしている拡張構文で、レンダリングエンジン（Starlight の吹き出しと Expressive Code）が提供しています。

4.1 4 種類のカラー吹き出し

吹き出しはコロン 3 つの構文で書きます。:::タイプ で始め、単独の行 ::: で終わります。タイプは 4 種類あり、色とアイコンがそれぞれ異なります:

タイプの後ろに角括弧を付けるとタイトルをカスタマイズできます:

:::tip[インストールを速く]
pnpm で依存関係をインストールすると npm よりはるかに速いです:

```bash
npm install -g pnpm
```
:::

レンダリング結果:

吹き出しの中ではリスト、コードブロック、テーブルなど、どの整形要素でも引き続き使えます。他の例は吹き出し・コードブロック・図表の例を参照してください。

4.2 コードブロックのファイル名タイトルと行ハイライト

コードフェンスの最初の行に title="ファイルパス" と書くとタイトルバーが表示され、{行番号} で重要な行をハイライトできます。複数の行番号はカンマで区切ります:

```typescript title="src/config/site.ts" {2,4}
export const siteConfig = {
  name: 'EpoCanvas Docs', // ← ハイライト行
  version: '1.0.0',
  locale: 'zh-CN',        // ← ハイライト行
};
```

レンダリング結果:

export const siteConfig = {
  name: 'EpoCanvas Docs',
  version: '1.0.0',
  locale: 'zh-CN',
};

4.3 diff による変更差分の表示

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',
});

4.4 脚注

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

サイト全体検索のインデックスは、ビルド時に Pagefind が生成します[^pf]。

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

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

4.5 非対応・間違いやすい書き方の早見表

次の書き方は他のプラットフォームではよく見かけますが、このサイトでは効かなかったり、期待どおりに表示されなかったりします。ドキュメントを書くときは避けてください:

間違いやすい書き方	実際の挙動	正しい代替方法
```mermaid フェンス	普通のコードブロックとしてソースが表示され、図は生成されない	mermaid.live で SVG を書き出し、画像として挿入する
`> [!NOTE]` の GitHub アラート構文	普通の引用ブロックとしてレンダリングされる	`:::note` に書き換える
`:::warning` / `:::important`	吹き出しのスタイルが付かず、黙って普通の段落になる	`:::caution` に書き換える
本文にレベル 1 見出し `#` を書く	ページに大見出しが 2 つできる	`#` を削除し、本文は `##` から始める
Enter 1 回で改行しようとする	2 行が 1 行につながる	空行で段落を分けるか、行末にバックスラッシュを付ける

5. さらに進む

Markdown がファイルからページまでどうレンダリングされるか、その完全なパイプラインと約束事を知りたい方は、レンダリングルールの詳細 をご覧ください。
吹き出し、コードブロック、脚注などの構文を「生きたサンプルページ」でまとめて見たい方は、吹き出し・コードブロック・図表の例 をご覧ください。

これがこのページの下部にレンダリングされる脚注の本体です。脚注の内容は本文中のどこに書いても、ページの最下部にまとめて表示されます。 ↩