feat(site): replace the demo with a two-page demo and docs site

.github/workflows/ci.yml

@@ -26,3 +26,4 @@ jobs:
             - run: pnpm test
             - run: pnpm test:perf
             - run: pnpm build
+            - run: pnpm --filter overlapmark-site test:e2e

.github/workflows/pages.yml

@@ -1,6 +1,6 @@
 name: Pages
 
-# Builds the demo (examples/vanilla) and deploys it to GitHub Pages at
+# Builds the site (site/: the demo and the docs) and deploys it to GitHub Pages at
 # https://edonghyun.github.io/overlapmark/. Off until the repository
 # variable PAGES_ENABLED is 'true' and Pages is set to deploy from Actions.
 on:
@@ -33,9 +33,9 @@ jobs:
             - run: corepack enable
             - run: pnpm install --frozen-lockfile
             # The site is served from the /overlapmark/ subpath.
-            - run: pnpm --filter vanilla-example build --base /overlapmark/
+            - run: pnpm --filter overlapmark-site build --base /overlapmark/
             - uses: actions/upload-pages-artifact@v5
               with:
-                  path: examples/vanilla/dist
+                  path: site/dist
             - id: deployment
               uses: actions/deploy-pages@v5

.gitignore

@@ -32,7 +32,12 @@ __screenshots__
 
 # local-only planning docs
 docs/
