README.md

@open-rpc/docusaurus-plugin

A Docusaurus plugin for generating documentation from OpenRPC specifications.

Installation

npm install @open-rpc/docusaurus-plugin

Usage

Add the plugin to the plugins section of your docusaurus.config.ts:

plugins: [
  [
    "@open-rpc/docusaurus-plugin",
    {
      openRPCSpecPath: "./path/to/openrpc.json",
      docOutputPath: "./docs/api-reference",
    },
  ],
];

Options

Option	Type	Default	Description
openRPCSpecPath	string	./openrpc.json	Path to the OpenRPC JSON specification file
docOutputPath	string	./api-reference	Output directory for generated documentation
showPoweredBy	boolean	true	Show "Powered by OpenRPC" footer on index page

Sidebar Configuration

There are several ways to configure your sidebar to display the generated API documentation.

Option A: Simple autogenerated (default)

Creates a dedicated sidebar that auto-generates entries from all docs:

// sidebars.ts
import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";

const sidebars: SidebarsConfig = {
  apiSidebar: [{ type: "autogenerated", dirName: "." }],
};

export default sidebars;

Option B: Category wrapper with autogenerated content

Embeds the API reference as a collapsible category within an existing sidebar:

// sidebars.ts
import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";

const sidebars: SidebarsConfig = {
  mainSidebar: [
    // Your other sidebar items...
    {
      type: "category",
      label: "API Reference",
      link: { type: "generated-index" },
      items: [
        {
          type: "autogenerated",
          dirName: "api-reference",
        },
      ],
    },
  ],
};

export default sidebars;

Components

The plugin exports React components for use in MDX files. Import them from @open-rpc/docusaurus-plugin/components:

import {
  TwoColumnLayout,
  InteractiveRequest,
  RequestExample,
  ResponseExample,
} from "@open-rpc/docusaurus-plugin/components";

Development

This plugin uses Bun for development.

# Build the plugin
bun run build

# Watch mode for development
bun run dev:watch

We also use the example-site and bun watch called from the root of the project to develop the plugin and see the results in the example site