blocks

ブロック

Markdown より豊かな内容は、以下のいずれかのブロックとしてページに追加します。この一覧はフレームワークに属しており、プロジェクトから追加することはできません。ここにないものを使いたい場合は、図か本文にする必要があります。新しい className を考案しても解決にはなりません。「スタイリング」を参照してください。

コールアウト

:::note、:::tip、:::info、:::warning（:::warn、:::caution）、:::danger、および独自の :::source です。インポート不要のプレーンな Markdown です。

:::warning[Required]

Careful, and *emphatic*.

:::

角括弧内のラベルは省略可能です。省略すると、コールアウト自身の名前が表示されます。:::source はブックマーク付きのグレーのコールアウトで、本文中のパターンの出典（書籍、著者、年）を示します。ページ内エディターでも同じコールアウトが表示されるため、執筆中も見た目は変わりません。

<VideoEmbed url="..." />

16:9 で埋め込まれる YouTube 動画です。グローバルに登録されているため、インポートも特別な手順も不要です。

<VideoEmbed url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" />

<LinkEmbed url="..." />

リンクをカードとして表示します。ページのタイトル、説明の一部、サイト名とアイコン、右側のプレビュー画像が表示されます。こちらもグローバルです。リンクが段落の主題になっている場合や、開く価値のあるツール、リポジトリ、参考資料を紹介する場合に使います。文中のリンクには、引き続き Markdown リンクを使ってください。

必須なのは url だけです。ほかのプロパティはページ自体で宣言される og:title、og:description、og:site_name、og:image、およびアイコンで、誰かが空行にリンクを貼り付けたときにスタジオが一度だけ読み取ります。手作業で記述する場合は、値を考案せず、ページ自身のタグからコピーしてください。読み取れないものは省略してください。url だけのカードでは、アドレスがタイトルとして、ホスト名がサイト名として表示されます。読み込みを確認していない画像を image に指定しないでください。

<LinkEmbed
  url="https://fumadocs.dev/"
  title="Fumadocs"
  description="The React.js documentation framework."
  site="Fumadocs"
  image="https://www.fumadocs.dev/banner.png"
  favicon="https://www.fumadocs.dev/icon.png"
/>

<FileAttachment ... />

ページにコミットされ、ダウンロードカードとして提供されるファイルです。こちらもグローバルです。必須なのは href だけです。size はバイト数、uploadedAt は YYYY-MM-DD 形式、note は最大 200 文字です。

<FileAttachment
  href="/files/docs/9f2c1a8b.zip"
  name="latency-harness.zip"
  size="248193"
  uploadedAt="2026-08-22"
  note="The harness behind the Q3 p99 numbers. Run make bench."
/>

<DocCardList />

各セクションのランディングページの末尾に表示される、子ページのグリッドです。インポートは不要です。ページがツリー内の現在の位置に結び付けます。見出しは自動で表示されます。サイトのルートでは「Sections」、セクション内では「In this section」となるため、その上に ## を置かないでください。別の文言にする場合は title="…" を渡します。現在のページは一覧に表示されず、各カードにはリンク先の description が表示されます。そのため、すべてのページのフロントマターに description を記述し、すべてのセクションの meta.json にも記述してください。

表

GFM の Markdown 表だけを使用します。table 要素は横スクロール可能なボックスに配置され、本文のタイポグラフィによってヘッダー、罫線、セルの余白が整えられるため、幅の広い表はページを広げずにスクロールできます。区切り行のコロンで列の配置を設定できます（:---: は中央揃え、---: は右揃えです。数値の列には右揃えが適しています）。セル内ではインライン Markdown が使えるため、リンク、code、太字を記述できます。

値を調べるよりも数値同士を比較したい場合は、表ではなくグラフを使ってください。

画像

ファイルとして同梱されているスクリーンショットや図は、通常の Markdown です。枠、キャップ、キャプションはテーマによって表示されるため、ラッパーを入力する必要はありません。

![The blocks of a page, with one being written in](/img/docs/editor.png "A grip in the left margin moves a block; the bar at the foot commits the page.")

