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 是供管道或 Agent 使用的命令：结果格式为 {lib} {path} - {title}，与 MCP 服务发布索引时采用的格式一致；未找到结果时以状态码 1 退出。 --in drei 可将搜索范围限定为一个库，--in drei/performances/instances 则可限定为某个页面中匹配的行。

这两个命令都会读取各个库已发布的 llms-full.txt，并将文件缓存一小时，缓存位置为 ~/.cache/pmndrs-docs——使用 --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-*……每个选项都会回退到与其对应的环境变量；这些变量与配置文档中介绍的相同。

若要在 MDX 中使用仓库的 React 组件和共享数据，请在当前工作目录中添加 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

复制页面、以 Markdown 查看（/<page>.md）和 llms-full.txt 使用相同的文档渲染器。MDX 表达式会根据 scope 求值，包括 Markdown 表格、JSX 属性和命令中的值。标题、表格、列表、链接、图片和代码都会序列化为 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 导出覆盖内置组件和已配置组件。这些替代组件不得依赖客户端组件，包括嵌套的客户端组件。导出内容描述的是构建时编写的内容或初始状态；不会记录读者选择的选项卡、编辑过的 Playground 或主题偏好。未解析的表达式和渲染错误会导致导出失败，并显示文档路径，而不会返回原始 MDX。

发布

每次推送到 main 都会通过 ci.yml 重新部署 docs.pmnd.rs——无需 changeset。

只有在下游使用方固定到 pmndrs/docs/.github/workflows/build.yml@v4 或 @pmndrs/docs@4，且需要获取此更改时，才添加一个（pnpm changeset）。这会更新 package.json、发布到 npm，并标记 vX.Y.Z 和 vX——因此 @v4 会解析到最新版本。

简而言之——仅修改网站：跳过。任何使用方可见的更改（工作流、构建行为、模板）：添加一个。

测试

视觉测试在云端通过 chromatic-playwright.yml 和 chromatic-storybook.yml 执行。

• pnpm run lgtm — 快速检查：类型、lint、注册表验证、单元测试。
• pnpm run LGTM — 完整检查：CI 运行 lgtm 和 Playwright。

Playwright 会检查自定义组件示例是否 渲染已配置的数据并响应交互。

Playwright 在本地生成的截图是临时文件——基线由 Chromatic 保存。

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