open-rpc · zcstarr · May 22, 2026 · May 22, 2026 · May 22, 2026 · May 22, 2026
diff --git a/bun.lock b/bun.lock
diff --git a/package.json b/package.json
@@ -24,29 +24,29 @@
     "ci:publish": "for dir in packages/markdown-generator packages/docusaurus-plugin; do (cd \"$dir\" && bun publish --access public || true); done && changeset tag"
   },
   "devDependencies": {
-    "@changesets/cli": "^2.29.8",
-    "@eslint/js": "^9.39.3",
-    "@types/bun": "^1.3.9",
+    "@changesets/cli": "2.29.8",
+    "@eslint/js": "9.39.3",
+    "@types/bun": "1.3.9",
     "@types/node": "22.13.5",
-    "@typescript-eslint/eslint-plugin": "^8.56.1",
-    "@typescript-eslint/parser": "^8.56.1",
-    "eslint": "^9.39.3",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-prettier": "^5.5.5",
-    "globals": "^16.5.0",
-    "typescript": "~5.9.3"
+    "@typescript-eslint/eslint-plugin": "8.56.1",
+    "@typescript-eslint/parser": "8.56.1",
+    "eslint": "9.39.3",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-plugin-prettier": "5.5.5",
+    "globals": "16.5.0",
+    "typescript": "5.9.3"
   },
   "dependencies": {
-    "@json-schema-tools/traverse": "^1.11.0",
-    "@open-rpc/examples": "^1.7.2",
-    "@open-rpc/schema-utils-js": "^2.2.1",
-    "@open-rpc/spec-types": "^0.0.2",
-    "mdast": "^3.0.0",
-    "mdast-util-gfm": "^3.1.0",
-    "mdast-util-mdx": "^3.0.0",
-    "mdast-util-to-markdown": "^2.1.2",
-    "remark-gfm": "^4.0.1",
-    "remark-stringify": "^11.0.0",
-    "unified": "^11.0.5"
+    "@json-schema-tools/traverse": "1.11.0",
+    "@open-rpc/examples": "1.7.2",
+    "@open-rpc/schema-utils-js": "2.2.1",
+    "@open-rpc/spec-types": "0.0.2",
+    "mdast": "3.0.0",
+    "mdast-util-gfm": "3.1.0",
+    "mdast-util-mdx": "3.0.0",
+    "mdast-util-to-markdown": "2.1.2",
+    "remark-gfm": "4.0.1",
+    "remark-stringify": "11.0.0",
+    "unified": "11.0.5"
   }
-}
+}
diff --git a/packages/docusaurus-plugin/package.json b/packages/docusaurus-plugin/package.json
@@ -27,11 +27,11 @@
   },
   "devDependencies": {
     "@docusaurus/types": "3.9.2",
-    "@types/react": "^19.2.4",
-    "@types/react-dom": "^19.2.3"
+    "@types/react": "19.2.4",
+    "@types/react-dom": "19.2.3"
   },
   "peerDependencies": {
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0"
+    "react": "19.2.0",
+    "react-dom": "19.2.0"
   }