• 最初の括弧内は alt です。画像が見えない人に伝える必要がある内容を記します。「X のスクリーンショット」のような表現ではなく、画像の内容を説明する文にしてください。
• 本文ですでに説明されている内容しか伝えない画像は装飾用です。![](…) と記述すると、そのようにマークされ、スクリーンリーダーでは読み上げられません。
• パスの後ろにある引用符付きの文字列は省略可能で、キャプションになります。
• 画像は、テキストの幅まで元のサイズで表示され、画面が広い場合は少し幅広くなります。また、--jd-shot-height より高くなることはないため、大きな書き出し画像でウィンドウ全体が埋まることはありません。クリックすると暗い背景の上に元のファイルが開き、ポインターを合わせると、元のファイルを拡大、コピー、ダウンロードするツールバーが表示されます。スクリーンショットは、読みやすいサイズで書き出してください。小さい画像が列いっぱいに引き伸ばされることはありません。
• ファイルはプロジェクトの docs/_uploads/img/docs/ に置きます。ページ内エディターからアップロードすると、ここに保存されます。
• SVG は 1 つのファイルからカラーモードに従います。ダークモードでは、ページが #dark を使って SVG を再描画するため、svg:target の下に設定したパレットがダークモード用になります。パレットが 1 つの SVG は、どちらのモードでも同じように表示されます。
• ![The team's logo]() のようにパスのない画像は、ダウンロードできなかったことを示すプレースホルダーを表示します。別のサイトから貼り付けたページでは、ブラウザーが取得を許可されていない画像ごとにプレースホルダーが表示されます。別のサイトへのリンクではなく、実際のファイルに置き換えてください。パスを開いても画像がない場合も、読み込めなかったことを示す同じプレースホルダーが表示されます。

幅

表や画像は、記事の列より広く表示できます。:::wide または :::full の中に単独で配置してください。通常の Markdown として記述し、インポートは不要です。

:::wide

| Product | Purpose | Business capabilities | Key systems |
| --- | --- | --- | --- |
| Field service | Customers, assets and service delivery in one platform | Case management, work orders | A CRM |

:::

• ラッパーを使わない場合は列幅になり、ほとんどの場合に適しています。:::wide は、列が窮屈な表や、細部が重要なスクリーンショットを少し広く表示します。:::full はページの端まで広がり、ページの中心となる概要に使います。
• どちらも列の中央に配置され、列より狭くなることはありません。そのため、小さい画面では通常のブロックとして表示されます。
• 幅を広げた画像はブロック全体に広がり、スクリーンショットの高さ制限もなくなります。そのため、ブロック全体に収まる大きさで書き出した画像だけを幅広く表示してください。
• 幅を広げられるのは表または単独の画像だけで、ページ自体のブロックとして配置されている場合に限ります。それ以外のものを囲んだ場合や、コールアウト、タブなどのブロック内では、ラッパーは無視され、コンテンツは列幅で表示されます。
• ページ内エディターでは、ブロックのグリップメニューに Width があり、幅を広げられるブロックの側面にあるグリップをドラッグすると、3 段階の幅を切り替えられます。

```mermaid フェンス

コードで記述したシーケンス図、フロー図、状態遷移図で、ブラウザー上で Mermaid によってレンダリングされます。通常の Markdown として記述し、インポートは不要です。ページ内では画像のように縮小されて列幅に収まり、クリックすると全画面表示になります。トラックパッドでパンし、ピンチ操作でズームできます。長いフローは縦長の図 1 つにまとめず、自然な章の区切りで分割し、本文の間に複数のフェンスとして配置してください。

ページ内エディターでは、フェンスはソースではなく図として表示されます。ノードをクリックして名前や形を変更し、ノード間をドラッグしてエッジを描画できます。編集内容はすべて、フェンス内の Mermaid ソースに書き戻されます。/diagram を入力するとフローチャートのひな形が挿入され、空のフェンスではフローチャート、シーケンス図、状態遷移図から選んで作成を始められます。

コードフェンス

Shiki はすべてのコードフェンスをハイライト表示し、言語の後に続くメタ文字列もブロックの一部として扱います。

```ts title="lib/cart.ts" lineNumbers
```

title="…" はファイル名のヘッダーを表示し、lineNumbers は行番号を付けます。また、コメント注釈を使うと、行をその場でマークできます。差分表示には // [!code highlight]、// [!code ++]、// [!code --]、ほかの部分を薄く表示するには // [!code focus]、トークンを強調するには // [!code word:parseDocument] を使います。隣り合う2つのコードフェンスに tab="Server" を付けると、1つのタブ付きブロックになり、登録は不要です。ページ内エディターはメタ文字列を記述どおりに保持し、そのまま出力するため、タイトル付きのコードフェンスを開くとキャプションバーにファイル名が表示され、保存時にも同じヘッダーとタブが維持されます。入力したコードフェンスは、ビルド済みページと同じ Shiki と同じテーマを使って入力中にハイライト表示されます。また、コードフェンスにカーソルを合わせると、フレームの隅に言語名を示すドロップダウンが表示されます。

jd-fig 図

図のスキルで描画する、インライン SVG または HTML の図です。図をクリックすると、Mermaid の図と同じ全画面ステージで開き、パン、ズーム、ミニマップを利用できます。図に何かを追加する必要はありません。図のスキルに用意されているのは、段落の内容に応じて表示する図の形式を決めるルーティングテーブル、形式ごとの references/forms/ にあるレイアウトのリファレンス、すべての矢印に適用されるコネクターのルール、そして図の種類ごとに読み込む Claude Code 組み込みスキルの一覧（仕組みには artifact-diagramming、グラフには dataviz）です。利用できるほかのビジュアルスキルも自由に使えます。

<Chart />

ブランドカラーの --chart-1 から --chart-5 を使い、Recharts 上で shadcn のチャートコンポーネントが描画する、数値データの棒グラフ、折れ線グラフ、面グラフ、円グラフ、またはレーダーチャートです。ツールチップと凡例も表示されます。x は各行のラベルに使うフィールドを指定し、series はプロットする各フィールドを色の順にラベルへ対応付けます。stacked、horizontal、unit、caption は任意です。チャートスキルでは、どの種類のチャートがどの問いに答えるかが説明されています。ページ内エディターでは、移動や削除ができるブロックですが、編集はソース内で行います。

<Chart type="bar" x="month" data={[{ month: "Apr", saves: 186 }, { month: "May", saves: 305 }]} series={{ saves: "Studio saves" }} />

レイアウトコンポーネント

フレームワークによって5つのファミリーのレイアウトコンポーネントが登録されるため、ページではインポートせずに使用できます。それ以外のタグは何も描画されません。

• <Tabs items={['npm','bun']}><Tab value="npm">…</Tab></Tabs>。1つの手順を複数の環境向けに示せるため、ほとんど同じ内容のセクションを3つ並べずに済みます。
• <Steps><Step>…</Step></Steps>。左側に縦線を配した番号付きの手順です。各ステップにコードブロックがある場合は、1. 2. 3. よりも適しています。
• <Files><Folder name="docs"><File name="index.mdx" /></Folder></Files>。ディレクトリツリーを表示します。そうでなければ、フェンス内にASCIIアートで描くことになります。
• <Cards><Card title="ADR 0015" href="/decision-records/0015-hosted-studio-and-static-publishing" /></Cards>。厳選したリンクのセットです。すべての子ページを表示するには、<DocCardList /> を使います。
• <Accordions><Accordion title="…">…</Accordion></Accordions>。多くの読者が読み飛ばす回答を折りたたんで表示します。type="multiple" を使うと複数の項目を同時に開いたままにできます。defaultValue は最初に開く項目のタイトルで、パネルに id を指定すると、コピーボタンと、そのパネルを開くアンカーが追加されます。

他のドキュメント用フレームワークに含まれるコンポーネントの一部は、意図的に含めていません。

コンポーネント	含めない理由
Callout	:::note などはマークダウンでも同じことができ、ページ内エディターでも描画できます。
ImageZoom	マークダウンの  は、枠線、キャプション、ズームにすでに対応した DocImage として描画されます。
CodeBlockTabs	tab="…" を指定した2つのコードフェンスを隣接させれば、マークダウンで同じことができます。
DynamicCodeBlock	ファイルに含まれていないコードを、実行時にハイライト表示します。ここにあるコードフェンスはすべてファイルに含まれています。
Banner、GitHubInfo	ページコンテンツではなく、サイトのクロームです。
InlineTOC	誰も手作業では書けない TOCItemType[] 配列を受け取ります。ページにはいずれにせよサイドバーの目次が表示されます。
TypeTable、AutoTypeTable	型と必須かどうかを示す列を含むマークダウンの表で、同じ内容を表せます。
GraphView	この規模のサイトでは、サイドバーから移動できます。

スタイリング

サイトのタイポグラフィにはフレームワーク独自の設定が使われます。見出しのサイズ、行の長さ、ブロック間の間隔、表やコードの枠線などです。ページ側でこれらを再スタイルすることはありません。docs/ 以下の記事本文は、ひたすら通常のマークダウンです。

プロジェクトの外観は、ページごとではなく、.jotdown/config.json の theme という1か所で管理します。モードごとに一度指定する Shadcn のトークン名である background、foreground、primary、destructive、chart-1 から chart-5 が、すべてのブロック、図、チャートに色を設定するため、ページ側で意識せずとも両方のカラーモードに反映されます。sections ではトークンを指定してセクションの色を設定し、radius では角を丸め、fonts では sans、serif、mono のフォントを指定します。

ドキュメント内のclassName

文章を強調する必要がある場合、マークダウンにはすでにその機能があります。引用（>）、太字、注釈（引用には :::note、警告には :::warning、出典には :::source）を使ってください。

docs/ で許可されている className は1つだけです。図形スキルで描画したインラインSVGまたはHTMLの図に付ける jd-fig です。これは文章ではなく、画像です。

それ以外は、人間には記述できず、ページ内エディターにも見えず、リポジトリに消えない汚れを残します。文章に独自の className を作らないでください。また、ドキュメント内でTailwindユーティリティを使わないでください。コンパイルされるのはフレームワーク独自のコンポーネントが使うクラスだけで、それ以外はスタイルのない要素として描画されます。

基本ルール

• ページに色やフォントをハードコードしないでください。図は--jd-fig-*トークンで描画し、チャートはブランドのチャートカラーを使います。唯一の例外は、独自のパレットを持つSVGファイルのエディトリアルイラストです。
• 記事のスタイルを変更しないでください。見出し、段落、表の表示がおかしくても、そのままにしてフレームワークのメンテナーに伝えてください。
• ユーザーがMermaidを指定しない限り、図はfigureスキルで描画するインラインSVG／HTMLの図にします。Mermaidは、複雑で高度に技術的な、決定論的なリファレンス図に使います。それ以外は、認知負荷を下げることを目指した説明図にします。

実際によくあるケースについて、同じルールを表にまとめます。

目的	してはいけないこと	すること
文章を強調する	proseを囲む<div className="…">	>ブロック引用、太字、または:::note／:::warningコールアウトを使う
色付きまたは枠付きの段落	ドキュメントに新しいクラスやTailwindユーティリティを追加する	プレーンなMarkdownを使う。画像の場合はjd-fig図を使う
プロジェクトに色を設定する	ページに16進数の値を記述する	.jotdown/config.jsonのthemeにshadcnトークンを設定する
プロジェクトに書体を設定する	ページに<style>を記述する	テーマのfontsに書体を設定する
公式リファレンスドキュメントにプロセス図や状態図を入れる	手描きの図を使う	```mermaidフェンスを使う
文章の横にイラストを配置する	```mermaidフェンスを使う	figureスキルで描画したjd-fig図を使う
雑誌のように記事の冒頭を飾る画像を配置する	ボックスの名前を変えただけの図や、ページに貼り付けたSVGを使う	editorial-illustrationスキルのSVGファイルを使い、:::wide内にMarkdown画像として表示する
数値、傾向、比較を示す	ボックスと矢印、または数値を並べた段落を使う	chartスキルに従って<Chart />ブロックを使う