Reusable GitHub Actions workflow

In your .github/workflows folder, create a eg. docs.yml file:

uses: pmndrs/docs/.github/workflows/build.yml@v4
  with:
    mdx: 'docs'
    libname: 'React Three Fiber'
    libname_short: 'r3f'
    home_redirect: '/getting-started/introduction'
    icon: '🇨🇭'
    logo: '/logo.png'
    github: 'https://github.com/pmndrs/react-three-fiber'
    discord: 'https://discord.com/channels/740090768164651008/740093168770613279'

With no theme_* input, the site gets the pmndrs palette. Each input is a THEME_* variable of the configuration.

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

The CLI discovers docs.config.ts at the checked-out repository root. See Custom components and data for its components and scope fields.

The reusable workflow does not install your repository's dependencies or expose a custom configuration path. If your components import packages or your configuration lives elsewhere, use your own build job: check out the repository, set up Node, install its dependencies, then run the CLI:

pnpm dlx @pmndrs/docs build docs out --format website --libname 'My library' --config config/docs.config.ts

Set the website's configuration in that job and deploy the generated out folder. --config is optional when using the root docs.config.ts.

Optional inputs for the version switcher; version_production_branch defaults to the repository's default branch.

eg. for a monorepo package whose branches are deployed by Vercel's Git integration:

uses: pmndrs/docs/.github/workflows/build.yml@v4
  with:
    # ...
    tag_match: 'leva@*'
    version_url_template: 'https://leva-git-{branch:vercel}-pmndrs.vercel.app'

With version_url_template, the workflow outputs where the switcher links the branch being built: version_url, and its hostname, version_hostname -- a long branch already cut and hashed to fit the hostname label. A deployment the Git integration does not make needs that alias set, eg. for a vercel deploy in a later job:

jobs:
  build:
    uses: pmndrs/docs/.github/workflows/build.yml@v4
    with:
      # ...
      version_url_template: 'https://mylib-git-{branch}-myteam.vercel.app'

  vercel:
    needs: build
    steps:
      # ... `vercel deploy`, its URL in `steps.vercel-deploy.outputs.url`
      - run: npx -y vercel alias set "$DEPLOYMENT" "$ALIAS" --token="$VERCEL_TOKEN" --scope=myteam
        env:
          DEPLOYMENT: ${{ steps.vercel-deploy.outputs.url }}
          ALIAS: ${{ needs.build.outputs.version_hostname }}