pmndrs docs

docs/getting-started/introduction.mdx

Uso

Lectura

$ 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

↑↓ controla el panel que tiene el foco — la lista de páginas, o la página en sí. ⏎ o ⇥ transfiere el foco, esc o ⇥ lo devuelve, y el borde iluminado indica dónde está — la rueda mueve el panel al que apunta, tenga foco o no. ←→ cambia de biblioteca, b pliega la barra lateral, / busca en todas las bibliotecas a la vez, o abre la página en un navegador, q sale. Los enlaces dentro de una página son clicables siempre que el terminal respete los hiperenlaces OSC 8 — iTerm2, Ghostty, WezTerm, Kitty, Windows Terminal.

search es lo que puede usar un agente o un script: los resultados se leen en {lib} {path} - {title}, la forma en que el servidor MCP publica su índice, y si no se encuentra nada, sale con código 1. --in drei reduce a una sola biblioteca, --in drei/performances/instances a las líneas coincidentes de una página.

Ambos leen el llms-full.txt publicado de cada biblioteca, almacenado en caché durante una hora en ~/.cache/pmndrs-docs — --refresh vuelve a buscar. Fuera de un terminal, un destino de página se escribe en la salida estándar, por lo que npx @pmndrs/docs drei/performances/instances | glow funciona.

Compilación

$ 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

--format fragment (el predeterminado) solo necesita node — sin next build, sin bundler. Un fragmento es el MDX compilado y nada más: sin diseño, sin hoja de estilos, sin script. Los diagramas Mermaid permanecen como bloques delimitados, y Sandpack muestra su código sin el editor.

build --help enumera todas las opciones del sitio web — --libname, --base-path, --icon, --theme-*… Cada una recurre a la variable de entorno a la que está mapeada, las mismas que configuración documenta.

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

Publicación

Cada push a main vuelve a implementar docs.pmnd.rs mediante ci.yml — no se necesita changeset para eso.

Agrega uno (pnpm changeset) solo cuando los consumidores posteriores que fijan pmndrs/docs/.github/workflows/build.yml@v4 o @pmndrs/docs@4 deban recibir el cambio. Esto incrementa package.json, publica en npm y etiqueta vX.Y.Z + vX — por lo que @v4 se resuelve a la versión más reciente.

En resumen — solo cambio del sitio: omítelo. Cualquier cosa que los consumidores vean (flujo de trabajo, comportamiento de compilación, plantillas): agrega uno.

Pruebas

Las pruebas visuales se realizan en la nube, mediante chromatic.yml.

$ npx playwright test --update-snapshots
$ npx chromatic --playwright --project-token $CHROMATIC_PROJECT_TOKEN