コンポーネント#

Ovellum は小さなコンテンツコンポーネント群 — コールアウト・ステップ・カード・タブ — を ::: ディレクティブ構文で提供します。これらは CommonMark のディレクティブ というプレーンな Markdown であり、JSX や独自フォーマットではありません。だからソースは ポータブルなままで、出力はただの HTML + CSS です。以下はすべてテーマでスタイルされ、 light でも dark でも動作します。

コールアウト#

一節をノート・ヒント・警告として強調します。::: とタイプでフェンスブロックを開きます:

:::note
Ovellum はレンダリング前にすべての Markdown をサニタイズします。
:::

:::warning{title="注意"}
ドキュメント化されたシンボルをリネームすると、その手書きの文章は孤立します。
:::

タイプ: note、tip、important、warning、caution。ラベルは既定でタイプ名に なります。{title="…"} で上書きできます。

ステップ#

番号付きの手順です。外側の ::::steps が項目ごとの :::step を包みます:

::::steps
:::step{title="インストール"}
`npm install -D ovellum`
:::

:::step{title="初期化"}
`npx ovellum init` を実行し、プロンプトに答えます。
:::
::::

番号は自動で付きます。{title="…"} は任意です。

カード#

レスポンシブなカードのグリッドです。href を加えるとカード全体がリンクになります:

::::cards
:::card{title="手動モード" href="/ja/docs/guides/manual-mode/"}
Markdown から静的サイトを構築します。
:::

:::card{title="ハイブリッドモード" href="/ja/docs/guides/hybrid-mode/"}
ソースから生成し、文章を残します。
:::
::::

href のないカードは、（クリックできない）通常のカードとしてレンダリングされます。

タブ#

選択肢を 1 か所で見せます — インストールコマンド、言語のバリアント、OS ごとの手順など。 外側の ::::tabs がパネルごとの :::tab を包み、{label="…"} がタブ名になります:

::::tabs
:::tab{label="npm"}
`npm install -D ovellum`
:::

:::tab{label="pnpm"}
`pnpm add -D ovellum`
:::
::::

既定では最初のタブが表示されます。タブリストはキーボード（矢印キー）で操作できます。 JavaScript を無効にしている場合は、すべてのパネルが完全に表示されるので、読者や クローラーからコンテンツが隠れることはありません。

コードグループ#

タブ付きのコードブロック — よくある「npm / pnpm / yarn」の切り替えです。フェンスされた ブロックを :::code-group で包みます。各タブはフェンスの言語、または info 文字列の title="…" でラベル付けされます:

:::code-group
```bash
npm install -D ovellum
```

```bash title="pnpm"
pnpm add -D ovellum
```
:::

:::code-group はブロックを包みますが、単一の :::（:::: ではない）を使います — その子はディレクティブではなくコードフェンスなので、曖昧さを解消するネストがありません。

図（Mermaid）#

```mermaid コードブロックは Mermaid の図として レンダリングされます:

```mermaid
graph LR
  Source --> Parser --> Generator --> Merger --> Docs
```

Mermaid のランタイムは遅延読み込みされ、図を含むページでのみ読み込まれます — そのため、デフォルトのサイト（および図のない全ページ）は余分な JavaScript を一切 出荷しません。ピン留めされた CDN から読み込まれ、ページがそこに到達できない場合は、 図のソースが読みやすいフォールバックとして表示されたままになります。第三者への リクエストを避けるには、ランタイムをセルフホストして site.mermaid.url をそこに向けるか、 site.mermaid.enabled: false で図を完全に無効にします。

.mdx ファイルを使う#

Ovellum は .mdx ファイルを Markdown として扱います — .md と同じように拾われ、 ルーティングされ、レンダリングされます。JSX の評価はありません。.mdx ファイルは 拡張子が違うだけの Markdown ファイルなので、上記のすべてのディレクティブは動作しますが、 JSX の <Component /> は実行されません。エディタやツールが .mdx を期待する場合に 使ってください。プレーンな .md とそれ以外は同じです。

ネストのルール#

他のディレクティブを含むコンポーネント（ステップ・カード・タブ）は、その子要素より コロンを 1 つ多く使う必要があります — :::step を囲む ::::steps のように。これにより パーサーが外側のブロックと内側のブロックを区別できます。コールアウトやコードグループは 通常の Markdown / コードを持つだけなので、::: を使います。