Chore: Capture local work from main

.github/dependabot.yml

@@ -4,12 +4,12 @@
 # Docs: https://docs.github.com/code-security/dependabot/dependabot-version-updates
 version: 2
 updates:
-  - package-ecosystem: "npm"
-    directory: "/"
+  - package-ecosystem: 'npm'
+    directory: '/'
     schedule:
-      interval: "monthly"
+      interval: 'monthly'
     open-pull-requests-limit: 1
     groups:
       all-dependencies:
-        patterns: ["*"]
-        update-types: ["major", "minor", "patch"]
+        patterns: ['*']
+        update-types: ['major', 'minor', 'patch']

.saggar/project.json

@@ -1,3 +1,3 @@
 {
-  "name" : "Docusaurus plugins docs"
-}
+  "name": "Docusaurus plugins docs"
+}

CLAUDE.md

@@ -4,7 +4,7 @@ Guidance for Claude Code when working in this repository.
 
 ## Project
 
-`docusaurus-plugins-docs` — a Docusaurus v3 documentation site for a family of Docusaurus plugins. The site installs and demos most plugins it documents, so docs and live behaviour stay in sync. Exceptions (`starter`, `marginalia`) are called out below.
+`docusaurus-plugins-docs` is a Docusaurus v3 documentation site for a family of Docusaurus plugins. The site installs and demos several plugins it documents. Embeds, Marginalia, Open with LLM, Speccy, and Starter aren't registered here. Their guides explain how to use them on your own site.
 
 - Entry: `docusaurus.config.ts`
 - Content: `docs/` (per-plugin nested structure), `blog/`, `src/pages/`
@@ -15,18 +15,21 @@ Guidance for Claude Code when working in this repository.
 
 Each is a standalone npm package (not a workspace). Most install from the npm registry; `new-post-toast` and `starter` install from local tarballs in `vendor/` (see `package.json` — `file:./vendor/*.tgz`) because the published versions need the workarounds documented below:
 
-| Directory (this repo) | Package                            | Docs route               |
-| --------------------- | ---------------------------------- | ------------------------ |
-| —                     | `docusaurus-plugin-banner`         | `/docs/banner/*`         |
-| —                     | `docusaurus-plugin-cookie-consent` | `/docs/cookie-consent/*` |
-| —                     | `docusaurus-plugin-glossary`       | `/docs/glossary/*`       |
-| —                     | `docusaurus-plugin-marginalia`     | `/docs/marginalia/*`     |
-| —                     | `docusaurus-plugin-mcp`            | `/docs/mcp/*`            |
-| —                     | `docusaurus-plugin-new-post-toast` | `/docs/new-post-toast/*` |
-| —                     | `docusaurus-plugin-omg`            | `/docs/omg/*`            |
+| Directory (this repo) | Package                             | Docs route                |
+| --------------------- | ----------------------------------- | ------------------------- |
+| —                     | `docusaurus-plugin-banner`          | `/docs/banner/*`          |
+| —                     | `docusaurus-plugin-cookie-consent`  | `/docs/cookie-consent/*`  |
+| —                     | `docusaurus-plugin-embeds`          | `/docs/embeds/*`          |
+| —                     | `docusaurus-plugin-glossary`        | `/docs/glossary/*`        |
+| —                     | `docusaurus-plugin-marginalia`      | `/docs/marginalia/*`      |
+| —                     | `docusaurus-plugin-mcp`             | `/docs/mcp/*`             |
+| —                     | `docusaurus-plugin-new-post-toast`  | `/docs/new-post-toast/*`  |
+| —                     | `docusaurus-plugin-open-with-llm`   | `/docs/open-with-llm/*`   |
+| —                     | `docusaurus-plugin-omg`             | `/docs/omg/*`             |
 | —                     | `docusaurus-plugin-share-selection` | `/docs/share-selection/*` |
-| —                     | `docusaurus-plugin-starter`        | `/docs/starter/*`        |
-| —                     | `docusaurus-plugin-statuspage`     | `/docs/statuspage/*`     |
+| —                     | `docusaurus-plugin-speccy`          | External Speccy guide     |
+| —                     | `docusaurus-plugin-starter`         | `/docs/starter/*`         |
+| —                     | `docusaurus-plugin-statuspage`      | `/docs/statuspage/*`      |
 
 The source of each plugin lives in its own sibling repo under `~/Development/docusaurus/`. **Do not** introduce a monorepo or workspace spanning them — they are maintained as independent repos and that boundary is load-bearing.
 

README.md

