Poimandres documentation

A documentation generator for `pmndrs/*` projects.

Configuration

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`
`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`)	`🇨🇭` 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`

* Required

MDX_BASEURL

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

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

  # [Config](https://github.com/pmndrs/docs#configuration)
  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

  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

  # [Config](https://github.com/pmndrs/docs#configuration)
  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=/introduction
  export MDX_BASEURL=http://localhost:$_PORT
  export EDIT_BASEURL=
  export NEXT_PUBLIC_URL=
  export ICON=
  export LOGO=gutenberg.jpg

  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

  # [Config](https://github.com/pmndrs/docs#configuration)
  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

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

Reusable GitHub Actions workflow

pmndrs/docs provides a build.yml reusable workflow, any project can use:

uses: pmndrs/docs/.github/workflows/build.yml@main
  with:
    mdx: './docs'
    libname: 'React Three Fiber'
    libname_short: 'r3f'
    home_redirect: '/getting-started/introduction'
    icon: '🇨🇭'
    logo: '/logo.png'

See pmndrs/react-three-fiber/.github/workflows/docs.yml for an example implementation.

Authoring

In your MDX folder, create any path/to/my-document.mdx:

---
title: My Document
description: Lorem ipsum...
image: dog.png
nav: 0
---

MARKDOWN

Frontmatter

Any key is optional.

title: if not provided, last part of the path is used: my document
image:
- relative (to the md file) or absolute path, eg: dog.png, ./dog.png, ../../dog.png, /dog.png or https://animals.com/dog.png
- will be used as metadata image if provided
nav: order in the navigation (on the same level)

MARKDOWN

TODO