You're viewing the ds 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.

Gutenberg lithography

Those projects are known to be using this generator.

INSTALL

Clone the repository

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

Use the right Node version

With nvm, which reads the repository's .nvmrc:

$ 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

Install the dependencies

$ pnpm install

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`) NB: also published at `/icon.svg`, which the libraries menu of the other pmndrs docs sites shows	`🇨🇭` 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 (unset: the pmndrs lime `#CAF543`)	`#323e48`
`THEME_SCHEME`	Theme scheme, moot while color match is on (see `THEME_COLOR_MATCH`)	`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_CUSTOM_COLORS`	Custom colors of the theme, `name:hex[:blend]` comma-separated -- each a role, `<Color role="brand" />`, `:blend` harmonizing it with the primary	`brand:#ff2d95:blend,status:#17b26a`
`THEME_COLOR_MATCH`	Each core and custom color rendered true to its own input (Material Theme Builder's "Color match"), on unless `false`: it takes precedence over `THEME_SCHEME`, readers can toggle it from the sidebar, and the scheme toggle is hidden while color match is on	`true` or `false`
`THEME_SECONDARY`	Secondary color, instead of the one derived from the primary	`#B03A3A`
`THEME_TERTIARY`	Tertiary color, instead of the one derived from the primary	`#7D5260`
`THEME_NEUTRAL`	Neutral color (the surfaces), instead of the pmndrs warm grey `#c1b793` -- `auto` derives it from the primary (see keep your previous look)	`#c1b793` or `auto`
`THEME_NEUTRAL_VARIANT`	Neutral variant color (the tinted surfaces, outlines), instead of the pmndrs `#495720` -- `auto` derives it from the primary	`#495720` or `auto`
`THEME_ERROR`	Error color, instead of the pmndrs red `#FF4980` -- `auto` for Material's default error	`#FF4980` or `auto`
`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`

Readers can re-seed THEME_PRIMARY, THEME_SCHEME, THEME_CONTRAST and THEME_COLOR_MATCH from the theme controls in the sidebar. An overridden control is outlined, and a double-click (or Delete) brings the site's value back.

MDX_BASEURL

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

advanced/introduction.mdx

![](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
The defaults are pmndrs/design-system's palette: the lime #CAF543 under color match, a warm grey neutral, and seven colors every site gets as custom colors, lime, teal, cyan, purple, red, orange and yellow (<Color role="teal" />).
THEME_PRIMARY is the seed: the secondary and tertiary colors are derived from it, unless the site gives its own (THEME_SECONDARY, THEME_TERTIARY). The neutral, neutral variant and error colors are the pmndrs ones, unless the site gives its own (THEME_NEUTRAL, THEME_NEUTRAL_VARIANT, THEME_ERROR), or auto to derive them from the primary too, as Material Theme Builder does.
THEME_COLOR_MATCH (on unless "false") is Material Theme Builder's "Color match - Stay true to my color inputs": each core and custom color keeps its input's chroma instead of being toned down to the scheme's, so THEME_SCHEME is ignored and the scheme toggle is hidden while color match is on. Readers can toggle color match from the sidebar. A custom color with :blend is still harmonized first.

Keep your previous look

Up to v4.19, a site's palette was the one its primary alone made (#323e48 under tonalSpot by default). Since v4.20 the defaults are the pmndrs palette, so a site that pinned only its primary now gets it under color match, on the pmndrs neutrals. To keep the previous look exactly, pin color match off and let the primary derive the neutrals and the error color again:

.github/workflows/docs.yml (reusable workflow)

uses: pmndrs/docs/.github/workflows/build.yml@v4
with:
  theme_primary: '#323e48' # yours
  theme_scheme: 'tonalSpot'
  theme_color_match: 'false'
  theme_neutral: 'auto'
  theme_neutral_variant: 'auto'
  theme_error: 'auto'

or, for a workflow that sets the environment itself:

.github/workflows/docs.yml (env)

env:
  THEME_PRIMARY: '#323e48' # yours
  THEME_SCHEME: 'tonalSpot'
  THEME_COLOR_MATCH: 'false'
  THEME_NEUTRAL: 'auto'
  THEME_NEUTRAL_VARIANT: 'auto'
  THEME_ERROR: 'auto'

The palette is then the v4.19 one, variable for variable. The alert colors are unchanged, so their THEME_NOTE… pins can stay or go. What is new either way: the seven pmndrs colors (--md-sys-color-lime… and their bg-lime… utilities), which nothing renders unless a page asks for one (<Color role="teal" />).

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 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 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
)