+!site/docs/
 
 # acceptance-test working files
 acceptance/.work/
 packages/*/LICENSE
+
+# Playwright output of the site e2e suite
+site/test-results/
+site/playwright-report/

CONTRIBUTING.md

@@ -14,15 +14,15 @@ pnpm exec playwright install chromium   # browser tests
 
 The repository is a pnpm workspace:
 
-| Path                              | What it is                                                                                     |
-| --------------------------------- | ---------------------------------------------------------------------------------------------- |
-| `packages/core`                   | `@overlapmark/core`: segments, render contract, DOM helpers, `styles.css`                      |
-| `packages/dom`                    | `@overlapmark/dom`, the vanilla JS adapter                                                     |
-| `packages/vue`, `react`, `svelte` | The framework adapters                                                                         |
-| `packages/adapter-contract`       | Private: the browser test suite every adapter runs                                             |
-| `acceptance`                      | End-to-end tests of apps installed from the packed tarballs                                    |
-| `examples/vanilla`                | The [live demo](https://edonghyun.github.io/overlapmark/): `pnpm --filter vanilla-example dev` |
-| `docs-assets`                     | README images, rendered from the demo by `pnpm docs:images`                                    |
+| Path                              | What it is                                                                                               |
+| --------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `packages/core`                   | `@overlapmark/core`: segments, render contract, DOM helpers, `styles.css`                                |
+| `packages/dom`                    | `@overlapmark/dom`, the vanilla JS adapter                                                               |
+| `packages/vue`, `react`, `svelte` | The framework adapters                                                                                   |
+| `packages/adapter-contract`       | Private: the browser test suite every adapter runs                                                       |
+| `acceptance`                      | End-to-end tests of apps installed from the packed tarballs                                              |
+| `site`                            | The [live demo and docs](https://edonghyun.github.io/overlapmark/): `pnpm --filter overlapmark-site dev` |
+| `docs-assets`                     | README images, rendered from the site by `pnpm docs:images`                                              |
 
 ## Checks
 

README.md

@@ -1,10 +1,10 @@
 # overlapmark
 
-<img src="https://raw.githubusercontent.com/edonghyun/overlapmark/main/docs-assets/hero.png" alt="A paragraph with overlapping highlights in different colors: the spots several analyses cover are darker, and a panel lists the highlights covering the clicked phrase." width="100%">
+<img src="https://raw.githubusercontent.com/edonghyun/overlapmark/main/docs-assets/hero.png" alt="The overlapmark demo: a sentence with three overlapping highlights in yellow, orange and pink, darker where they overlap, under an Add a highlight button." width="100%">
 
 [![npm](https://img.shields.io/npm/v/@overlapmark/core?label=npm)](https://www.npmjs.com/package/@overlapmark/core) [![CI](https://github.com/edonghyun/overlapmark/actions/workflows/ci.yml/badge.svg)](https://github.com/edonghyun/overlapmark/actions/workflows/ci.yml) [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/edonghyun/overlapmark/blob/main/LICENSE)
 
-**[Live demo](https://edonghyun.github.io/overlapmark/)**
+**[Live demo](https://edonghyun.github.io/overlapmark/)** · **[Docs](https://edonghyun.github.io/overlapmark/docs/)**
 
 Overlapping text highlights for Vue, React, Svelte and plain JS. The more highlights cover a spot, the darker it gets, even when every highlight has its own color, and a click tells you exactly which highlights cover that spot.
 
@@ -101,7 +101,7 @@ highlights = findMatches(text, 'highlights').map((m, i) => ({
 hl.update({ highlights });
 ```
 
-The [live demo](https://edonghyun.github.io/overlapmark/) lives in [`examples/vanilla`](examples/vanilla): `pnpm --filter vanilla-example dev`.
+The [live demo and docs](https://edonghyun.github.io/overlapmark/) live in [`site`](site): `pnpm --filter overlapmark-site dev`.
 
 ## Quick start (Vue)
 
@@ -221,23 +221,23 @@ With the default `layers` strategy, each highlight covering a segment is its own
 
 ### `multiply` (default)
 
-<img src="https://raw.githubusercontent.com/edonghyun/overlapmark/main/docs-assets/overlap-multiply.png" alt="The demo paragraph in multiply mode: every nested highlight darkens the spot it covers." width="100%">
+<img src="https://raw.githubusercontent.com/edonghyun/overlapmark/main/docs-assets/overlap-multiply.png" alt="A sentence with three nested highlights in multiply mode: every nested highlight darkens the spot it covers." width="100%">
 
 Each nested layer multiplies with the layers under it (`mix-blend-mode: multiply`), like a highlighter pen drawn over itself, so every highlight covering a spot darkens it, for any color except pure white (a white layer multiplies to no change). The root is an isolated group (`isolation: isolate`), so the layers never blend with the page behind the root.
 
 **When to use:** text on a light background, with any palette. **Caveats:** a nested layer, its own text included, multiplies with everything painted under it inside the root, so a decoration such as a badge's background inside a nested mark is tinted too. On a dark background, pastel layers fade into the background, and the light text of a nested highlight is tinted by the layers below it and loses contrast. For dark themes, keep a light reading surface behind the highlighted text, or switch to `darken` with deeper colors (see the snippet below).
 
 ### `darken`
 
-<img src="https://raw.githubusercontent.com/edonghyun/overlapmark/main/docs-assets/overlap-darken.png" alt="The demo paragraph in darken mode: nested highlights are their own color mixed toward black." width="100%">
+<img src="https://raw.githubusercontent.com/edonghyun/overlapmark/main/docs-assets/overlap-darken.png" alt="The same sentence in darken mode: nested highlights are their own color mixed toward black." width="100%">
 
 Each nested layer takes its own color mixed toward `--om-depth-ink` (default `black`) by `--om-depth-step` (default `12%`) per nesting level, up to `--om-max-depth`, and is painted at `--om-alpha`. It uses no blend mode: the layers are translucent over the page, and the text is not tinted.
 
 **When to use:** dark themes, or wherever blending is unwanted. **Caveats:** it darkens reliably only when the overlapping colors have similar lightness. A pale color nested inside a saturated one still comes out lighter than the color around it, so pick a palette of similar lightness.
 
 ### `none`
 
-<img src="https://raw.githubusercontent.com/edonghyun/overlapmark/main/docs-assets/overlap-none.png" alt="The demo paragraph in none mode: plain translucent layers." width="100%">
+<img src="https://raw.githubusercontent.com/edonghyun/overlapmark/main/docs-assets/overlap-none.png" alt="The same sentence in none mode: plain translucent layers." width="100%">
 
 Plain translucent layers, each at `--om-alpha`, with no depth effect. Overlaps of light colors may look the same as, or lighter than, a single highlight.
 

RELEASING.md

@@ -25,7 +25,7 @@ Never run `npm publish` or `changeset publish` from a laptop.
 
 The demo links to the npm packages, which return 404 until they are published, and the README images need these files on `main`. So these come last:
 
-2. **Demo site.** Settings, Pages: set the source to GitHub Actions, then add the repository variable `PAGES_ENABLED` with the value `true`. The next push to `main`, or a manual run of the Pages workflow, deploys the demo to <https://edonghyun.github.io/overlapmark/>.
+2. **Demo and docs site.** Settings, Pages: set the source to GitHub Actions, then add the repository variable `PAGES_ENABLED` with the value `true`. The next push to `main`, or a manual run of the Pages workflow, deploys the demo to <https://edonghyun.github.io/overlapmark/> and the docs to <https://edonghyun.github.io/overlapmark/docs/>.
 3. **Repository homepage.** Set the repository website (the About box) to <https://edonghyun.github.io/overlapmark/>.
 4. **Deprecate the old package.** The root README says `vue-easy-highlight` is replaced; make npm say so:
 

acceptance/scripts/check-readme.ts

@@ -1,12 +1,13 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { QUICK_STARTS } from '../../site/src/quick-starts.ts';
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
 
 interface Framework {
     /** As in the root README heading `## Quick start (<heading>)`. */
-    heading: string;
+    heading: keyof typeof QUICK_STARTS;
     pkg: string;
     /** The acceptance app's quick-start file. */
     file: string;
@@ -72,6 +73,12 @@ for (const { heading, pkg, file } of frameworks) {
             `${pkgReadme}: quick start differs from README.md (${heading})`,
         );
 
+    const site = QUICK_STARTS[heading];
+    if (normalized(site.code).join('\n') !== lines.join('\n'))
+        problems.push(
+            `site/src/quick-starts.ts: quick start differs from README.md (${heading})`,
+        );
+
     const app = join(root, 'acceptance/apps', file);
     if (!existsSync(app)) {
         problems.push(`${relative(root, app)} does not exist (${heading})`);
@@ -87,4 +94,6 @@ if (problems.length > 0) {
     console.error(problems.join('\n'));
     process.exit(1);
 }
-console.log('README quick starts match the package READMEs and the apps');
+console.log(
+    'README quick starts match the package READMEs, the site and the apps',
+);