pmndrs docs

docs/getting-started/introduction.mdx

使い方

読む

$ npx @pmndrs/docs                                 # the reader: every library, every page
$ npx @pmndrs/docs drei                            # straight into one
$ npx @pmndrs/docs drei/performances/instances     # straight to a page
$ npx @pmndrs/docs search instanced mesh           # one result per line, on stdout

↑↓ は、ページ一覧またはページ本文のうち、フォーカスがあるペインを操作します。⏎ または ⇥ でフォーカスを移し、esc または ⇥ で戻します。点灯した枠線がフォーカス位置を示します。ホイールは、フォーカスの有無にかかわらず、ポインターが指しているペインをスクロールします。←→ でライブラリを切り替え、b でサイドバーを折りたたみ、/ で全ライブラリを一度に検索し、o でページをブラウザーで開き、q で終了します。ページ内のリンクは、ターミナルが OSC 8 ハイパーリンクに対応していればクリックできます。対応するターミナルは、iTerm2、Ghostty、WezTerm、Kitty、Windows Terminal です。

search は、パイプやエージェントから利用できるコマンドです。検索結果は {lib} {path} - {title} の形式で出力されます。これはMCP サーバーがインデックスを公開する形式と同じです。結果が見つからない場合は、終了コード 1 を返します。--in drei でライブラリを1つに絞り込み、--in drei/performances/instances で1つのページ内の該当行に絞り込めます。

各ライブラリの公開済み llms-full.txt を読み込み、~/.cache/pmndrs-docs に1時間キャッシュします。--refresh を指定すると再取得します。ターミナル外では、ページの内容が標準出力に書き込まれるため、npx @pmndrs/docs drei/performances/instances | glow のように実行できます。

ビルド

$ cat foo.mdx | npx @pmndrs/docs@latest build               # one HTML fragment, on stdout
$ npx @pmndrs/docs@latest build docs out                    # one .html per .mdx, assets alongside
$ npx @pmndrs/docs@latest build docs out --format website   # the whole website, statically exported

どちらの形式も、同じ Next.js ビルドと静的エクスポートを使用します。--format fragment（デフォルト）は、エクスポートからコンパイル済みの MDX を抽出します。レイアウト、スタイルシート、スクリプトは含まれません。Mermaid の図はコードフェンス付きブロックのまま表示され、Sandpack はエディターなしでコードを表示します。

ドキュメントのレンダリングでは、単一ファイルや標準入力の場合も含め、next build が実行されます。これらの入力の場合、標準出力には HTML のみが含まれ、ビルドログは標準エラー出力に送られます。esbuild は公開用の CLI のパッケージ化にのみ使用され、利用側のコンポーネントの読み込みやドキュメントのレンダリングには使用されません。

build --help では、ウェブサイトのすべてのオプション（--libname、--base-path、--icon、--theme-* など）を確認できます。各オプションは、対応する環境変数の値をデフォルトとして使用します。これらの環境変数は、設定に記載されています。

リポジトリの React コンポーネントと共有データを MDX で使うには、現在の作業ディレクトリに docs.config.ts を追加します。別の場所を指定するには、--config path/to/config.ts または DOCS_CONFIG を使用します。フラグが優先されます。 設定、ウェブサイトのレンダリング、HTML フラグメントの動作については、カスタムコンポーネントとデータを参照してください。

$ curl -sL https://raw.githubusercontent.com/pmndrs/docs/refs/heads/main/preview.sh | \
  MDX="docs" \
  ICON="🥑" \
  sh

Copy Page、Markdown として表示（/<page>.md）、および llms-full.txt は同じドキュメントレンダラーを使用します。MDX の式は、Markdown テーブル、JSX 属性、コマンド内の値を含め、scope に基づいて評価されます。見出し、テーブル、リスト、リンク、画像、コードは Markdown としてシリアライズされます。書式は正規化されますが、MDX ファイルが書き換えられることはありません。インラインコードとフェンス付きの例は、中括弧や JSX も含め、そのまま保持されます。

組み込みコンポーネントには静的な表現が用意されています。タブにはすべてのパネルが含まれ、コードブロックには記述されたコマンドが含まれ、Mermaid では図のソースが保持され、テーマプリセットでは宣言された値が表示されます。カラーのプレビューには、ブラウザーのスタイルを計算せず、役割または CSS 値が表示されます。Sandpack とライブ埋め込みには静的な通知または遷移先が表示され、コントリビューターと支援者のリストにはリンクが表示されます。

カスタムのサーバーレンダリング可能なコンポーネントは、非同期コンポーネントを含め、レンダリング済みのコンテンツを使用します。Next が不透明な参照として公開するクライアントコンポーネントには、通知と記述された子要素が使用されます。ブラウザー API、プロバイダー、または特定のインタラクティブな状態を必要とするコンポーネントでは、markdownComponents にサーバーレンダリング可能な代替を指定してください。

import type { DocsConfig } from '@pmndrs/docs/src/config'
import { Example } from './docs/authoring/Example'
import example from './docs/authoring/Example.json'

export default {
  components: { Example },
  scope: { example },
  markdownComponents: {
    Example: ({ initialCount }: { initialCount: number }) => `Count: ${initialCount}`,
  },
} satisfies DocsConfig

markdownComponents は、Markdown エクスポートに限り、組み込みコンポーネントと設定済みコンポーネントの両方を上書きします。ネストされたクライアントコンポーネントを含め、これらの代替にクライアント側の依存関係が含まれないようにしてください。エクスポートにはビルド時点で記述された状態または初期状態が反映されます。読者が選択したタブ、編集したプレイグラウンド、テーマ設定は記録されません。未解決の式やレンダリングエラーが発生した場合、生の MDX を返すのではなく、ドキュメントのパスとともにエクスポートが失敗します。

リリース

main へのプッシュのたびに、ci.yml を通じて docs.pmnd.rs が再デプロイされます。そのため、changeset は必要ありません。

下流の利用者が pmndrs/docs/.github/workflows/build.yml@v4 または @pmndrs/docs@4 を固定していて、その変更を取り込む必要がある場合に限り、pnpm changeset を実行して changeset を追加してください。これにより package.json のバージョンが更新され、npm に公開され、vX.Y.Z と vX のタグが付けられます。そのため、@v4 は最新のバージョンを参照します。

要するに、サイトのみの小さな変更なら不要です。利用者に影響する変更（ワークフロー、ビルド動作、テンプレート）なら追加してください。

テスト

ビジュアルテストは、クラウド上で chromatic-playwright.yml と chromatic-storybook.yml を通じて実施されます。

• pnpm run lgtm — 高速ゲートです。型、リント、レジストリの検証、ユニットテストを実行します。
• pnpm run LGTM — CI で実行されるすべてのゲートです。lgtm と Playwright を実行します。

Playwright は、カスタムコンポーネントの例が設定されたデータをレンダリングし、操作に応答することを確認します。

Playwright がローカルに書き出すスクリーンショットは使い捨てです。ベースラインは Chromatic が保持します。

$ pnpm run LGTM
$ npx chromatic --playwright --project-token $CHROMATIC_PROJECT_TOKEN