docs: a landing page that types its Markdown, a rail that widens on hover, and a Vite Doctor page

docs/pages/guide/validation.md

@@ -45,7 +45,7 @@ github-callouts and zoom have nothing to report: a quote that isn't a callout st
 
 ## Line numbers
 
-`meta.issues` can't say where a problem is, because Comark gives nodes no source positions. [comark-lint](/lint/) finds the line of each issue and adds what Comark forgives silently: blocks never closed, misspelled components, broken anchors, and unsafe URLs. Run it in CI and in [Vite Doctor](/lint/getting-started/#vite-doctor):
+`meta.issues` can't say where a problem is, because Comark gives nodes no source positions. [comark-lint](/lint/) finds the line of each issue and adds what Comark forgives silently: blocks never closed, misspelled components, broken anchors, and unsafe URLs. Run it in CI and in [Vite Doctor](/lint/vite-doctor/):
 
 ```sh
 pnpm comark-lint "docs/**/*.md"

docs/pages/index.md

@@ -1,9 +1,27 @@
 ---
 title: Comark plugins
 description: Plugins for Comark that make review documents easier to read.
-tagline: Annotated screenshots, zoom, carousels, tabs, callouts, embeds, and charts for Comark documents. Each plugin is its own package, and they all share one version.
+headline: Review documents, written in Markdown.
+tagline: Annotated screenshots, code changes, charts, callouts, embeds, zoom, carousels, and tabs for Comark, plus partials and a linter. Each plugin is its own package, and they all share one version.
 ---
 
+::hero
+````md
+> [!TIP] Decision
+> Extra filters collapse into **+2 filters**.
+
+::screenshot{src="/after.png" alt="Filter toolbar on one row"}
+:::annotation{x=67.9 y=34.8 w=13 h=14.2 mark="highlight"}
+Five filters now fit on one row.
+:::
+
+:::annotation{x=82.5 y=34.8 w=10.5 h=14.2 mark="check" color="green"}
+**Apply** lines up with the chips.
+:::
+::
+````
+::
+
 ## Review blocks
 
 What a review is made of: screenshots with marks, code changes, callouts, and players.
@@ -20,7 +38,7 @@ Scripts that add to plain HTML. Without them a page still reads top to bottom, c
 
 ## Authoring tools
 
-For writing the documents: shared partials, and a linter that catches what Comark forgives.
+For writing the documents: shared partials, and a linter that catches what Comark forgives, from the command line or [Vite Doctor](/lint/vite-doctor/).
 
 ::cards{group="Authoring tools"}
 ::

docs/pages/lint/getting-started.md

@@ -42,21 +42,4 @@ const diagnostics = await lint(markdown, { plugins: [annotate()], components });
 
 ## Vite Doctor
 
-`comark-lint/doctor` is a [Vite Doctor](https://github.com/onmax/vite-doctor) extension. Vite Doctor loads extensions from an executable config, so register it in `doctor.config.ts`:
-
-```ts
-// doctor.config.ts
-import comark from "comark-lint/doctor";
-import { defineDoctorConfig } from "vite-doctor/config";
-
-export default defineDoctorConfig({
-  extends: ["auto"],
-  extensions: [comark({ components: ["tabs"] })],
-});
-```
-
-```sh
-pnpm vite-doctor . --config doctor.config.ts
-```
-
-It lints `**/*.{md,mdc}` except `node_modules` and `dist`; set `include` and `exclude` to change that. Each rule reports with its own code, `COMARK0001` to `COMARK0007`, and the `comark/recommended` preset turns them all on. It runs whenever the extension is registered. It needs `vite-doctor` 0.1 or later.
+`comark-lint/doctor` runs the same rules inside [Vite Doctor](/lint/vite-doctor/), each with its own code.

docs/pages/lint/vite-doctor.md

@@ -0,0 +1,64 @@
+---
+title: Vite Doctor
+description: Lint a project's Markdown as part of Vite Doctor, with one code per rule.
+install: pnpm add -D comark-lint vite-doctor
+---
+
+## Setup
+
+`comark-lint/doctor` is a [Vite Doctor](https://github.com/onmax/vite-doctor) extension. Vite Doctor loads extensions from an executable config, so register it in `doctor.config.ts`:
+
+```ts
+// doctor.config.ts
+import comark from "comark-lint/doctor";
+import { defineDoctorConfig } from "vite-doctor/config";
+
+export default defineDoctorConfig({
+  extends: ["comark/recommended"],
+  extensions: [comark({ components: ["tabs"] })],
+});
+```
+
+```sh
+pnpm vite-doctor . --config doctor.config.ts
+```
+
+It runs whenever the extension is registered, and the `comark/recommended` preset turns every rule on. It needs `vite-doctor` 0.1 or later.
+
+## Options
+
+It takes the same `plugins` and `components` as the [command line's config](/lint/getting-started/#command-line), plus two of its own:
+
+| Option | |
+| --- | --- |
+| `include` | The Markdown to check, relative to the project root. Default `**/*.{md,mdc}`. |
+| `exclude` | Globs to skip. Default `**/node_modules/**` and `**/dist/**`. |
+
+This site lints its own pages this way. Its `docs/build.ts` renders a few components itself, so the config names them:
+
+```ts
+// doctor.config.ts
+export default defineDoctorConfig({
+  extends: ["comark/recommended"],
+  extensions: [
+    comark({
+      include: "docs/pages/**/*.md",
+      components: ["cards", "example", "examples", "hero", "matrix"],
+    }),
+  ],
+});
+```
+
+## Codes
+
+Each rule reports with its own code, and the code links to the rule's entry on the [overview](/lint/#rules). Frontmatter Comark can't read and unsafe URLs are errors; the rest are warnings.
+
+| Code | Rule | Severity |
+| --- | --- | --- |
+| [`COMARK0001`](/lint/#comark0001) | `comark/unclosed-block` | warning |
+| [`COMARK0002`](/lint/#comark0002) | `comark/unknown-component` | warning |
+| [`COMARK0003`](/lint/#comark0003) | `comark/malformed-attributes` | warning |
+| [`COMARK0004`](/lint/#comark0004) | `comark/broken-anchor` | warning |
+| [`COMARK0005`](/lint/#comark0005) | `comark/invalid-frontmatter` | error |
+| [`COMARK0006`](/lint/#comark0006) | `comark/plugin-issue` | warning |
+| [`COMARK0007`](/lint/#comark0007) | `comark/unsafe-url` | error |

docs/play.ts

@@ -92,10 +92,27 @@ function markPreset(id?: string) {
 
 // The header's npmx link follows the preset, and stays on its package while you edit it. A shared link's Markdown
 // could use any of them, so it gets the page with all of them.
+const reducedMotion = matchMedia("(prefers-reduced-motion: reduce)");
 function pointNpmx(npm?: string) {
   npmx.href = `https://npmx.dev/${npm ? `package/${npm}` : "~onmax_"}`;
   npmx.title = npm ? `${npm} on npmx` : "Every package on npmx";
-  npmxName.textContent = npm || "npmx";
+  const name = npm || "npmx";
+  if (npmxName.textContent === name) return;
+  const from = npmx.offsetWidth;
+  npmxName.textContent = name;
+  const to = npmx.offsetWidth;
+  // The pill resizes to the new name as the name rises into it, so the swap reads as one change of package.
+  const ease = "cubic-bezier(0.23, 1, 0.32, 1)";
+  if (reducedMotion.matches) {
+    npmxName.animate({ opacity: [0, 1] }, { duration: 150, easing: "ease-out" });
+    return;
+  }
+  if (from !== to)
+    npmx.animate({ width: [`${from}px`, `${to}px`] }, { duration: 250, easing: ease });
+  npmxName.animate(
+    { opacity: [0, 1], filter: ["blur(2px)", "blur(0)"], transform: ["translateY(6px)", "none"] },
+    { duration: 200, easing: ease },
+  );
 }
 
 let run = 0;