Color mode

MDX

Riebeckiteに信頼済みMDXコンテンツを追加します。MDXページではMarkdown、JSX、JavaScript式、ESM import/export、ローカルのHono JSXコンポーネントを利用できます。

English

インストール

sh
npm install @riebeckite/plugin-mdx

設定

ts
import { defineConfig } from "@riebeckite/core";
import mdx from "@riebeckite/plugin-mdx";
 
export default defineConfig({
  plugins: [mdx({ trusted: true })],
});

trusted: trueは必須です。MDXはサーバー描画と静的生成中に著者のJavaScriptを実行するため、信頼できるコンテンツだけで有効にしてください。指定しない場合、設定時にエラーになります。

MDXを書く

設定したcontentディレクトリに.mdxファイルを配置します。frontmatterと公開メタデータはMarkdownファイルと同じように扱われます。

mdx
---
title: Release notes
publish: true
---
 
export const version = "1.0";
import { Badge } from "./badge";
 
# Version {version}
 
<Badge>Stable</Badge>

MDXモジュールと相対importはViteが解決します。JSXは開発時のSSRと本番SSGでHono JSXランタイムにより描画されます。

静的な相対importは増分ビルドで追跡されます。import先のローカルファイルを変更すると、そのMDXページが再ビルドされます。.mdxファイルの追加・削除時には開発サーバーを再読み込みします。

検索、抜粋、読了時間、見出しはMDXソースの静的なテキスト投影から生成されます。投影はMDXを構文木として解析し、見出し・段落・リスト・リンクなどのMarkdown構造を保ち、frontmatter、import/export宣言、JavaScript式、JSX属性を除外します。JSXの子要素にある静的なMarkdownは保持します。これらの派生出力ではコンポーネントを実行しないため、コンポーネントが描画時に生成するテキストは含まれません。不正なMDXは部分的な投影を返さず、ビルドを失敗させます。

コンポーネント

すべてのMDXページで使うコンポーネントはcomponentsで渡します。

ts
plugins: [
  mdx({
    trusted: true,
    components: { Callout },
  }),
]

ページやページ群だけで使うコンポーネントには、ローカルの相対importを使用してください。

Plugin APIのコンポーネントレジストリに登録したプラグインコンポーネントは、すべてのMDXページでも利用できます。Markdownフェンスと同じpropsをJSXとして渡します。

mdx
<CodeCopy text="npm install" label="Copy command" copiedLabel="Copied" />

MDXは別実装のレジストリではなく、Markdownと同じレジストリを受け取ります。mdx({ components })で同じ名前のコンポーネントを渡した場合、そのMDXページではプラグインコンポーネントより優先されます。対話的なプラグインコンポーネントは、そのページが描画したときだけ読み込まれてハイドレートされます。

Markdownとの共存

Markdownの既存動作は変わりません。同じslugになる.mdと.mdxは作成しないでください。Riebeckiteはどちらかを任意に選ばず、衝突として報告します。

プレビュー

パッケージのプレビューはMarkdownのみを描画します。MDXページは、ViteでMDXとそのimportを解決するサイトの開発サーバーでプレビューしてください。

Powered by Riebeckite

Local Graph

Nearby Notes

This neighbourhood is large, so the graph stops after 320 nodes.