feat(cli): dev, to serve a folder of MDX as it is written

.changeset/olive-pans-smile.md

@@ -0,0 +1,16 @@
+---
+'@pmndrs/docs': minor
+---
+
+`dev`: serve a folder of MDX, reloading as it is written
+
+```sh
+$ npx @pmndrs/docs@latest dev docs --libname "React Three Fiber" --icon 🥑
+```
+
+Pages are read on every request, and the folder is served alongside, so relative assets resolve
+with no second server to start. Takes every website option `build` takes, plus `--port`.
+
+Both commands now read a `.env` from the folder they run in — the variables the reusable
+workflow sets, written down once; a flag, or a variable already in the environment, wins over
+the file. `preview.sh` is replaced by `dev`. Needs node >=20.12.

.env

@@ -0,0 +1,23 @@
+# The docs.pmnd.rs website itself. `pmndrs-docs dev --help` lists every option; a flag, or a
+# variable already in the environment, wins over what is written here -- which is how CI builds
+# this same site with its own values.
+
+MDX=docs
+
+NEXT_PUBLIC_LIBNAME=Poimandres
+NEXT_PUBLIC_LIBNAME_SHORT=pmndrs
+NEXT_PUBLIC_LIBNAME_DOTSUFFIX_LABEL=docs
+NEXT_PUBLIC_LIBNAME_DOTSUFFIX_HREF=https://pmnd.rs
+
+LOGO=gutenberg.jpg
+GITHUB=https://github.com/pmndrs/docs
+DISCORD=https://discord.com/channels/740090768164651008/1264328004172255393
+
+THEME_PRIMARY="#323e48"
+THEME_SCHEME=tonalSpot
+THEME_CONTRAST=0
+THEME_NOTE="#1f6feb"
+THEME_TIP="#238636"
+THEME_IMPORTANT="#8957e5"
+THEME_WARNING="#d29922"
+THEME_CAUTION="#da3633"

.github/workflows/ci.yml

@@ -120,13 +120,9 @@ jobs:
 
       - id: vercel-deploy
         run: |
+          # Whatever is not passed here comes from `.env`, the website's own configuration
           npx -y vercel deploy --token=${{ secrets.VERCEL_TOKEN }} \
             --target=${{ github.event_name == 'push' && 'production' || 'preview' }} \
-            --build-env MDX=docs \
-            --build-env NEXT_PUBLIC_LIBNAME="Poimandres" \
-            --build-env NEXT_PUBLIC_LIBNAME_SHORT="pmndrs" \
-            --build-env NEXT_PUBLIC_LIBNAME_DOTSUFFIX_LABEL="docs" \
-            --build-env NEXT_PUBLIC_LIBNAME_DOTSUFFIX_HREF="https://pmnd.rs" \
             --build-env BASE_PATH= \
             --build-env DIST_DIR= \
             --build-env OUTPUT= \
@@ -136,17 +132,7 @@ jobs:
             --build-env SOURCECODE_BASEURL="https://github.com/${{ github.repository }}/tree/${{ github.head_ref || github.ref_name }}" \
             --build-env NEXT_PUBLIC_URL= \
             --build-env ICON= \
-            --build-env LOGO=gutenberg.jpg \
-            --build-env GITHUB="https://github.com/${{ github.repository }}" \
             --build-env DISCORD="${{ secrets.DISCORD }}" \
-            --build-env THEME_PRIMARY="#323e48" \
-            --build-env THEME_SCHEME="tonalSpot" \
-            --build-env THEME_CONTRAST="0" \
-            --build-env THEME_NOTE="#1f6feb" \
-            --build-env THEME_TIP="#238636" \
-            --build-env THEME_IMPORTANT="#8957e5" \
-            --build-env THEME_WARNING="#d29922" \
-            --build-env THEME_CAUTION="#da3633" \
             --build-env CONTRIBUTORS_PAT="${{ secrets.GITHUB_TOKEN }}" \
             > deployment-url.txt
 

.gitignore

@@ -17,7 +17,6 @@ node_modules/
 .next/
 .DS_Store
 .secrets
-tmp/api-backup
 
 build/
 dist/
@@ -41,5 +40,9 @@ chromatic-archives/
 storybook-static
 src/stories
 
-# the CLI's scratch copy of the app, removed after a build unless one crashes
+# the CLI's scratch copy of the app, and the docs it links in to serve them
 .pmndrs-docs/
+/public/mdx
+
+# Playwright screenshots, regenerated on every run
+*-snapshots/

README.md

@@ -31,6 +31,21 @@ Both read the published `llms-full.txt` of each library, cached for an hour unde
 `~/.cache/pmndrs-docs` — `--refresh` fetches again. Outside a terminal, a page target is
 written to stdout, so `npx @pmndrs/docs drei/performances/instances | glow` works.
 
+## Write
+
+```sh
+$ npx @pmndrs/docs@latest dev docs --libname "React Three Fiber" --icon 🥑
+```
+
+Serves the website on http://localhost:3000, reading the MDX folder on every request — edit a
+page, reload. The folder is served alongside, so relative assets resolve while you write, and
+`--port` moves the server. Every website option `build` takes, `dev` takes too.
+
+Each of them falls back to the environment variable it maps to — the ones
+[`build.yml`](.github/workflows/build.yml) sets — and a `.env` in the folder you run from is
+read into the environment, so `npx @pmndrs/docs@latest dev` alone is enough once written down.
+[`.env`](.env) is this repository's own website.
+
 ## Build
 
 ```sh
@@ -43,27 +58,10 @@ $ npx @pmndrs/docs@latest build docs out --format website   # the whole website,
 fragment is the compiled MDX and nothing else: no layout, no stylesheet, no script. Mermaid
 diagrams stay fenced blocks, and Sandpack shows its code without the editor.
 
-`build --help` lists every website option — `--libname`, `--base-path`, `--icon`, `--theme-*`… Each
+`dev --help` and `build --help` list every website option — `--libname`, `--base-path`, `--icon`, `--theme-*`… Each
 one falls back to the environment variable it maps to, the same ones
 [configuration](docs/getting-started/introduction.mdx#Configuration) documents.
 
-<details>
-<summary>Preview a folder of MDX, served</summary>
-
-```sh
-$ curl -sL https://raw.githubusercontent.com/pmndrs/docs/refs/heads/main/preview.sh | \
-  MDX="docs" \
-  ICON="🥑" \
-  sh
-```
-
-Builds the website, then serves it — alongside the MDX folder itself, so relative assets
-resolve while you edit. Any option from
-[configuration](docs/getting-started/introduction.mdx#Configuration) goes in the same way, and
-`VERSION` picks a published version of the CLI.
-
-</details>
-
 # Releasing
 
 Every push to `main` redeploys [docs.pmnd.rs](https://docs.pmnd.rs) via [ci.yml](.github/workflows/ci.yml) — no [changeset](.changeset/) needed for that.