From e2118db4931dccdcbed7770f4b865cc272de0469 Mon Sep 17 00:00:00 2001 From: Antoine BERNIER Date: Wed, 19 Aug 2026 16:29:33 +0200 Subject: [PATCH] feat(cli): `dev`, to serve a folder of MDX as it is written `pmndrs-docs dev docs --libname "React Three Fiber"` serves the website on localhost:3000 and reads the MDX folder on every request -- edit a page, reload. It takes every website option `build` takes, plus `--port`. The folder is linked under `public`, which is where Next serves a folder as it is on disk, so `MDX_BASEURL` has something to answer and there is no second server to start. The same kind of link satisfies the `@source` Tailwind resolves statically, which is how `build` stages the docs now -- a link where it used to copy the whole folder. `MDX_BASEURL` may be a path rather than a URL, so nothing depends on which port the server lands on. The options are declared once, in `src/website.options.ts`: the CLI builds its flags from it, `--help` prints the descriptions, and the documentation renders the table from the same rows. Both commands read a `.env` from the folder they run in, through node's own parser, so the variables the reusable workflow sets can be written down once -- a flag, or a variable already in the environment, wins. That leaves `preview.sh`, `start.sh` and `next-build.sh` with nothing to do: `.env` carries what they exported, `dev` replaces the build-and-serve dance, and `build --format website` is the only static export path left. Playwright drives `pnpm dev` instead of `start.sh`, on the port `PORT` names, with the Next dev overlay kept out of its screenshots. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_012cPxBc72sTMVZdgtFWYdAt --- .changeset/olive-pans-smile.md | 16 ++ .env | 23 +++ .github/workflows/ci.yml | 16 +- .gitignore | 7 +- README.md | 34 ++-- docs/getting-started/introduction.mdx | 226 ++++++-------------------- next-build.sh | 35 ---- next.config.mjs | 2 + package.json | 6 +- playwright.config.ts | 12 +- playwright.screenshot.css | 4 + preview.sh | 27 --- src/cli/main.ts | 123 +++++++------- src/cli/render.tsx | 2 + src/cli/website.ts | 148 ++++++++++++----- src/components/mdx/WebsiteOptions.tsx | 30 ++++ src/utils/compileMdxContent.tsx | 2 + src/utils/resolveMdxUrl.test.ts | 6 + src/utils/resolveMdxUrl.ts | 6 +- src/website.options.ts | 35 ++++ start.sh | 41 ----- 21 files changed, 383 insertions(+), 418 deletions(-) create mode 100644 .changeset/olive-pans-smile.md create mode 100644 .env delete mode 100755 next-build.sh create mode 100644 playwright.screenshot.css delete mode 100755 preview.sh create mode 100644 src/components/mdx/WebsiteOptions.tsx create mode 100644 src/website.options.ts delete mode 100755 start.sh diff --git a/.changeset/olive-pans-smile.md b/.changeset/olive-pans-smile.md new file mode 100644 index 000000000..f61b4bdda --- /dev/null +++ b/.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. diff --git a/.env b/.env new file mode 100644 index 000000000..644616f4e --- /dev/null +++ b/.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" diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e892a5b64..53492cbb3 100644 --- a/.github/workflows/ci.yml +++ b/.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 diff --git a/.gitignore b/.gitignore index 557262a06..f3596e2a8 100644 --- a/.gitignore +++ b/.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/ diff --git a/README.md b/README.md index 1696eba94..8a1eb1eb5 100644 --- a/README.md +++ b/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. -
-Preview a folder of MDX, served - -```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. - -
- # 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. diff --git a/docs/getting-started/introduction.mdx b/docs/getting-started/introduction.mdx index 00a0dc4ab..681536f22 100644 --- a/docs/getting-started/introduction.mdx +++ b/docs/getting-started/introduction.mdx @@ -14,79 +14,53 @@ nav: 0 ## INSTALL -Pre-requisites: - -- Install [nvm](https://github.com/nvm-sh/nvm), then: - ```sh - $ nvm install - $ nvm use - $ node -v # make sure your version satisfies package.json#engines.node - ``` - nb: if you want this node version to be your default nvm's one: - `nvm alias default node` +Nothing to install to use it — every command below runs through `npx`. Working on the generator +itself is the one case that needs a checkout: ```sh $ git clone https://github.com/pmndrs/docs.git $ cd docs -$ pnpm install +$ nvm use && pnpm install ``` ## Configuration -> [!IMPORTANT] -> -> Default value is always: `""` (think *empty*). - -| 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` | -| `NEXT_PUBLIC_LIBNAME_DOTSUFFIX_LABEL` | Text for the ".docs" suffix link inside the header | `docs` | -| `NEXT_PUBLIC_LIBNAME_DOTSUFFIX_HREF` | Href for the ".docs" suffix link inside the header | `https://docs.pmnd.rs` | -| `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` | -| `SOURCECODE_BASEURL` | Base URL for `sourcecode:` code path | `https://github.com/pmndrs/react-three-fiber/tree/main` | -| `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` | -| `GITHUB` | Github URL | `https://github.com/pmndrs/react-three-fiber` | -| `DISCORD` | Discord URL | `https://discord.com/channels/740090768164651008/740093168770613279` | -| `THEME_PRIMARY` | Primary accent color | `#323e48` | -| `THEME_SCHEME` | Theme scheme | `content` or `expressive` or `fidelity` or `monochrome` or `neutral` or `tonalSpot` or `vibrant` | -| `THEME_CONTRAST` | Theme contrast -- value between -1 and 1 | `0` 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` | -| `CONTRIBUTORS_PAT` | GitHub token for contributors API (see: https://docs.github.com/en/rest/collaborators/collaborators?apiVersion=2022-11-28#list-repository-collaborators) | `ghp_1234567890` | - -\* Required +Every option is a flag, the environment variable it falls back to, or a line of a `.env` read +from the folder the command runs in — a flag beats the environment, which beats the file, and +everything defaults to empty. `pmndrs-docs dev --help` prints these same rows, which is where +they are declared: -
- `MDX_BASEURL` + -Given a `advanced/introduction.mdx` file in the `MDX` folder: +`MDX` is the folder itself, the `IN` argument of every command. `CONTRIBUTORS_PAT` has no flag: +it is a [GitHub token](https://docs.github.com/en/rest/collaborators/collaborators) for the +contributors API, and belongs in CI rather than in a file. -```md -![](dog.png) +```sh +# .env +MDX=docs # the folder of *.mdx, relative or absolute +NEXT_PUBLIC_LIBNAME=React Three Fiber # the name in the header +NEXT_PUBLIC_LIBNAME_SHORT=r3f +BASE_PATH=/react-three-fiber +HOME_REDIRECT=/getting-started/introduction +MDX_BASEURL=https://github.com/pmndrs/react-three-fiber/raw/master/docs +SOURCECODE_BASEURL=https://github.com/pmndrs/react-three-fiber/tree/main +EDIT_BASEURL=https://github.com/pmndrs/react-three-fiber/edit/master/docs +ICON=🇨🇭 +LOGO=/logo.png +GITHUB=https://github.com/pmndrs/react-three-fiber +THEME_PRIMARY="#323e48" # quoted, or `#` starts a comment +THEME_SCHEME=tonalSpot ``` -becomes (for a `MDX_BASEURL=http://localhost:60141` value): - -```md -![](http://localhost:60141/advanced/dog.png) -``` +`MDX` and `NEXT_PUBLIC_LIBNAME` are the two required ones. -`http://localhost:60141` being the `MDX` folder served. +
+ `MDX_BASEURL` -> [!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. +Relative images are resolved against it, so `![](dog.png)` in `advanced/introduction.mdx` +becomes `![](https://…/advanced/dog.png)`. `build.yml` points it at the raw files of the branch +being built; `dev` points it at the MDX folder it serves itself.
@@ -108,135 +82,41 @@ We implement [m3 design system](https://m3.material.io/styles/color/system/overv ### dev ```sh -$ ( - trap 'kill -9 0' SIGINT - - export _PORT=60141 - - export MDX=docs - export NEXT_PUBLIC_LIBNAME="Poimandres" - export NEXT_PUBLIC_LIBNAME_SHORT="pmndrs" - export NEXT_PUBLIC_LIBNAME_DOTSUFFIX_LABEL="docs" - export NEXT_PUBLIC_LIBNAME_DOTSUFFIX_HREF="https://docs.pmnd.rs" - export BASE_PATH= - export DIST_DIR= - export OUTPUT= - export HOME_REDIRECT= - export MDX_BASEURL=http://localhost:$_PORT - export SOURCECODE_BASEURL="vscode://file$(pwd)" - export EDIT_BASEURL="vscode://file$(pwd)/docs" - 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" - export CONTRIBUTORS_PAT= - - kill $(lsof -ti:"$_PORT") - npx serve $MDX -p $_PORT --no-port-switching --no-clipboard & - - pnpm run dev & - - wait -) +$ npx -y @pmndrs/docs@latest dev docs \ + --libname "React Three Fiber" \ + --libname-short "r3f" \ + --home-redirect /getting-started/introduction \ + --icon 🇨🇭 \ + --github https://github.com/pmndrs/react-three-fiber ``` Then go to: http://localhost:3000 +Pages are read on every request — edit one, reload. The `MDX` folder is served alongside, so +relative images resolve as you write them, and `--port` moves the server. + > [!TIP] -> If `HOME_REDIRECT=` empty, `/` will not redirect, and instead displays an index of libraries. +> If `--home-redirect` is left empty, `/` will not redirect, and instead displays an index of libraries. -### build +With the options in a [`.env`](#Configuration), there is nothing left to pass: ```sh -$ ( - 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 NEXT_PUBLIC_LIBNAME_DOTSUFFIX_LABEL="docs" - export NEXT_PUBLIC_LIBNAME_DOTSUFFIX_HREF="https://docs.pmnd.rs" - export BASE_PATH= - export DIST_DIR= - export OUTPUT=export - export HOME_REDIRECT=/getting-started/introduction - export MDX_BASEURL=http://localhost:$_PORT - export SOURCECODE_BASEURL= - 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" - export CONTRIBUTORS_PAT= - - pnpm run build - - kill $(lsof -ti:"$_PORT") - npx serve $MDX -p $_PORT --no-port-switching --no-clipboard & - - npx serve out & - - wait -) +$ npx -y @pmndrs/docs@latest dev ``` -http://localhost:3000 - -### CLI - -No clone, no install — the published CLI does the same build: +### build ```sh -$ cd ~/code/pmndrs/react-three-fiber -$ ( - trap 'kill -9 0' SIGINT - - export _PORT=60141 - - export NEXT_PUBLIC_LIBNAME="React Three Fiber" - export NEXT_PUBLIC_LIBNAME_SHORT="r3f" - export BASE_PATH=/toto - export HOME_REDIRECT=/getting-started/introduction - export MDX_BASEURL=http://localhost:$_PORT - export ICON=🇨🇭 - export GITHUB=https://github.com/pmndrs/react-three-fiber - - npx -y @pmndrs/docs@latest build docs docs/out --format website - - kill $(lsof -ti:"$_PORT") - npx serve docs -p $_PORT --no-port-switching --no-clipboard & - - npx -y serve docs/out & - - wait -) +$ npx -y @pmndrs/docs@latest build docs out --format website \ + --libname "React Three Fiber" \ + --icon 🇨🇭 +$ npx -y serve out ``` -Then go to: http://localhost:3000 - -Every option above has a flag too — `npx @pmndrs/docs@latest build --help` lists them. +`--format website` statically exports the whole site into `out` — what +[`build.yml`](./github-actions.mdx) publishes to GitHub Pages. `--format fragment` (the default) +compiles one `.html` per `.mdx` instead: the compiled MDX and nothing else, no layout, no +stylesheet, no script. ## Agents diff --git a/next-build.sh b/next-build.sh deleted file mode 100755 index 7444d4116..000000000 --- a/next-build.sh +++ /dev/null @@ -1,35 +0,0 @@ -#!/bin/sh -# -# Next.js build wrapper for static export compatibility -# -# When building in export mode (OUTPUT=export), Next.js cannot handle Route Handlers -# (route.ts files) as they require server runtime. This script temporarily moves the -# /api directory during the build, then restores it afterward to preserve the source. -# -# Usage: -# OUTPUT=export npm run build # Static export (GitHub Pages) -# npm run build # Server build (Vercel) - -# Check if we're building in export mode -if [ "$OUTPUT" = "export" ]; then - IS_EXPORT=true -else - IS_EXPORT=false -fi - -# Move API directory if building for export -if [ "$IS_EXPORT" = "true" ]; then - mkdir -p tmp - mv src/app/api tmp/api-backup -fi - -# Run Next.js build -next build -STATUS=$? - -# Restore API directory if it was moved -if [ "$IS_EXPORT" = "true" ]; then - mv tmp/api-backup src/app/api -fi - -exit $STATUS \ No newline at end of file diff --git a/next.config.mjs b/next.config.mjs index 8bb618bd2..76248d2ff 100644 --- a/next.config.mjs +++ b/next.config.mjs @@ -5,6 +5,8 @@ const output = process.env.OUTPUT || undefined /** @type {import('next').NextConfig} */ const nextConfig = { productionBrowserSourceMaps: true, + // The floating dev badge is in front of the page Playwright screenshots + devIndicators: false, images: { // domains: ['codesandbox.io'], unoptimized: true, diff --git a/package.json b/package.json index 9b0ff511b..fba464182 100644 --- a/package.json +++ b/package.json @@ -85,9 +85,9 @@ "zod": "^3.24.1" }, "scripts": { - "dev": "NODE_OPTIONS='--inspect' next", + "dev": "pnpm build:cli && NODE_OPTIONS='--inspect' node bin/pmndrs-docs.mjs dev --sourcecode-baseurl \"vscode://file$PWD\" --edit-baseurl \"vscode://file$PWD/docs\"", "start": "next start", - "build": "./next-build.sh", + "build": "next build", "format": "prettier -w src/", "lint": "eslint src/**/*.{ts,tsx} && prettier . --check", "prepare": "husky && (test -f scripts/copy-fonts.sh && sh scripts/copy-fonts.sh || true)", @@ -101,7 +101,7 @@ "prepack": "node scripts/build-cli.mjs" }, "engines": { - "node": ">=20.9.0" + "node": ">=20.12.0" }, "packageManager": "pnpm@10.28.1", "description": "Generate pmndrs-standardized documentation — HTML fragments, or the whole website — from a folder of MDX.", diff --git a/playwright.config.ts b/playwright.config.ts index e0707fd75..bd2395c08 100644 --- a/playwright.config.ts +++ b/playwright.config.ts @@ -3,11 +3,17 @@ import { defineConfig, devices } from '@playwright/test' /** * See https://playwright.dev/docs/test-configuration. */ +// The website is served on 3000 unless `PORT` says otherwise, which `pnpm dev` reads too +const url = `http://localhost:${process.env.PORT ?? 3000}` + export default defineConfig({ testDir: './src/app', testIgnore: '**/route.test.ts', use: { - baseURL: 'http://localhost:3000', + baseURL: url, + }, + expect: { + toHaveScreenshot: { stylePath: './playwright.screenshot.css' }, }, projects: [ { @@ -26,7 +32,7 @@ export default defineConfig({ }, ], webServer: { - command: './start.sh', - url: 'http://localhost:3000', + command: 'pnpm dev', + url, }, }) diff --git a/playwright.screenshot.css b/playwright.screenshot.css new file mode 100644 index 000000000..ab865ee09 --- /dev/null +++ b/playwright.screenshot.css @@ -0,0 +1,4 @@ +/* The Next dev overlay is not part of the page: it comes and goes with whatever it has to say */ +nextjs-portal { + display: none; +} diff --git a/preview.sh b/preview.sh deleted file mode 100755 index 2c3796531..000000000 --- a/preview.sh +++ /dev/null @@ -1,27 +0,0 @@ -#!/bin/sh - -main() { - trap 'kill -9 0' SIGINT - - export _PORT="${_PORT:-60141}" - export VERSION="${VERSION:-latest}" - - export MDX="${MDX:-docs}" - export NEXT_PUBLIC_LIBNAME="${NEXT_PUBLIC_LIBNAME:-Poimandres}" - # Relative assets resolve against the MDX folder, served below on the same port - export MDX_BASEURL="${MDX_BASEURL:-http://localhost:$_PORT}" - - rm -rf "$MDX/out" - - # Every other option is read straight from the environment — same process, nothing to forward - npx -y "@pmndrs/docs@$VERSION" build "$MDX" "$MDX/out" --format website || exit 1 - - kill $(lsof -ti:"$_PORT") - npx serve $MDX -p $_PORT --no-port-switching --no-clipboard & - - npx -y serve "$MDX/out" & - - wait -} - -main diff --git a/src/cli/main.ts b/src/cli/main.ts index 4828c8650..53d4f80e0 100644 --- a/src/cli/main.ts +++ b/src/cli/main.ts @@ -1,4 +1,5 @@ import { version } from '@/package.json' +import { WEBSITE_OPTIONS } from '@/website.options' import { MARKDOWN_REGEX, crawl, getDocs } from '@/utils/docs' import { Command, Option, type OptionValues } from 'commander' import { copyFile, mkdir, readFile, stat, writeFile } from 'node:fs/promises' @@ -8,58 +9,22 @@ import { formatHits, formatMatches } from './browse.print' import { matchingLines, search } from './browse.search' import { resolveTarget } from './browse.target' import { fragmentComponents, renderFragment, renderToHtml } from './render' -import { buildWebsite } from './website' +import { buildWebsite, devWebsite } from './website' -/** - * The website options — the ones that describe *a site* rather than what to compile. - * - * Each carries the environment variable the app reads it as, so that a flag and its variable - * are declared in one place, and `--help` says which is which. `Option.env()` then does the - * fallback itself, which is what keeps the reusable workflow working with no flags at all. - */ -const websiteOptions = [ - new Option('--libname ', 'Library name, e.g. "React Three Fiber"').env( - 'NEXT_PUBLIC_LIBNAME', - ), - new Option('--libname-short ', 'Short library name, for narrow screens').env( - 'NEXT_PUBLIC_LIBNAME_SHORT', - ), - new Option('--libname-dotsuffix-label