pmndrs.docs

pmndrs/docs

Documentation generator for pmndrs/* projects.

Summary

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

Nothing to install to use it — every command below runs through npx. Working on the generator itself is the one case that needs a checkout:

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

Configuration

Every option is a flag, the environment variable it falls back to, or a line of a .env read from the folder the command runs in — a flag beats the environment, which beats the file, and everything defaults to empty. pmndrs-docs dev --help prints these same rows, which is where they are declared:

flagvardescription
--libnameNEXT_PUBLIC_LIBNAMELibrary name, e.g. "React Three Fiber"
--libname-shortNEXT_PUBLIC_LIBNAME_SHORTShort name, for narrow screens
--libname-dotsuffix-labelNEXT_PUBLIC_LIBNAME_DOTSUFFIX_LABELSuffix label
--libname-dotsuffix-hrefNEXT_PUBLIC_LIBNAME_DOTSUFFIX_HREFSuffix link
--base-pathBASE_PATHBase path of the final URL, e.g. "/react-three-fiber"
--home-redirectHOME_REDIRECTWhere "/" redirects to, empty for an index
--urlNEXT_PUBLIC_URLPublic URL the website is served from
--mdx-baseurlMDX_BASEURLBase URL relative assets are resolved against
--sourcecode-baseurlSOURCECODE_BASEURLBase URL of the "source code" links
--edit-baseurlEDIT_BASEURLBase URL of the "edit this page" links
--iconICONFavicon emoji, or a path inside the MDX folder
--logoLOGOLogo path or URL
--githubGITHUBGitHub URL
--discordDISCORDDiscord URL
--theme-primaryTHEME_PRIMARYSeed color of the palette, e.g. "#323e48"
--theme-schemeTHEME_SCHEMEPalette scheme, e.g. "tonalSpot"
--theme-contrastTHEME_CONTRASTPalette contrast, between -1 and 1
--theme-noteTHEME_NOTEColor of the NOTE alerts
--theme-tipTHEME_TIPColor of the TIP alerts
--theme-importantTHEME_IMPORTANTColor of the IMPORTANT alerts
--theme-warningTHEME_WARNINGColor of the WARNING alerts
--theme-cautionTHEME_CAUTIONColor of the CAUTION alerts

MDX is the folder itself, the IN argument of every command. CONTRIBUTORS_PAT has no flag: it is a GitHub token for the contributors API, and belongs in CI rather than in a file.

# .env
MDX=docs                                    # the folder of *.mdx, relative or absolute
NEXT_PUBLIC_LIBNAME=React Three Fiber       # the name in the header
NEXT_PUBLIC_LIBNAME_SHORT=r3f
BASE_PATH=/react-three-fiber
HOME_REDIRECT=/getting-started/introduction
MDX_BASEURL=https://github.com/pmndrs/react-three-fiber/raw/master/docs
SOURCECODE_BASEURL=https://github.com/pmndrs/react-three-fiber/tree/main
EDIT_BASEURL=https://github.com/pmndrs/react-three-fiber/edit/master/docs
ICON=🇨🇭
LOGO=/logo.png
GITHUB=https://github.com/pmndrs/react-three-fiber
THEME_PRIMARY="#323e48"                     # quoted, or `#` starts a comment
THEME_SCHEME=tonalSpot

MDX and NEXT_PUBLIC_LIBNAME are the two required ones.

MDX_BASEURL

Relative images are resolved against it, so ![](dog.png) in advanced/introduction.mdx becomes ![](https://…/advanced/dog.png). build.yml points it at the raw files of the branch being built; dev points it at the MDX folder it serves itself.

THEME_*

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

color scheme

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

Usage

dev

 
$ npx -y @pmndrs/docs@latest dev docs \
  --libname "React Three Fiber" \
  --libname-short "r3f" \
  --home-redirect /getting-started/introduction \
  --icon 🇨🇭 \
  --github https://github.com/pmndrs/react-three-fiber

Then go to: http://localhost:3000

Pages are read on every request — edit one, reload. The MDX folder is served alongside, so relative images resolve as you write them, and --port moves the server.

Tip

If --home-redirect is left empty, / will not redirect, and instead displays an index of libraries.

With the options in a .env, there is nothing left to pass:

$ npx -y @pmndrs/docs@latest dev

build

 
$ npx -y @pmndrs/docs@latest build docs out --format website \
  --libname "React Three Fiber" \
  --icon 🇨🇭
$ npx -y serve out

--format website statically exports the whole site into out — what build.yml publishes to GitHub Pages. --format fragment (the default) compiles one .html per .mdx instead: the compiled MDX and nothing else, no layout, no stylesheet, no script.

Agents

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

Edit this page