-}
+}
diff --git a/packages/docusaurus-plugin/src/lib.ts b/packages/docusaurus-plugin/src/lib.ts
@@ -6,6 +6,7 @@ import {
   identitySchemaEdits,
   renderMethodsToMarkdown,
   renderIndex,
+  tagPermalinkPrefixForDocsRoute,
 } from "@open-rpc/markdown-generator";
 import type {
   DereffedMethodObject,
@@ -84,7 +85,8 @@ export async function cleanUpExistingDocs(specPath: string, outputDir: string) {
       (entry) =>
         entry.isFile() &&
         methodFileNamesToGenerate.has(entry.name) === false &&
-        entry.name !== "index.md",
+        entry.name !== "index.md" &&
+        entry.name !== "index.mdx",
     )
     .map((entry) => `${entry.parentPath}/${entry.name}`);
 
@@ -127,13 +129,21 @@ export async function generateDocs(
     additionalFrontmatter["slug"] = options.indexSlug;
   }
 
-  const indexContent = renderIndex(doc, "mdx", additionalFrontmatter);
+  const indexContent = renderIndex(
+    doc,
+    "mdx",
+    additionalFrontmatter,
+    tagPermalinkPrefixForDocsRoute(options.docsRouteBasePath),
+  );
   const finalIndex =
     options.showPoweredBy === true
       ? `${indexContent}\n---\n\n*Powered by [OpenRPC](https://open-rpc.org)*\n`
       : indexContent;
 
-  await fs.writeFile(path.join(outDir, "index.md"), finalIndex, "utf8");
+  // Drop any legacy .md index before writing .mdx so Docusaurus doesn't see
+  // two route candidates with the same slug.
+  await fs.rm(path.join(outDir, "index.md"), { force: true });
+  await fs.writeFile(path.join(outDir, "index.mdx"), finalIndex, "utf8");
 }
 
 /* ---------- Renderers ---------- */

