OpenRPC Markdown Documentation Tools

Generate API documentation from OpenRPC specifications.

Overview

This monorepo provides tools for turning OpenRPC JSON specifications into markdown documentation. Use it standalone with the CLI, or integrate directly with Docusaurus for an interactive documentation site.

┌─────────────────┐     ┌──────────────────────┐     ┌─────────────────────┐
│  OpenRPC JSON   │ ──► │  markdown-generator  │ ──► │   Markdown / MDX    │
│  Specification  │     │                      │     │   Documentation     │
└─────────────────┘     └──────────────────────┘     └─────────────────────┘
                                   │
                                   ▼
                        ┌──────────────────────┐
                        │  docusaurus-plugin   │
                        │  (interactive docs)  │
                        └──────────────────────┘

Key Features:

• JSON Schema rendering
• Method parameters, results, and errors documentation
• Request/response examples with syntax highlighting
• Customizable output via mdast edit hooks
• Docusaurus plugin with two-column layout and interactive components

Packages

Package	Description	Docs
@open-rpc/markdown-generator	Core library and CLI for markdown generation	README
@open-rpc/docusaurus-plugin	Docusaurus plugin with interactive components	README
example-site	Demo Docusaurus site for testing	README

Repo Test Website

Quick Start

Option 1: CLI

Generate markdown files directly from any OpenRPC specification:

# Install globally
npm install -g @open-rpc/markdown-generator

# Generate MDX files
openrpc-md ./openrpc.json -m ./docs/api

# Generate plain Markdown
openrpc-md ./openrpc.json -m ./docs/api -t md

See the markdown-generator README for CLI options and programmatic API.

Option 2: Docusaurus Plugin

For Docusaurus sites, use the plugin for automatic generation with interactive components:

1. Install the plugin:

npm install @open-rpc/docusaurus-plugin

2. Add to docusaurus.config.ts:

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

3. Configure sidebar in sidebars.ts:

const sidebars = {
  apiSidebar: [
    {
      type: "category",
      label: "API Reference",
      items: [{ type: "autogenerated", dirName: "api-reference" }],
    },
  ],
};

See the docusaurus-plugin README for configuration options and component exports.

Development

This project uses Bun as its JavaScript runtime and package manager.

Prerequisites

# Install Bun
curl -fsSL https://bun.sh/install | bash

Setup

# Install dependencies (also builds packages via postinstall)
bun install

Commands

# Run tests
bun test

# Build all packages
bun run build:all

# Type check all packages
bun run types:all

# Lint
bun run lint
bun run lint:fix

Watch Mode

For development with live reloading:

# From repo root - watches and rebuilds on changes
bun watch.ts

This watches the markdown-generator and docusaurus-plugin packages, rebuilding them when source files change. The example site will hot-reload with the updates.

Testing Changes

The example-site package provides a Docusaurus site for testing:

cd packages/example-site
bun start

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run bun test and bun run lint
5. Submit a pull request

This repo uses Changesets for versioning. Add a changeset for your changes:

bun changeset

License

Apache 2.0