From 9cb1888b0b3f2b26b2bbedda7e484cdd5e01d0ad Mon Sep 17 00:00:00 2001 From: Max Clayton Clowes Date: Sun, 11 Oct 2026 15:56:10 +0100 Subject: [PATCH 01/10] Chore: sync plugin catalogs and demo coverage Fixes #39 --- CLAUDE.md | 27 +++++++++++++++------------ README.md | 28 ++++++++++++++++------------ docs/intro.md | 2 +- docusaurus.config.ts | 3 +-- src/pages/index.mdx | 3 ++- 5 files changed, 35 insertions(+), 28 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index d94ca7d..7e86288 100644 --- a/CLAUDE.md +++ b/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. diff --git a/README.md b/README.md index 731fc3f..85c4775 100644 --- a/README.md +++ b/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 diff --git a/docs/intro.md b/docs/intro.md index 5cd53f3..dccd764 100644 --- a/docs/intro.md +++ b/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 diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 7317d5a..d6fe02b 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -46,8 +46,7 @@ const config: Config = { 'docusaurus-plugin-banner', { id: 'welcome', - content: - '🎉 You are looking at a site that uses every plugin documented here — try them out.', + content: '🎉 Explore the plugin docs and try the live demos on this site.', dismissible: true, backgroundColor: '#173a58', textColor: '#f4fffb', diff --git a/src/pages/index.mdx b/src/pages/index.mdx index 1573b0a..e9996e8 100644 --- a/src/pages/index.mdx +++ b/src/pages/index.mdx @@ -5,7 +5,7 @@ hide_table_of_contents: true # Docusaurus plugins -A family of small, focused plugins for Docusaurus v3 — documented and **dogfooded** on this site. Every plugin you read about here is installed and running right now on the site you're looking at. +A family of small, focused plugins for Docusaurus v3, with documentation and 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. ## Plugins @@ -20,6 +20,7 @@ A family of small, focused plugins for Docusaurus v3 — documented and **dogfoo | [New post toast](/docs/new-post-toast/overview) | Shows returning readers the blog posts published since their last visit. | | [Open with LLM](/docs/open-with-llm/overview) | Lets readers copy, download, or open a docs page as Markdown in an LLM. | | [omg](/docs/omg/overview) | Compiles OpenAPI Markdown Grammar into OpenAPI 3.1 during the Docusaurus build. | +| [Share selection](/docs/share-selection/overview) | Lets readers copy, ask AI about, or share a selected passage with a deep link. | | [Speccy](https://github.com/mcclowes/speccy/blob/main/apps/docusaurus-demo/docs/docusaurus.md) | Generates OpenAPI reference routes and embeds API references in MDX. | | [Starter](/docs/starter/overview) | Provides a typed template for building a Docusaurus plugin. | | [Statuspage](/docs/statuspage/overview) | Displays current incidents from a public Statuspage.io instance. | From ae15368f52a8a0213699f20d798c99ab6c04ce9f Mon Sep 17 00:00:00 2001 From: Max Clayton Clowes Date: Sun, 11 Oct 2026 15:57:59 +0100 Subject: [PATCH 02/10] Bug: restore typecheck with TypeScript 6 Fixes #40 --- tsconfig.json | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/tsconfig.json b/tsconfig.json index ed276a1..cf9104f 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -1,7 +1,10 @@ { "extends": "@docusaurus/tsconfig", "compilerOptions": { - "baseUrl": "." + "baseUrl": null, + "paths": { + "@site/*": ["./*"] + } }, "include": ["src/", "docusaurus.config.ts", "sidebars.ts"] } From 9ff10a1161ecfb77ac3436e389678ec653799a98 Mon Sep 17 00:00:00 2001 From: Max Clayton Clowes Date: Sun, 11 Oct 2026 16:02:21 +0100 Subject: [PATCH 03/10] Bug: restore linting with ESLint 9 flat config Fixes #41 --- .eslintrc.cjs | 24 ------------------------ eslint.config.mjs | 30 ++++++++++++++++++++++++++++++ package-lock.json | 2 ++ package.json | 2 ++ 4 files changed, 34 insertions(+), 24 deletions(-) delete mode 100644 .eslintrc.cjs create mode 100644 eslint.config.mjs diff --git a/.eslintrc.cjs b/.eslintrc.cjs deleted file mode 100644 index ba40c4e..0000000 --- a/.eslintrc.cjs +++ /dev/null @@ -1,24 +0,0 @@ -module.exports = { - root: true, - parser: '@typescript-eslint/parser', - parserOptions: { - ecmaVersion: 2022, - sourceType: 'module', - ecmaFeatures: { jsx: true }, - }, - env: { browser: true, node: true, es2022: true }, - plugins: ['@typescript-eslint', 'react'], - extends: [ - 'eslint:recommended', - 'plugin:@typescript-eslint/recommended', - 'plugin:react/recommended', - 'plugin:react/jsx-runtime', - 'prettier', - ], - settings: { react: { version: '18' } }, - ignorePatterns: ['build/', '.docusaurus/', 'node_modules/'], - rules: { - '@typescript-eslint/no-explicit-any': 'off', - '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }], - }, -}; diff --git a/eslint.config.mjs b/eslint.config.mjs new file mode 100644 index 0000000..fd8b9de --- /dev/null +++ b/eslint.config.mjs @@ -0,0 +1,30 @@ +import { defineConfig } from 'eslint/config'; +import js from '@eslint/js'; +import ts from '@typescript-eslint/eslint-plugin'; +import react from 'eslint-plugin-react'; +import prettier from 'eslint-config-prettier'; +import globals from 'globals'; + +export default defineConfig([ + { ignores: ['build/**', '.docusaurus/**', '**/node_modules/**', '**/.*'] }, + { + files: ['**/*.{js,jsx,mjs,cjs,ts,tsx,mts,cts}'], + extends: [ + js.configs.recommended, + ...ts.configs['flat/recommended'], + react.configs.flat.recommended, + react.configs.flat['jsx-runtime'], + prettier, + ], + languageOptions: { + ecmaVersion: 2022, + sourceType: 'module', + globals: { ...globals.browser, ...globals.node }, + }, + settings: { react: { version: '18' } }, + rules: { + '@typescript-eslint/no-explicit-any': 'off', + '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }], + }, + }, +]); diff --git a/package-lock.json b/package-lock.json index 70259b6..d43e41f 100644 --- a/package-lock.json +++ b/package-lock.json @@ -30,11 +30,13 @@ "@docusaurus/module-type-aliases": "^3.5.0", "@docusaurus/tsconfig": "^3.10.1", "@docusaurus/types": "^3.5.0", + "@eslint/js": "9.39.5", "@typescript-eslint/eslint-plugin": "^8.62.1", "@typescript-eslint/parser": "^8.62.1", "eslint": "^9.39.0", "eslint-config-prettier": "^10.1.8", "eslint-plugin-react": "^7.35.0", + "globals": "14.0.0", "prettier": "^3.9.4", "typescript": "~6.0.3" }, diff --git a/package.json b/package.json index 54dac81..f2d67b5 100644 --- a/package.json +++ b/package.json @@ -43,11 +43,13 @@ "@docusaurus/module-type-aliases": "^3.5.0", "@docusaurus/tsconfig": "^3.10.1", "@docusaurus/types": "^3.5.0", + "@eslint/js": "9.39.5", "@typescript-eslint/eslint-plugin": "^8.62.1", "@typescript-eslint/parser": "^8.62.1", "eslint": "^9.39.0", "eslint-config-prettier": "^10.1.8", "eslint-plugin-react": "^7.35.0", + "globals": "14.0.0", "prettier": "^3.9.4", "typescript": "~6.0.3" }, From f4d799fc6bd3e91c633571822838bbccb4d5d204 Mon Sep 17 00:00:00 2001 From: Max Clayton Clowes Date: Mon, 12 Oct 2026 22:01:22 +0100 Subject: [PATCH 04/10] Chore: Add Vercel Web Analytics Refs mcclowes/traction#10 --- package-lock.json | 43 +++++++++++++++++++++++++++++++++++++++++++ package.json | 1 + src/theme/Root.tsx | 6 ++++++ 3 files changed, 50 insertions(+) create mode 100644 src/theme/Root.tsx diff --git a/package-lock.json b/package-lock.json index d43e41f..f8b959c 100644 --- a/package-lock.json +++ b/package-lock.json @@ -12,6 +12,7 @@ "@docusaurus/core": "^3.10.1", "@docusaurus/preset-classic": "^3.10.1", "@mdx-js/react": "^3.0.0", + "@vercel/analytics": "^2.0.1", "clsx": "^2.1.0", "docusaurus-plugin-banner": "^0.4.0", "docusaurus-plugin-cookie-consent": "^4.6.0", @@ -6229,6 +6230,48 @@ "integrity": "sha512-60YRaenCQcVjYEKOcG824+DRGGIQ3VKErcBoAEDJZz5bKIs2ZG+X/H9Nk+Q6EVkwJk5QNApxbrc5QtBSwtrXAg==", "license": "ISC" }, + "node_modules/@vercel/analytics": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/@vercel/analytics/-/analytics-2.0.1.tgz", + "integrity": "sha512-MTQG6V9qQrt1tsDeF+2Uoo5aPjqbVPys1xvnIftXSJYG2SrwXRHnqEvVoYID7BTruDz4lCd2Z7rM1BdkUehk2g==", + "license": "MIT", + "peerDependencies": { + "@remix-run/react": "^2", + "@sveltejs/kit": "^1 || ^2", + "next": ">= 13", + "nuxt": ">= 3", + "react": "^18 || ^19 || ^19.0.0-rc", + "svelte": ">= 4", + "vue": "^3", + "vue-router": "^4" + }, + "peerDependenciesMeta": { + "@remix-run/react": { + "optional": true + }, + "@sveltejs/kit": { + "optional": true + }, + "next": { + "optional": true + }, + "nuxt": { + "optional": true + }, + "react": { + "optional": true + }, + "svelte": { + "optional": true + }, + "vue": { + "optional": true + }, + "vue-router": { + "optional": true + } + } + }, "node_modules/@webassemblyjs/ast": { "version": "1.14.1", "resolved": "https://registry.npmjs.org/@webassemblyjs/ast/-/ast-1.14.1.tgz", diff --git a/package.json b/package.json index f2d67b5..e1b1290 100644 --- a/package.json +++ b/package.json @@ -25,6 +25,7 @@ "@docusaurus/core": "^3.10.1", "@docusaurus/preset-classic": "^3.10.1", "@mdx-js/react": "^3.0.0", + "@vercel/analytics": "^2.0.1", "clsx": "^2.1.0", "docusaurus-plugin-banner": "^0.4.0", "docusaurus-plugin-cookie-consent": "^4.6.0", diff --git a/src/theme/Root.tsx b/src/theme/Root.tsx new file mode 100644 index 0000000..2a410a3 --- /dev/null +++ b/src/theme/Root.tsx @@ -0,0 +1,6 @@ +import React, { type ReactNode } from "react"; +import { Analytics } from "@vercel/analytics/react"; + +export default function Root({ children }: { children: ReactNode }) { + return <>{children}; +} From 02d7ab29fe0eab550a4cd2527b13037cb7579e42 Mon Sep 17 00:00:00 2001 From: Max Clayton Clowes Date: Tue, 13 Oct 2026 00:32:53 +0100 Subject: [PATCH 05/10] Chore: Restore plugin docs formatting and nested examples --- .github/dependabot.yml | 10 +++++----- .saggar/project.json | 4 ++-- docs/marginalia/advanced/theming.md | 28 ++++++++++++++-------------- docs/marginalia/configuration.md | 4 ++-- docs/marginalia/getting-started.md | 2 +- docs/mcp/advanced/openapi.md | 8 ++++---- docs/mcp/configuration.md | 20 ++++++++++---------- docs/mcp/overview.md | 14 +++++++------- docs/omg/advanced/renderers.md | 2 +- docs/omg/advanced/source-layout.md | 4 ++-- docs/omg/getting-started.md | 9 +++++---- src/theme/Root.tsx | 11 ++++++++--- 12 files changed, 61 insertions(+), 55 deletions(-) diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 6fd0c7f..388c5bb 100644 --- a/.github/dependabot.yml +++ b/.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'] diff --git a/.saggar/project.json b/.saggar/project.json index a5311f6..3cb9717 100644 --- a/.saggar/project.json +++ b/.saggar/project.json @@ -1,3 +1,3 @@ { - "name" : "Docusaurus plugins docs" -} \ No newline at end of file + "name": "Docusaurus plugins docs" +} diff --git a/docs/marginalia/advanced/theming.md b/docs/marginalia/advanced/theming.md index 66734a4..d912fd1 100644 --- a/docs/marginalia/advanced/theming.md +++ b/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 diff --git a/docs/marginalia/configuration.md b/docs/marginalia/configuration.md index 3e20c92..52b65b1 100644 --- a/docs/marginalia/configuration.md +++ b/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`. | ## `` diff --git a/docs/marginalia/getting-started.md b/docs/marginalia/getting-started.md index fa45bbe..9a6a872 100644 --- a/docs/marginalia/getting-started.md +++ b/docs/marginalia/getting-started.md @@ -33,7 +33,7 @@ import { Marginalia, Aside, Endpoint } from '@theme/Marginalia'; -The concept of has shaped software thinking. +The concept of has shaped software thinking. Request a session with . diff --git a/docs/mcp/advanced/openapi.md b/docs/mcp/advanced/openapi.md index a3a83d7..5aa655b 100644 --- a/docs/mcp/advanced/openapi.md +++ b/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 diff --git a/docs/mcp/configuration.md b/docs/mcp/configuration.md index 486e471..5c1217c 100644 --- a/docs/mcp/configuration.md +++ b/docs/mcp/configuration.md @@ -5,16 +5,16 @@ title: Configuration # Configuration -| Option | Type | Default | Description | -| --------------------------------- | -------------------------- | -------------------- | ------------------------------------------------------------------------ | -| `server.name` / `server.version` | `string` | site title / `0.0.0` | Identity reported to MCP clients. | -| `instructions` | `string` | — | One-line steer shown to the model on connect. | -| `docsDir` | `string` | `docs` | Docs source dir, relative to the site. | -| `routeBasePath` | `string` | `/` | Route base path your docs are served under. Used to build real page URLs. | -| `openapi` | `{ name, spec }[]` | `[]` | Specs to index. `spec` is a JSON or YAML path relative to the site. See [OpenAPI](./advanced/openapi.md). | -| `exclude` | `string[]` | `[]` | Substrings; any source-relative doc path containing one is skipped. | -| `outputDir` | `string` | `mcp` | Snapshot location, relative to the build `outDir`. | -| `endpoint` | `string` | `/mcp` | Default endpoint path for the CLI server. | +| Option | Type | Default | Description | +| -------------------------------- | ------------------ | -------------------- | --------------------------------------------------------------------------------------------------------- | +| `server.name` / `server.version` | `string` | site title / `0.0.0` | Identity reported to MCP clients. | +| `instructions` | `string` | — | One-line steer shown to the model on connect. | +| `docsDir` | `string` | `docs` | Docs source dir, relative to the site. | +| `routeBasePath` | `string` | `/` | Route base path your docs are served under. Used to build real page URLs. | +| `openapi` | `{ name, spec }[]` | `[]` | Specs to index. `spec` is a JSON or YAML path relative to the site. See [OpenAPI](./advanced/openapi.md). | +| `exclude` | `string[]` | `[]` | Substrings; any source-relative doc path containing one is skipped. | +| `outputDir` | `string` | `mcp` | Snapshot location, relative to the build `outDir`. | +| `endpoint` | `string` | `/mcp` | Default endpoint path for the CLI server. | ## Examples diff --git a/docs/mcp/overview.md b/docs/mcp/overview.md index ef6291b..6fb94a5 100644 --- a/docs/mcp/overview.md +++ b/docs/mcp/overview.md @@ -26,13 +26,13 @@ Docusaurus sites usually deploy as static files, which can't serve a live endpoi The server exposes six read-only tools: -| Tool | Description | -| --------------------- | ------------------------------------------------------------------------ | -| `search_docs` | Full-text search the docs. Returns URL, title, category, snippet. | -| `read_doc` | Full markdown of a page by URL. | -| `list_doc_categories` | Categories with page counts. | -| `list_apis` | The indexed OpenAPI specs with versions and counts. | -| `search_api` | Search operations and webhook events by path, name, summary, or tag. | +| Tool | Description | +| --------------------- | -------------------------------------------------------------------------------- | +| `search_docs` | Full-text search the docs. Returns URL, title, category, snippet. | +| `read_doc` | Full markdown of a page by URL. | +| `list_doc_categories` | Categories with page counts. | +| `list_apis` | The indexed OpenAPI specs with versions and 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, `$ref`s resolved. | The three `*_api` tools only appear when you configure [`openapi`](./advanced/openapi.md). Everything is read-only. diff --git a/docs/omg/advanced/renderers.md b/docs/omg/advanced/renderers.md index 1512274..5be0303 100644 --- a/docs/omg/advanced/renderers.md +++ b/docs/omg/advanced/renderers.md @@ -81,7 +81,7 @@ If you just want a single embeddable page without another plugin, drop a Swagger SwaggerUIBundle({ url: '/api/todo.yaml', dom_id: '#swagger-ui', - }) + }); diff --git a/docs/omg/advanced/source-layout.md b/docs/omg/advanced/source-layout.md index b752fed..efb693f 100644 --- a/docs/omg/advanced/source-layout.md +++ b/docs/omg/advanced/source-layout.md @@ -27,7 +27,7 @@ Three conventional folders: ## Endpoint anatomy -```md title="endpoints/list-todos.omg.md" +````md title="endpoints/list-todos.omg.md" --- method: GET path: /todos @@ -53,7 +53,7 @@ Returns all todos, optionally filtered by completion status. completed: boolean }] ``` -``` +```` A few things to notice: diff --git a/docs/omg/getting-started.md b/docs/omg/getting-started.md index 9522c86..cea65ea 100644 --- a/docs/omg/getting-started.md +++ b/docs/omg/getting-started.md @@ -19,15 +19,15 @@ Add the plugin to `docusaurus.config.ts` (or `.js`) with one or more `apis` entr ```ts // docusaurus.config.ts -import type { PluginOmgOptions } from 'docusaurus-plugin-omg' +import type { PluginOmgOptions } from 'docusaurus-plugin-omg'; const omgOptions: PluginOmgOptions = { apis: [{ id: 'todo', input: 'api/todo/api.omg.md' }], -} +}; export default { plugins: [['docusaurus-plugin-omg', omgOptions]], -} +}; ``` After `docusaurus build` (or `docusaurus start`) the compiled spec lands at `static/api/todo.yaml` and is served at `/api/todo.yaml` at runtime. @@ -50,7 +50,7 @@ A tiny demo API. Add an endpoint at `api/todo/endpoints/list-todos.omg.md`: -```md title="api/todo/endpoints/list-todos.omg.md" +````md title="api/todo/endpoints/list-todos.omg.md" --- method: GET path: /todos @@ -69,6 +69,7 @@ Returns all todos. completed: boolean }] ``` +```` Run `npm start` — the plugin compiles on the fly, and `/api/todo.yaml` updates as you save. diff --git a/src/theme/Root.tsx b/src/theme/Root.tsx index 2a410a3..9e19ca8 100644 --- a/src/theme/Root.tsx +++ b/src/theme/Root.tsx @@ -1,6 +1,11 @@ -import React, { type ReactNode } from "react"; -import { Analytics } from "@vercel/analytics/react"; +import React, { type ReactNode } from 'react'; +import { Analytics } from '@vercel/analytics/react'; export default function Root({ children }: { children: ReactNode }) { - return <>{children}; + return ( + <> + {children} + + + ); } From df8fee7404df8881ee577ef81a001ea10704ed60 Mon Sep 17 00:00:00 2001 From: Max Clayton Clowes Date: Tue, 13 Oct 2026 00:39:41 +0100 Subject: [PATCH 06/10] Chore: Migrate the deprecated Markdown link setting --- docusaurus.config.ts | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docusaurus.config.ts b/docusaurus.config.ts index d6fe02b..b8be338 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -11,7 +11,11 @@ const config: Config = { organizationName: 'mcclowes', projectName: 'docusaurus-plugins-docs', onBrokenLinks: 'warn', - onBrokenMarkdownLinks: 'warn', + markdown: { + hooks: { + onBrokenMarkdownLinks: 'warn', + }, + }, i18n: { defaultLocale: 'en', locales: ['en'] }, From 5e79990b94d0085ade054b30a3521b40806f6ec5 Mon Sep 17 00:00:00 2001 From: Max Clayton Clowes Date: Tue, 13 Oct 2026 11:43:12 +0100 Subject: [PATCH 07/10] Chore: Document selection sharing keyboard access Refs #53 --- docs/share-selection/getting-started.md | 10 ++++++++++ docs/share-selection/overview.md | 1 + 2 files changed, 11 insertions(+) diff --git a/docs/share-selection/getting-started.md b/docs/share-selection/getting-started.md index 0549a39..2bb1045 100644 --- a/docs/share-selection/getting-started.md +++ b/docs/share-selection/getting-started.md @@ -23,6 +23,16 @@ That's enough. Highlight three or more words on a docs page, blog post, or MDX p Selections inside code blocks are ignored, because code blocks already have a copy button. +## Use the keyboard + +:::note Upcoming release +The shortcut below requires the upcoming keyboard-access release of the plugin. +::: + +Select a passage with Shift and the arrow keys using your browser's caret browsing mode. When the palette appears, press **Alt+Shift+S** (**Option+Shift+S** on macOS) to focus its first action. + +Use **Tab** to move between actions and **Enter** to activate one. **Escape** closes the palette and returns focus to the selected passage, so you can continue reading. + ## Try the deep link Copy a passage, then open the link from the clipboard in a new tab. The page scrolls to the passage and highlights it. diff --git a/docs/share-selection/overview.md b/docs/share-selection/overview.md index ab39070..90cad0e 100644 --- a/docs/share-selection/overview.md +++ b/docs/share-selection/overview.md @@ -14,6 +14,7 @@ Highlight text on a page and a small palette appears above it. Readers can copy - Links combine the nearest heading anchor with a text fragment (`#setup:~:text=...`), so the reader lands on the passage with it highlighted. Browsers without text fragment support still land on the heading. - **Ask AI** sends the passage along with its heading path and the text around it, so the model knows what the reader means. - Custom actions turn a selection into any URL, such as a pre-filled "Report an issue with this passage" form. +- The upcoming release adds [keyboard access](./getting-started.md#use-the-keyboard): **Alt+Shift+S** focuses the palette, and **Escape** returns to the selected passage. ## How it works From ad35d443a7cf0ae8397acf4c2fbfad6a544e7d45 Mon Sep 17 00:00:00 2001 From: Max Clayton Clowes Date: Wed, 14 Oct 2026 17:56:20 +0100 Subject: [PATCH 08/10] Chore: Link selection-sharing example development guide --- docs/share-selection/getting-started.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/share-selection/getting-started.md b/docs/share-selection/getting-started.md index 2bb1045..6892f05 100644 --- a/docs/share-selection/getting-started.md +++ b/docs/share-selection/getting-started.md @@ -23,6 +23,10 @@ That's enough. Highlight three or more words on a docs page, blog post, or MDX p Selections inside code blocks are ignored, because code blocks already have a copy button. +## Try the example site + +The repository includes a [Docusaurus example site](https://github.com/mcclowes/docusaurus-plugin-share-selection/tree/main/examples/docusaurus-v3). Follow the [development instructions](https://github.com/mcclowes/docusaurus-plugin-share-selection#development) to install and run it locally. + ## Use the keyboard :::note Upcoming release From ec5c89072c8f55afbe38bfd3161764a674cf150b Mon Sep 17 00:00:00 2001 From: Max Clayton Clowes Date: Wed, 14 Oct 2026 19:15:45 +0100 Subject: [PATCH 09/10] Chore: clarify manual glossary route precedence Refs mcclowes/docusaurus-plugin-glossary#179 --- docs/glossary/component.md | 4 ++++ docs/glossary/configuration.md | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/docs/glossary/component.md b/docs/glossary/component.md index ce5ba08..708e03b 100644 --- a/docs/glossary/component.md +++ b/docs/glossary/component.md @@ -49,6 +49,10 @@ We use ## 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`, `` 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` diff --git a/docs/glossary/configuration.md b/docs/glossary/configuration.md index 6119291..2e03591 100644 --- a/docs/glossary/configuration.md +++ b/docs/glossary/configuration.md @@ -19,6 +19,10 @@ 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 `` 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. + ## Glossary JSON schema ```ts From 4bd20b5a8fe3947554e182dd790aa108b00c9758 Mon Sep 17 00:00:00 2001 From: Max Clayton Clowes Date: Wed, 14 Oct 2026 19:54:42 +0100 Subject: [PATCH 10/10] Chore: document glossary anchor validation requirements Refs mcclowes/docusaurus-plugin-glossary#180 --- docs/glossary/configuration.md | 6 ++++++ docs/glossary/getting-started.md | 2 ++ docs/glossary/overview.md | 3 ++- 3 files changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/glossary/configuration.md b/docs/glossary/configuration.md index 2e03591..8c58a7c 100644 --- a/docs/glossary/configuration.md +++ b/docs/glossary/configuration.md @@ -23,6 +23,12 @@ Manual `` links to glossary entries inherit the default plugin ins 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 diff --git a/docs/glossary/getting-started.md b/docs/glossary/getting-started.md index b151a64..5b0de54 100644 --- a/docs/glossary/getting-started.md +++ b/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: diff --git a/docs/glossary/overview.md b/docs/glossary/overview.md index 7e3ef3b..f957315 100644 --- a/docs/glossary/overview.md +++ b/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