You're viewing the claude/badge-npm-chromatic-colors deployment.

pmndrs/docs

Documentation generator for pmndrs/* projects.

npm@pmndrs/docs storybook chromaticstorybook chromaticplaywright

A static MDX documentation generator, with a GitHub reusable workflow. It is primarily used for some pmndrs/* projects, but will work for anyone.

Those projects are known to be using this generator.

INSTALL

Pre-requisites:

Install nvm, then:

$ nvm install
$ nvm use
$ node -v # make sure your version satisfies package.json#engines.node

nb: if you want this node version to be your default nvm's one: nvm alias default node

$ git clone https://github.com/pmndrs/docs.git
$ cd docs
$ pnpm install

Configuration

Important

Default value is always: "" (think empty).

var	description	example
`MDX`*	Path to `*.mdx` folder NB: can be relative or absolute	`docs` or `~/code/myproject/documentation`
`NEXT_PUBLIC_LIBNAME`*	Library name	`React Three Fiber`
`NEXT_PUBLIC_LIBNAME_SHORT`	Library short name	`r3f`
`BASE_PATH`	Base path for the final URL	`/react-three-fiber`
`DIST_DIR`	Path to the output folder (within project)	`out` or `docs/out/react-three-fiber`
`OUTPUT`	Set to `export` for static output	`export`
`HOME_REDIRECT`	Where the home should redirect	`/getting-started/introduction`
`MDX_BASEURL`	Base URL for inlining relative images	`http://localhost:60141`or `https://github.com/pmndrs/react-three-fiber/raw/master/docs`
`SOURCECODE_BASEURL`	Base URL for `sourcecode:` code path	`https://github.com/pmndrs/react-three-fiber/tree/main`
`EDIT_BASEURL`	Base URL for displaying "Edit this page" URLs	`https://github.com/pmndrs/react-three-fiber/edit/master/docs`
`NEXT_PUBLIC_URL`	Final URL of the published website	`https://pmndrs.github.io/react-three-fiber`
`ICON`	Emoji or image to use as (fav)icon (path local to `MDX`)	`🇨🇭` or `/icon.png` or `/favicon.ico`
`LOGO`	Logo src/path (either FQURL or local to `MDX` path)	`/logo.png` or `https://worldvectorlogo.com/r3f.png`
`GITHUB`	Github URL (its star count shows next to the header link)	`https://github.com/pmndrs/react-three-fiber`
`DISCORD`	Discord URL	`https://discord.com/channels/740090768164651008/740093168770613279`
`THEME_PRIMARY`	Primary accent color	`#323e48`
`THEME_SCHEME`	Theme scheme	`content` or `expressive` or `fidelity` or `monochrome` or `neutral` or `tonalSpot` or `vibrant`
`THEME_CONTRAST`	Theme contrast -- value between -1 and 1	`0` or `-1` or `1` or `-.6`
`THEME_NOTE`	"note" color	`#1f6feb`
`THEME_TIP`	"tip" color	`#238636`
`THEME_IMPORTANT`	"important" color	`#8957e5`
`THEME_WARNING`	"warning" color	`#d29922`
`THEME_CAUTION`	"caution" color	`#da3633`
`THEME_STORYBOOK`	"storybook" color	`#ff4785`
`THEME_NPM`	"npm" color	`#cb3837`
`THEME_CHROMATIC`	"chromatic" color	`#fc521f`
`CONTRIBUTORS_PAT`	GitHub token for contributors API and the header star count (see: https://docs.github.com/en/rest/collaborators/collaborators?apiVersion=2022-11-28#list-repository-collaborators)	`ghp_1234567890`
`LIB_VERSION`	Version label in the sidebar footer (default: `git describe --tags`)	`v1.2.3`
`TAG_MATCH`	Tags the version label is read from (`git describe --match`)	`v..*`
`VERSION_URL_TEMPLATE`	URL of a branch deployment; enables the version switcher	`https://mylib-git-{branch:vercel}-myteam.vercel.app`
`VERSION_PRODUCTION_BRANCH`	Production branch (default: `main`)	`master`
`VERSION_PRODUCTION_URL`	Production branch URL (default: `NEXT_PUBLIC_URL`)	`https://docs.pmnd.rs`
`VERSION_BRANCHES`	Regex of the branches the switcher offers	`^(main\|next\|v\d+)$`
`VERSION_BRANCHES_LIST`	Branches the switcher offers, instead of the remote's	`main,next,v9`

* Required

MDX_BASEURL

Given a advanced/introduction.mdx file in the MDX folder:

![](dog.png)

becomes (for a MDX_BASEURL=http://localhost:60141 value):

![](http://localhost:60141/advanced/dog.png)

http://localhost:60141 being the MDX folder served.

Tip

When deployed on GitHub Pages, MDX_BASEURL will typically value something like https://github.com/pmndrs/uikit/raw/main/docs, thanks to build.yml rule.

THEME_*

We implement m3 design system, using material-theme-builder.

This is an embed iframe of material-theme-builder's <Mtb> story.

Note

Material Color for more information
We currently don't have secondary/tertiary colors (maybe some day).

VERSION_*, LIB_VERSION, TAG_MATCH

Label: git describe --tags (eg. v10.7.9, v10.7.9-3-ga1b2c3d), or <branch>@<shortsha> without tags. LIB_VERSION overrides it.
TAG_MATCH narrows the tags:

repo tags	`TAG_MATCH`
`v10.7.9`, `v10`	`v..*`
`leva@0.10.1`, `other@1.0`	`leva@*`

VERSION_URL_TEMPLATE enables the switcher: the label lists the branches, each leading to the same page on its deployment. Full public URL (base path included), with a placeholder:

placeholder	`feat/Dark_mode` becomes	for	example
`{branch}`	`feat-dark-mode`	URLs you create	`https://docs-git-{branch}-pmndrs.vercel.app`
`{branch:vercel}`	`feat-darkmode`	Vercel Git integration	`https://mylib-git-{branch:vercel}-myteam.vercel.app`
`{branch:raw}`	`feat%2FDark_mode`	a path or query string	`https://example.com/preview?branch={branch:raw}`

VERSION_PRODUCTION_BRANCH leads to VERSION_PRODUCTION_URL; every other branch shows a banner linking to production.
Branches: the remote's, minus dependabot/, renovate/, changeset-release/. VERSION_BRANCHES replaces that filter, VERSION_BRANCHES_LIST the whole list. Read at build time.

Important

The per-branch URLs are yours to create: Vercel's Git integration does, vercel deploy does not (vercel alias set, see ci.yml).
Git needs full history and tags (fetch-depth: 0).

Usage

dev

This is dev.sh. The site listens on PORT (default 3000), the MDX folder on any free port, so several checkouts can run side by side:

$ (
  trap 'kill -9 0' SIGINT

  export PORT=${PORT:-3000}
  export _PORT=$(node -e 'const s = require("net").createServer().listen(0, () => { console.log(String(s.address().port)); s.close() })')

  export MDX=docs
  export NEXT_PUBLIC_LIBNAME="Poimandres"
  export NEXT_PUBLIC_LIBNAME_SHORT="pmndrs"
  export BASE_PATH=
  export DIST_DIR=
  export OUTPUT=
  export HOME_REDIRECT=
  export MDX_BASEURL=http://localhost:$_PORT
  export SOURCECODE_BASEURL="vscode://file$(pwd)"
  export EDIT_BASEURL="vscode://file$(pwd)/docs"
  export NEXT_PUBLIC_URL=
  export ICON=
  export LOGO=gutenberg.jpg
  export GITHUB=https://github.com/pmndrs/docs
  export DISCORD=https://discord.com/channels/740090768164651008/1264328004172255393
  export THEME_PRIMARY="#323e48"
  export THEME_SCHEME="tonalSpot"
  export THEME_CONTRAST="0"
  export THEME_NOTE="#1f6feb"
  export THEME_TIP="#238636"
  export THEME_IMPORTANT="#8957e5"
  export THEME_WARNING="#d29922"
  export THEME_CAUTION="#da3633"
  export THEME_STORYBOOK="#ff4785"
  export THEME_NPM="#cb3837"
  export THEME_CHROMATIC="#fc521f"
  export CONTRIBUTORS_PAT=

  npx serve $MDX -p $_PORT --no-port-switching --no-clipboard &

  pnpm run dev &

  wait
)

Then go to: http://localhost:3000

Tip

If HOME_REDIRECT= empty, / will not redirect, and instead displays an index of libraries.

build

This is start.sh, same ports:

$ (
  trap 'kill -9 0' SIGINT

  # `next dev` leaves types pointing at `src/app/api`, which the export build moves aside
  rm -rf out .next/dev/types

  export PORT=${PORT:-3000}
  export _PORT=$(node -e 'const s = require("net").createServer().listen(0, () => { console.log(String(s.address().port)); s.close() })')

  export MDX=docs
  export NEXT_PUBLIC_LIBNAME="Poimandres"
  export NEXT_PUBLIC_LIBNAME_SHORT="pmndrs"
  export BASE_PATH=
  export DIST_DIR=
  export OUTPUT=export
  export HOME_REDIRECT=
  export MDX_BASEURL=http://localhost:$_PORT
  export SOURCECODE_BASEURL=
  export EDIT_BASEURL=
  export NEXT_PUBLIC_URL=
  export ICON=
  export LOGO=gutenberg.jpg
  export GITHUB=https://github.com/pmndrs/docs
  export DISCORD=https://discord.com/channels/740090768164651008/1264328004172255393
  export THEME_PRIMARY="#323e48"
  export THEME_SCHEME="tonalSpot"
  export THEME_CONTRAST="0"
  export THEME_NOTE="#1f6feb"
  export THEME_TIP="#238636"
  export THEME_IMPORTANT="#8957e5"
  export THEME_WARNING="#d29922"
  export THEME_CAUTION="#da3633"
  export THEME_STORYBOOK="#ff4785"
  export THEME_NPM="#cb3837"
  export THEME_CHROMATIC="#fc521f"
  export CONTRIBUTORS_PAT=

  pnpm run build

  npx serve $MDX -p $_PORT --no-port-switching --no-clipboard &

  npx serve out -p $PORT &

  wait
)

http://localhost:3000

CLI

No clone, no install — the published CLI does the same build:

$ cd ~/code/pmndrs/react-three-fiber
$ (
  trap 'kill -9 0' SIGINT

  export PORT=${PORT:-3000}
  export _PORT=$(node -e 'const s = require("net").createServer().listen(0, () => { console.log(String(s.address().port)); s.close() })')

  export NEXT_PUBLIC_LIBNAME="React Three Fiber"
  export NEXT_PUBLIC_LIBNAME_SHORT="r3f"
  export BASE_PATH=/toto
  export HOME_REDIRECT=/getting-started/introduction
  export MDX_BASEURL=http://localhost:$_PORT
  export ICON=🇨🇭
  export GITHUB=https://github.com/pmndrs/react-three-fiber

  npx -y @pmndrs/docs@latest build docs docs/out --format website

  npx serve docs -p $_PORT --no-port-switching --no-clipboard &

  npx -y serve docs/out -p $PORT &

  wait
)

Then go to: http://localhost:3000

Every option above has a flag too — npx @pmndrs/docs@latest build --help lists them.

Agents

llms.txt dumps and the pmndrs MCP server moved to their own page: Agents.

Edit this page

Summary

INSTALL

Configuration

Usage

dev

build

CLI

Agents