@@ -1,20 +1,24 @@
 # docusaurus-plugins-docs
 
-Documentation site for a family of Docusaurus v3 plugins — and a live demo of all of them. Every plugin documented here is installed and running on this site, so the docs are dogfooded by definition.
+Documentation site for a family of Docusaurus v3 plugins, with live demos of several plugins. Embeds, Marginalia, Open with LLM, Speccy, and Starter aren't registered on this site. Their guides explain how to use them on your own site.
 
 ## Plugins
 
-| Plugin                                                                                               | Docs                                                                                                |
-| ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
-| [`docusaurus-plugin-banner`](https://www.npmjs.com/package/docusaurus-plugin-banner)                 | [`/docs/banner`](./docs/banner)                                                                     |
-| [`docusaurus-plugin-cookie-consent`](https://www.npmjs.com/package/docusaurus-plugin-cookie-consent) | [`/docs/cookie-consent`](./docs/cookie-consent)                                                     |
-| [`docusaurus-plugin-glossary`](https://www.npmjs.com/package/docusaurus-plugin-glossary)             | [`/docs/glossary`](./docs/glossary)                                                                 |
-| `docusaurus-plugin-marginalia` (not yet published)                                                   | [`/docs/marginalia`](./docs/marginalia)                                                             |
-| [`docusaurus-plugin-new-post-toast`](https://www.npmjs.com/package/docusaurus-plugin-new-post-toast) | [`/docs/new-post-toast`](./docs/new-post-toast)                                                     |
-| [`docusaurus-plugin-omg`](https://www.npmjs.com/package/docusaurus-plugin-omg)                       | [`/docs/omg`](./docs/omg)                                                                           |
-| [`docusaurus-plugin-speccy`](https://www.npmjs.com/package/docusaurus-plugin-speccy)                 | [Speccy docs](https://github.com/mcclowes/speccy/blob/main/apps/docusaurus-demo/docs/docusaurus.md) |
-| [`docusaurus-plugin-starter`](https://www.npmjs.com/package/docusaurus-plugin-starter)               | [`/docs/starter`](./docs/starter)                                                                   |
-| [`docusaurus-plugin-statuspage`](https://www.npmjs.com/package/docusaurus-plugin-statuspage)         | [`/docs/statuspage`](./docs/statuspage)                                                             |
+| Plugin                                                                                                 | Docs                                                                                                |
+| ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
+| [`docusaurus-plugin-banner`](https://www.npmjs.com/package/docusaurus-plugin-banner)                   | [`/docs/banner`](./docs/banner)                                                                     |
+| [`docusaurus-plugin-cookie-consent`](https://www.npmjs.com/package/docusaurus-plugin-cookie-consent)   | [`/docs/cookie-consent`](./docs/cookie-consent)                                                     |
+| [`docusaurus-plugin-embeds`](https://www.npmjs.com/package/docusaurus-plugin-embeds)                   | [`/docs/embeds`](./docs/embeds)                                                                     |
+| [`docusaurus-plugin-glossary`](https://www.npmjs.com/package/docusaurus-plugin-glossary)               | [`/docs/glossary`](./docs/glossary)                                                                 |
+| `docusaurus-plugin-marginalia` (not yet published)                                                     | [`/docs/marginalia`](./docs/marginalia)                                                             |
+| [`docusaurus-plugin-mcp`](https://www.npmjs.com/package/docusaurus-plugin-mcp)                         | [`/docs/mcp`](./docs/mcp)                                                                           |
+| [`docusaurus-plugin-new-post-toast`](https://www.npmjs.com/package/docusaurus-plugin-new-post-toast)   | [`/docs/new-post-toast`](./docs/new-post-toast)                                                     |
+| [`docusaurus-plugin-open-with-llm`](https://www.npmjs.com/package/docusaurus-plugin-open-with-llm)     | [`/docs/open-with-llm`](./docs/open-with-llm)                                                       |
+| [`docusaurus-plugin-omg`](https://www.npmjs.com/package/docusaurus-plugin-omg)                         | [`/docs/omg`](./docs/omg)                                                                           |
+| [`docusaurus-plugin-share-selection`](https://www.npmjs.com/package/docusaurus-plugin-share-selection) | [`/docs/share-selection`](./docs/share-selection)                                                   |
+| [`docusaurus-plugin-speccy`](https://www.npmjs.com/package/docusaurus-plugin-speccy)                   | [Speccy docs](https://github.com/mcclowes/speccy/blob/main/apps/docusaurus-demo/docs/docusaurus.md) |
+| [`docusaurus-plugin-starter`](https://www.npmjs.com/package/docusaurus-plugin-starter)                 | [`/docs/starter`](./docs/starter)                                                                   |
+| [`docusaurus-plugin-statuspage`](https://www.npmjs.com/package/docusaurus-plugin-statuspage)           | [`/docs/statuspage`](./docs/statuspage)                                                             |
 
 ## Development
 

docs/glossary/component.md

@@ -49,6 +49,10 @@ We use <GlossaryTerm term="REST" definition="Representational State Transfer" />
 
 ## When to use it manually
 
+Omitting `routePath` uses the default glossary plugin instance's configured route. For example, with plugin `routePath: '/terms'` and a term ID of `api`, `<GlossaryTerm term="API" />` links to `/terms#api`. An explicit `routePath="/glossary"` still overrides that configuration. `documentationPath` or the term's `documentation.path` takes precedence over glossary-entry links.
+
+This fallback fix is unreleased. Until it is published, pass `routePath` explicitly when using a custom glossary route.
+
 - The auto-linker won't touch terms inside code blocks, existing links, or existing MDX components — use the component manually if you want those matched
 - When you need a one-off override of the term text or definition (e.g. localized phrasing) without editing `glossary.json`
 

docs/glossary/configuration.md

@@ -19,6 +19,16 @@ title: Configuration
 `generatePage`, `linkOnlyFirstOccurrence`, and category badges are unreleased. See
 [embedding a glossary](component.md#embedding-a-glossary-in-a-doc) for docs sidebar support.
 
+Manual `<GlossaryTerm>` links to glossary entries inherit the default plugin instance's `routePath`. A nonempty `routePath` prop overrides that route; when neither is available, the component uses `/glossary`.
+
+The configured-route fallback fix is unreleased. Pass `routePath` explicitly on manual terms until the fix is published.
+
+## Anchor validation
+
+Standalone and embedded glossaries register their rendered term IDs and letter-navigation IDs with Docusaurus. Valid links to these anchors pass a build with `onBrokenAnchors: 'throw'`, including sites hosted under a base URL such as `/sub/`. Missing anchors still fail validation.
+
+The anchor-registration fix is unreleased and raises the minimum supported Docusaurus version from 3.0 to 3.1, which introduced the anchor collector API. Published versions may report valid glossary-entry anchors as broken.
+
 ## Glossary JSON schema
 
 ```ts

docs/glossary/getting-started.md

@@ -11,6 +11,8 @@ title: Getting started
 npm install docusaurus-plugin-glossary
 ```
 
+The unreleased anchor-registration fix requires Docusaurus 3.1 or newer. See [anchor validation](configuration.md#anchor-validation) for the support change.
+
 ## Use the preset
 
 The easiest setup is to swap `@docusaurus/preset-classic` for the plugin's preset wrapper — it configures the classic preset **and** wires up the auto-linking remark plugin in one step:

docs/glossary/overview.md

@@ -32,7 +32,8 @@ Full runnable example site at [`examples/docusaurus-v3/`](https://github.com/mcc
 
 ## Compatibility
 
-- Docusaurus `^3.0.0` with MDX v3
+- Published versions support Docusaurus `^3.0.0` with MDX v3.
+- The unreleased anchor-registration fix requires Docusaurus `^3.1.0`.
 - React `^18` or `^19`
 - Node.js 20 or newer
 

docs/intro.md

@@ -7,7 +7,7 @@ sidebar_position: 1
 
 # Docusaurus plugins
 
-This site documents — and dogfoods — a family of Docusaurus v3 plugins. Every plugin you read about here is also installed and configured in the site you're reading it on, so each page is itself an example of the plugin in action.
+This site documents a family of Docusaurus v3 plugins and runs several as live demos. Embeds, Marginalia, Open with LLM, Speccy, and Starter aren't live demos on this site. Their guides explain how to use them on your own site.
 
 ## The plugins
 

docs/marginalia/advanced/theming.md

@@ -48,20 +48,20 @@ Wrap overrides in `[data-theme='dark']`:
 
 ## Variable reference
 
-| Variable                      | Maps to (default)               | Purpose                      |
-| ----------------------------- | ------------------------------- | ---------------------------- |
-| `--marginalia-accent`         | `--ifm-color-primary`           | Anchor underline, hot border |
-| `--marginalia-accent-soft`    | `--ifm-color-primary-lightest`  | `link` kind swatch           |
-| `--marginalia-accent-strong`  | `--ifm-color-primary-darker`    | `code` swatch, PUT/PATCH chip |
-| `--marginalia-danger`         | `--ifm-color-danger`            | `warning` / `endpoint` swatch |
-| `--marginalia-surface`        | `--ifm-card-background-color`   | Card + TOC background         |
-| `--marginalia-border`         | `--ifm-color-emphasis-300`      | Card border, dividers        |
-| `--marginalia-text`           | `--ifm-font-color-base`         | Body text inside cards       |
-| `--marginalia-heading`        | `--ifm-heading-color`           | Card titles                  |
-| `--marginalia-muted`          | `--ifm-color-emphasis-700`      | Kind labels, muted copy      |
-| `--marginalia-font-mono`      | `--ifm-font-family-monospace`   | Kind labels, pills, endpoint |
-| `--marginalia-font-serif`     | `--ifm-font-family-base`        | Card titles                  |
-| `--marginalia-navbar-offset`  | `--ifm-navbar-height`           | Sticky TOC offset            |
+| Variable                     | Maps to (default)              | Purpose                       |
+| ---------------------------- | ------------------------------ | ----------------------------- |
+| `--marginalia-accent`        | `--ifm-color-primary`          | Anchor underline, hot border  |
+| `--marginalia-accent-soft`   | `--ifm-color-primary-lightest` | `link` kind swatch            |
+| `--marginalia-accent-strong` | `--ifm-color-primary-darker`   | `code` swatch, PUT/PATCH chip |
+| `--marginalia-danger`        | `--ifm-color-danger`           | `warning` / `endpoint` swatch |
+| `--marginalia-surface`       | `--ifm-card-background-color`  | Card + TOC background         |
+| `--marginalia-border`        | `--ifm-color-emphasis-300`     | Card border, dividers         |
+| `--marginalia-text`          | `--ifm-font-color-base`        | Body text inside cards        |
+| `--marginalia-heading`       | `--ifm-heading-color`          | Card titles                   |
+| `--marginalia-muted`         | `--ifm-color-emphasis-700`     | Kind labels, muted copy       |
+| `--marginalia-font-mono`     | `--ifm-font-family-monospace`  | Kind labels, pills, endpoint  |
+| `--marginalia-font-serif`    | `--ifm-font-family-base`       | Card titles                   |
+| `--marginalia-navbar-offset` | `--ifm-navbar-height`          | Sticky TOC offset             |
 
 ## Swizzling
 

docs/marginalia/configuration.md

@@ -10,8 +10,8 @@ components.
 
 ## Plugin options
 
-| Option    | Type      | Default | Description                                |
-| --------- | --------- | ------- | ------------------------------------------ |
+| Option    | Type      | Default | Description                                           |
+| --------- | --------- | ------- | ----------------------------------------------------- |
 | `enabled` | `boolean` | `true`  | Toggle the plugin without removing it from `plugins`. |
 
 ## `<Marginalia>`

docs/marginalia/getting-started.md

@@ -33,7 +33,7 @@ import { Marginalia, Aside, Endpoint } from '@theme/Marginalia';
 
 <Marginalia>
 
-The concept of <Aside anchor="pattern languages" kind="concept" title="Christopher Alexander" meta={["1977", "253 patterns"]}>*A Pattern Language* catalogued 253 design patterns for towns and buildings.</Aside> has shaped software thinking.
+The concept of <Aside anchor="pattern languages" kind="concept" title="Christopher Alexander" meta={["1977", "253 patterns"]}>_A Pattern Language_ catalogued 253 design patterns for towns and buildings.</Aside> has shaped software thinking.
 
 Request a session with <Endpoint method="POST" path="/sessions" />.
 

docs/mcp/advanced/openapi.md

@@ -24,10 +24,10 @@ Point the plugin at one or more OpenAPI specs and it indexes every operation and
 
 Configuring `openapi` adds three more tools to the server. Without it, they don't appear at all.
 
-| Tool           | Description                                                              |
-| -------------- | ------------------------------------------------------------------------ |
-| `list_apis`    | The indexed specs, with versions and operation counts.                   |
-| `search_api`   | Search operations and webhook events by path, name, summary, or tag.     |
+| Tool           | Description                                                                           |
+| -------------- | ------------------------------------------------------------------------------------- |
+| `list_apis`    | The indexed specs, with versions and operation counts.                                |
+| `search_api`   | Search operations and webhook events by path, name, summary, or tag.                  |
 | `get_endpoint` | Full detail of one operation: params, request body, responses, with `$ref`s resolved. |
 
 ## Why resolved schemas matter