pmndrs/docs
pmndrs/* projects.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
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:
| flag | var | description |
|---|---|---|
--libname | NEXT_PUBLIC_LIBNAME | Library name, e.g. "React Three Fiber" |
--libname-short | NEXT_PUBLIC_LIBNAME_SHORT | Short name, for narrow screens |
--libname-dotsuffix-label | NEXT_PUBLIC_LIBNAME_DOTSUFFIX_LABEL | Suffix label |
--libname-dotsuffix-href | NEXT_PUBLIC_LIBNAME_DOTSUFFIX_HREF | Suffix link |
--base-path | BASE_PATH | Base path of the final URL, e.g. "/react-three-fiber" |
--home-redirect | HOME_REDIRECT | Where "/" redirects to, empty for an index |
--url | NEXT_PUBLIC_URL | Public URL the website is served from |
--mdx-baseurl | MDX_BASEURL | Base URL relative assets are resolved against |
--sourcecode-baseurl | SOURCECODE_BASEURL | Base URL of the "source code" links |
--edit-baseurl | EDIT_BASEURL | Base URL of the "edit this page" links |
--icon | ICON | Favicon emoji, or a path inside the MDX folder |
--logo | LOGO | Logo path or URL |
--github | GITHUB | GitHub URL |
--discord | DISCORD | Discord URL |
--theme-primary | THEME_PRIMARY | Seed color of the palette, e.g. "#323e48" |
--theme-scheme | THEME_SCHEME | Palette scheme, e.g. "tonalSpot" |
--theme-contrast | THEME_CONTRAST | Palette contrast, between -1 and 1 |
--theme-note | THEME_NOTE | Color of the NOTE alerts |
--theme-tip | THEME_TIP | Color of the TIP alerts |
--theme-important | THEME_IMPORTANT | Color of the IMPORTANT alerts |
--theme-warning | THEME_WARNING | Color of the WARNING alerts |
--theme-caution | THEME_CAUTION | Color 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  in advanced/introduction.mdx
becomes . 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.
- 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.
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
Both formats use the same Next.js build and static export. --format website exports the
whole site into out — what build.yml publishes to GitHub Pages.
--format fragment (the default) extracts one .html per .mdx from that export: the
compiled MDX and nothing else, no layout, no stylesheet, no script. Assets are copied
alongside the fragments. Mermaid diagrams stay fenced blocks, and Sandpack shows its code
without the editor.
You can also pass a single file or pipe MDX to stdin:
$ npx -y @pmndrs/docs@latest build page.mdx
$ cat page.mdx | npx -y @pmndrs/docs@latest build
Both write only the HTML fragment to stdout, with build logs on stderr. Every invocation
runs next build, even for a single file or stdin.
Agents
llms.txt dumps and the pmndrs MCP server moved to their own page: Agents.