pmndrs/docs

Documentation generator for `pmndrs/*` projects.

INSTALL

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

Configuration

vardescriptionexample
MDX*Path to *.mdx folder
NB: can be relative or absolute
docs or ~/code/myproject/documentation
NEXT_PUBLIC_LIBNAME*Library nameReact Three Fiber
NEXT_PUBLIC_LIBNAME_SHORTLibrary short namer3f
BASE_PATHBase path for the final URL/react-three-fiber
DIST_DIRPath to the output folder (within project)out or docs/out/react-three-fiber
OUTPUTSet to export for static outputexport
HOME_REDIRECTWhere the home should redirect/getting-started/introduction
MDX_BASEURLBase URL for inlining relative imageshttp://localhost:60141or https://github.com/pmndrs/react-three-fiber/raw/master/docs
EDIT_BASEURLBase URL for displaying "Edit this page" URLshttps://github.com/pmndrs/react-three-fiber/edit/master/docs
NEXT_PUBLIC_URLFinal URL of the published websitehttps://pmndrs.github.io/react-three-fiber
ICONEmoji or image to use as (fav)icon (path local to MDX)šŸ‡ØšŸ‡­ or /icon.png or /favicon.ico
LOGOLogo src/path (either FQURL or local to MDX path)/logo.png or https://worldvectorlogo.com/r3f.png
GITHUBGithub URLhttps://github.com/pmndrs/react-three-fiber
DISCORDDiscord URLhttps://discord.com/channels/740090768164651008/740093168770613279
THEME_PRIMARYPrimary accent color (see: https://tailwind-material-colors-docs.vercel.app)#323e48
THEME_SCHEMETheme scheme (see: https://tailwind-material-colors-docs.vercel.app)content or expressive or fidelity or monochrome or neutral or tonalSpot or vibrant
THEME_CONTRASTTheme contrast -- value between -1 and 10 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

* Required

MDX_BASEURL

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

![](https://github.com/pmndrs/docs/raw/sandpack/docs/getting-started/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.

dev

$ (
  trap 'kill -9 0' SIGINT

  export _PORT=60141

  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 EDIT_BASEURL="vscode://file/$MDX"
  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"

  kill $(lsof -ti:"$_PORT")
  npx serve $MDX -p $_PORT --no-port-switching --no-clipboard &
  npm 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

$ (
  trap 'kill -9 0' SIGINT

  rm -rf out

  export _PORT=60141

  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=/getting-started/introduction
  export MDX_BASEURL=http://localhost:$_PORT
  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"

  npm run build

  kill $(lsof -ti:"$_PORT")
  npx serve $MDX -p $_PORT --no-port-switching --no-clipboard &
  npx serve out &

  wait
)

http://localhost:3000

Docker

$ docker build -t pmndrs-docs .
$ cd ~/code/pmndrs/react-three-fiber
$ (
  trap 'kill -9 0' SIGINT

  export _PORT=60141

  export MDX=./docs
  export NEXT_PUBLIC_LIBNAME="React Three Fiber"
  export NEXT_PUBLIC_LIBNAME_SHORT="r3f"
  export BASE_PATH=
  export OUTPUT=export
  export HOME_REDIRECT=/getting-started/introduction
  export MDX_BASEURL=http://localhost:$_PORT
  export EDIT_BASEURL=
  export NEXT_PUBLIC_URL=
  export ICON=šŸ‡ØšŸ‡­
  export LOGO=/logo.png
  export GITHUB=https://github.com/pmndrs/react-three-fiber
  export DISCORD=https://discord.com/channels/740090768164651008/740093168770613279
  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"

  rm -rf "$MDX/out"

  docker run --rm --init -it \
    -v "$MDX":/app/docs \
    -e MDX \
    -e NEXT_PUBLIC_LIBNAME \
    -e BASE_PATH \
    -e DIST_DIR="$MDX/out$BASE_PATH" \
    -e OUTPUT \
    -e HOME_REDIRECT \
    -e MDX_BASEURL \
    -e EDIT_BASEURL \
    -e NEXT_PUBLIC_URL \
    -e ICON \
    -e LOGO \
    -e GITHUB \
    -e DISCORD \
    -e THEME_PRIMARY \
    -e THEME_SCHEME \
    -e THEME_CONTRAST \
    -e THEME_NOTE \
    -e THEME_TIP \
    -e THEME_IMPORTANT \
    -e THEME_WARNING \
    -e THEME_CAUTION \
    pmndrs-docs npm run build

  kill $(lsof -ti:"$_PORT")
  npx serve $MDX -p $_PORT --no-port-switching --no-clipboard &
  npx -y serve "$MDX/out" &

  wait
)

Then go to: http://localhost:3000