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. What follows is for working on the generator itself.

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

Every flag falls back to the variable next to it, and every default is "" (think empty).

Those variables can be written down in a .env, in the folder the command runs from — a flag, or a variable already in the environment, wins over the file:

# .env
MDX=docs
NEXT_PUBLIC_LIBNAME=React Three Fiber
ICON=🇨🇭

flag	var	description	example
`IN` argument*	`MDX`	Path to `*.mdx` folder NB: can be relative or absolute	`docs` or `~/code/myproject/documentation`
`--libname`*	`NEXT_PUBLIC_LIBNAME`	Library name	`React Three Fiber`
`--libname-short`	`NEXT_PUBLIC_LIBNAME_SHORT`	Library short name	`r3f`
`--libname-dotsuffix-label`	`NEXT_PUBLIC_LIBNAME_DOTSUFFIX_LABEL`	Text for the ".docs" suffix link inside the header	`docs`
`--libname-dotsuffix-href`	`NEXT_PUBLIC_LIBNAME_DOTSUFFIX_HREF`	Href for the ".docs" suffix link inside the header	`https://docs.pmnd.rs`
`--base-path`	`BASE_PATH`	Base path for the final URL	`/react-three-fiber`
`--home-redirect`	`HOME_REDIRECT`	Where the home should redirect	`/getting-started/introduction`
`--mdx-baseurl`	`MDX_BASEURL`	Base URL for inlining relative images	`https://github.com/pmndrs/react-three-fiber/raw/master/docs`
`--sourcecode-baseurl`	`SOURCECODE_BASEURL`	Base URL for `sourcecode:` code path	`https://github.com/pmndrs/react-three-fiber/tree/main`
`--edit-baseurl`	`EDIT_BASEURL`	Base URL for displaying "Edit this page" URLs	`https://github.com/pmndrs/react-three-fiber/edit/master/docs`
`--url`	`NEXT_PUBLIC_URL`	Final URL of the published website	`https://pmndrs.github.io/react-three-fiber`
`--icon`	`ICON`	Emoji or image to use as (fav)icon (path local to `MDX`)	`🇨🇭` or `/icon.png` or `/favicon.ico`
`--logo`	`LOGO`	Logo src/path (either FQURL or local to `MDX` path)	`/logo.png` or `https://worldvectorlogo.com/r3f.png`
`--github`	`GITHUB`	Github URL	`https://github.com/pmndrs/react-three-fiber`
`--discord`	`DISCORD`	Discord URL	`https://discord.com/channels/740090768164651008/740093168770613279`
`--theme-primary`	`THEME_PRIMARY`	Primary accent color	`#323e48`
`--theme-scheme`	`THEME_SCHEME`	Theme scheme	`content` or `expressive` or `fidelity` or `monochrome` or `neutral` or `tonalSpot` or `vibrant`
`--theme-contrast`	`THEME_CONTRAST`	Theme contrast -- value between -1 and 1	`0` or `-1` or `1` or `-.6`
`--theme-note`	`THEME_NOTE`	"note" color	`#1f6feb`
`--theme-tip`	`THEME_TIP`	"tip" color	`#238636`
`--theme-important`	`THEME_IMPORTANT`	"important" color	`#8957e5`
`--theme-warning`	`THEME_WARNING`	"warning" color	`#d29922`
`--theme-caution`	`THEME_CAUTION`	"caution" color	`#da3633`
—	`CONTRIBUTORS_PAT`	GitHub token for contributors API (see: https://docs.github.com/en/rest/collaborators/collaborators?apiVersion=2022-11-28#list-repository-collaborators)	`ghp_1234567890`

* 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.

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