diff --git a/packages/docusaurus-plugin/src/options.ts b/packages/docusaurus-plugin/src/options.ts
@@ -6,6 +6,8 @@ export type Options = {
   docOutputPath: string;
   showPoweredBy: boolean;
   indexSlug: string | undefined;
+  /** Docusaurus docs routeBasePath (default preset: "docs"). */
+  docsRouteBasePath?: string;
 };
 
 /**
@@ -25,5 +27,6 @@ export function normalizeOptions(options: Options): PluginOptions {
     showPoweredBy:
       options.showPoweredBy === undefined ? true : options.showPoweredBy,
     indexSlug: options.indexSlug === undefined ? undefined : options.indexSlug,
+    docsRouteBasePath: options.docsRouteBasePath ?? "docs",
   };
 }
diff --git a/.../example-site/docs/api-reference/index.md → ...example-site/docs/api-reference/index.mdx b/.../example-site/docs/api-reference/index.md → ...example-site/docs/api-reference/index.mdx
@@ -3,7 +3,6 @@
 title: "Ethereum JSON-RPC Specification"
 description: "A specification of the standard interface for Ethereum clients."
 
-
 ---
 
 # Ethereum JSON-RPC Specification
@@ -79,6 +78,10 @@ A specification of the standard interface for Ethereum clients.
 - [`eth_syncing`](./methods/eth_syncing.mdx)
 - [`eth_uninstallFilter`](./methods/eth_uninstallFilter.mdx)
 
+import TagsListInline from '@theme/TagsListInline';
+
+<TagsListInline tags={[{label: "client", permalink: "/docs/tags/client"}]} />
+
 ---
 
 *Powered by [OpenRPC](https://open-rpc.org)*
diff --git a/packages/example-site/docs/api-reference/methods/eth_chainId.mdx b/packages/example-site/docs/api-reference/methods/eth_chainId.mdx
@@ -3,6 +3,8 @@
 title: "eth_chainId"
 hide_table_of_contents: true
 description: ""
+tags:
+  - client
 ---
 
 import {TwoColumnLayout, InteractiveRequest, ResponseExample} from '@open-rpc/docusaurus-plugin/components';

diff --git a/packages/example-site/error-group-openrpc.json b/packages/example-site/error-group-openrpc.json
@@ -5598,6 +5598,11 @@
 		{
 			"name": "eth_chainId",
 			"summary": "Returns the chain ID of the current network.",
+			"tags": [
+				{
+					"name": "client"
+				}
+			],
 			"params": [],
 			"result": {
 				"name": "Chain ID",

diff --git a/packages/example-site/package.json b/packages/example-site/package.json
@@ -19,17 +19,17 @@
     "@open-rpc/docusaurus-plugin": "workspace:*",
     "@docusaurus/core": "3.9.2",
     "@docusaurus/preset-classic": "3.9.2",
-    "@mdx-js/react": "^3.0.0",
-    "clsx": "^2.0.0",
-    "prism-react-renderer": "^2.3.0",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0"
+    "@mdx-js/react": "3.1.1",
+    "clsx": "2.1.1",
+    "prism-react-renderer": "2.4.1",
+    "react": "19.2.0",
+    "react-dom": "19.2.0"
   },
   "devDependencies": {
     "@docusaurus/module-type-aliases": "3.9.2",
     "@docusaurus/tsconfig": "3.9.2",
     "@docusaurus/types": "3.9.2",
-    "typescript": "~5.6.2"
+    "typescript": "5.9.3"
   },
   "browserslist": {
     "production": [
@@ -46,4 +46,4 @@
   "engines": {
     "node": ">=20.0"
   }
-}
+}
diff --git a/packages/markdown-generator/README.md b/packages/markdown-generator/README.md
@@ -30,6 +30,13 @@ Writes markdown files directly to disk for each method, plus an `index.md`. The
 
 Generates an index markdown string listing all methods with links. Returns the markdown as a string.
 
+The index intentionally does **not** aggregate method tags into its YAML frontmatter—that previously made the index doc appear under every `/tags/*` listing in Docusaurus. Instead, when at least one method has tags, the index appends an inline tag strip after the methods list:
+
+- For `"mdx"` output, it emits `<TagsListInline>` (Docusaurus theme component) so the chips match the standard `tags:` row visually.
+- For `"md"` output, it emits a `**Tags:** [name](./tags/<slug>) · ...` fallback line.
+
+When no methods carry tags, no tag block is emitted at all. Tag links must use **absolute** permalinks such as `/docs/tags/<slug>` — Docusaurus registers tag list pages at `<routeBasePath>/tags/<slug>`, and relative paths like `../tags/<slug>` are resolved by `@docusaurus/Link` to `/tags/<slug>` (404). Pass `tagPermalinkPrefixForDocsRoute("docs")` as the fourth argument to `renderIndex` (the Docusaurus plugin does this automatically). Write the index as `.mdx` when using `<TagsListInline>`. Tag pages list method docs that carry matching `tags:` frontmatter; add `docs/tags.yml` entries if you want tag descriptions on the tag page.
+
 ### `identityEdits` / `identitySchemaEdits`
 
 Default edit functions that pass content through unchanged. Use these as a starting point when creating custom edits.

diff --git a/packages/markdown-generator/package.json b/packages/markdown-generator/package.json
@@ -30,22 +30,22 @@
     "build": "bun build.ts && bun run types"
   },
   "devDependencies": {
-    "@types/bun": "^1.3.1",
+    "@types/bun": "1.3.9",
     "@types/node": "22.13.5",
-    "typescript": "5.9",
-    "@typescript-eslint/eslint-plugin": "^8.46.2",
-    "eslint": "^9.38.0",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-prettier": "^5.5.4"
+    "typescript": "5.9.3",
+    "@typescript-eslint/eslint-plugin": "8.56.1",
+    "eslint": "9.39.3",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-plugin-prettier": "5.5.5"
   },
   "dependencies": {
     "@open-rpc/schema-utils-js": "2.2.1",
-    "@types/mdast": "^4.0.4",
-    "mdast-util-from-markdown": "^2.0.2",
-    "mdast-util-frontmatter": "^2.0.1",
-    "mdast-util-gfm": "^3.1.0",
-    "mdast-util-mdx": "^3.0.0",
-    "mdast-util-to-markdown": "^2.1.0",
-    "micromark-extension-gfm": "^3.0.0"
+    "@types/mdast": "4.0.4",
+    "mdast-util-from-markdown": "2.0.2",
+    "mdast-util-frontmatter": "2.0.1",
+    "mdast-util-gfm": "3.1.0",
+    "mdast-util-mdx": "3.0.0",
+    "mdast-util-to-markdown": "2.1.2",
+    "micromark-extension-gfm": "3.0.0"
   }
-}
+}