generator

.dockerignore

@@ -0,0 +1,3 @@
+node_modules
+out
+.next

.github/workflows/build.yml

@@ -0,0 +1,66 @@
+name: Reusable pmndrs/docs workflow
+
+on:
+  workflow_call:
+    inputs:
+      mdx:
+        required: true
+        type: string
+      libname:
+        required: true
+        type: string
+      home_redirect:
+        required: true
+        type: string
+        default: '/getting-started/introduction'
+      icon:
+        type: string
+        default: '🖨️'
+      logo:
+        type: string
+        default: '/logo.png'
+      base_path:
+        type: string
+
+jobs:
+  build-job:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - id: configurepages
+        uses: actions/configure-pages@v5
+      # https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#example-of-setting-an-output-parameter
+      - id: set-base-path
+        run: echo "BASE_PATH=${{ inputs.base_path || steps.configurepages.outputs.base_path }}" >> "$GITHUB_OUTPUT"
+      - run: |
+          set -ex
+
+          docker run --rm --init \
+            -v "$MDX":/app/docs \
+            -e BASE_PATH \
+            -e DIST_DIR="$MDX/out$BASE_PATH" \
+            -e MDX \
+            -e NEXT_PUBLIC_LIBNAME \
+            -e OUTPUT=export \
+            -e HOME_REDIRECT \
+            -e MDX_BASEURL \
+            -e EDIT_BASEURL \
+            -e NEXT_PUBLIC_URL \
+            -e ICON \
+            -e LOGO \
+            ghcr.io/pmndrs/docs:main npm run build
+        env:
+          BASE_PATH: ${{ steps.set-base-path.outputs.BASE_PATH }}
+          MDX: ${{ inputs.mdx }}
+          NEXT_PUBLIC_LIBNAME: ${{ inputs.libname }}
+          HOME_REDIRECT: ${{ inputs.home_redirect }}
+          MDX_BASEURL: 'https://github.com/${{ github.repository }}/raw/${{ github.ref_name }}/${{ inputs.mdx }}'
+          EDIT_BASEURL: 'https://github.com/${{ github.repository }}/edit/${{ github.ref_name }}/${{ inputs.mdx }}'
+          NEXT_PUBLIC_URL: ${{ steps.configurepages.outputs.base_url }}
+          ICON: '${{ inputs.icon }}'
+          LOGO: '${{ inputs.logo }}'
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: ${{ inputs.mdx }}/out${{ steps.set-base-path.outputs.BASE_PATH }}

.github/workflows/docker.yml

@@ -0,0 +1,60 @@
+# https://docs.github.com/en/actions/publishing-packages/publishing-docker-images#publishing-images-to-github-packages
+name: Create and publish a Docker image
+on:
+  push:
+    branches: ['main']
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build-and-push-image:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write # 'write' required for semantic-release-action
+      packages: write
+      attestations: write
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Log in to the Container registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      # will generate a git tag => then, used by docker/metadata-action
+      - name: Semantic Release
+        id: semantic_release
+        uses: cycjimmy/semantic-release-action@v4
+        with:
+          semantic_version: 24
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+
+      - name: Build and push Docker image
+        id: push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+      - name: Generate artifact attestation
+        uses: actions/attest-build-provenance@v1
+        with:
+          subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME}}
+          subject-digest: ${{ steps.push.outputs.digest }}
+          push-to-registry: true

.gitignore

@@ -6,11 +6,6 @@
 .pnp.js
 node_modules/
 
-# dependency lock files
-package-lock.json
-pnpm-lock.yaml
-yarn.lock
-
 # other
 .next/
 .DS_Store
@@ -20,4 +15,6 @@ dist/
 logs/
 out/
 tmp/
-temp/
+temp/
+
+tsconfig.tsbuildinfo

Dockerfile

@@ -0,0 +1,9 @@
+FROM node:18-alpine
+
+RUN apk add --no-cache libc6-compat git && apk update
+WORKDIR /app
+
+COPY package.json package-lock.json ./
+RUN npm ci
+
+COPY . .

README.md

@@ -0,0 +1,205 @@
+# Configuration
+
+| var                     | description                                                                                                                                                              | example                                                                                  |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
+| `MDX`\*                 | Path to `*.mdx` folder<br>NB: can be relative or absolute                                                                                                                | `docs` or `~/code/myproject/documentation`                                               |
+| `NEXT_PUBLIC_LIBNAME`\* | Library name                                                                                                                                                             | `React Three Fiber`                                                                      |
+| `BASE_PATH`             | Base path for the final URL                                                                                                                                              | `/react-three-fiber`                                                                     |
+| `DIST_DIR`              | Path to the output folder ([within project](https://nextjs.org/docs/app/api-reference/next-config-js/distDir#:~:text=should%20not%20leave%20your%20project%20directory)) | `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
+
+<details>
+  <summary>`MDX_BASEURL`</summary>
+
+Given a `advanced/introduction.mdx` file in the `MDX` folder:
+
+```mdx
+![](dog.png)
+```
+
+becomes (for a `MDX_BASEURL=http://localhost:60141` value):
+
+```mdx
+![](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`](.github/workflows/build.yml) rule.
+
+</details>
+
+# dev
+
+```sh
+$ (
+  trap 'kill -9 0' SIGINT
+
+  export _PORT=60141
+
+  # [Config](https://github.com/pmndrs/docs#configuration)
+  export MDX=~/code/pmndrs/react-three-fiber/docs
+  export NEXT_PUBLIC_LIBNAME="React Three Fiber"
+  export BASE_PATH=
+  export DIST_DIR=
+  export OUTPUT=export
+  export HOME_REDIRECT=/getting-started/introduction
+  export MDX_BASEURL=http://localhost:$_PORT
+  export EDIT_BASEURL="vscode://file/$MDX"
+  export NEXT_PUBLIC_URL=
+  export ICON="/icon.ico"
+  export LOGO=/logo.png
+
+  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
+
+```sh
+$ (
+  trap 'kill -9 0' SIGINT
+
+  rm -rf out
+
+  export _PORT=60141
+
+  # [Config](https://github.com/pmndrs/docs#configuration)
+  export MDX=~/code/pmndrs/react-three-fiber/docs
+  export NEXT_PUBLIC_LIBNAME="React Three Fiber"
+  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=/logo.png
+
+  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
+
+```sh
+$ docker build -t pmndrs-docs .
+```
+
+```sh
+$ 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 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`](.github/workflows/build.yml) reusable workflow, any project can use:
+
+```yml
+uses: pmndrs/docs/.github/workflows/build.yml@main
+  with:
+    mdx: './docs'
+    libname: 'React Three Fiber'
+    home_redirect: '/getting-started/introduction'
+    icon: '🇨🇭'
+    logo: '/logo.png'
+```
+
+See [`pmndrs/react-three-fiber/.github/workflows/docs.yml`](https://github.com/pmndrs/react-three-fiber/blob/master/.github/workflows/docs.yml) for an example implementation.
+
+# Authoring
+
+In your `MDX` folder, create any `path/to/my-document.mdx`:
+
+```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