@khannanov-nil/openrpc-docusaurus

Docusaurus OpenRPC Plugin

A Docusaurus plugin for OpenRPC.

Installation

npm install @metamask/docusaurus-openrpc

Usage

There are two ways to use this plugin:

1. Create a separate, standalone sidebar

Creates its own sidebar and path for the JSON-RPC method documentation.

Add the following in the plugins section of your docusaurus.config.js file:

[
  '@metamask/docusaurus-openrpc',
  {
    path: '/api-playground',
    openrpcDocument: './path/to/openrpc.json', // path or url to openrpc document.
  },
];

2. Integrate into the existing sidebar

Embeds the JSON-RPC method docs sidebar entries into your existing Docusaurus sidebar. You can configure this in your sidebar.js file.

If you are using the @docusaurus/preset-classic then make the following changes in the presets section of your docusaurus.config.js file. You should also add a sidebar entry in the sidebars.js file, as described below:

1. Replace "@docusaurus/preset-classic" with "@metamask/docusaurus-openrpc/dist/preset".

2. Replace /** @type {import("@docusaurus/preset-classic").Options} */ with /** @type {import('@metamask/docusaurus-openrpc/dist/preset').Options} */.

3. In the docs: { section add the openrpc configuration with the fields shown below.

   • The openrpcDocument field is the Docusaurus path to your OpenRPC JSON spec. You can also use the URL format, for example: openrpcDocument: "https://metamask.github.io/api-specs/latest/openrpc.json",.
   • The path field is the name of the category directory in your Docusaurus docs. For example, reference will build your JSON-RPC docs in docs/reference Docusuarus directory. NOTE: You must have at least one Markdown file in this directory.

   See below:

     presets: [
         [
           "@metamask/docusaurus-openrpc/dist/preset",
           /** @type {import('@metamask/docusaurus-openrpc/dist/preset').Options} */
           {
             docs: {
                     ...
               openrpc: {
                           openrpcDocument: "./docs/refs-openrpc.json",
                           path: "reference",
                           sidebarLabel: "JSON-RPC",
                         },
                       },
                       theme: {
                         customCss: require.resolve("./src/css/custom.css"),
           ...

4. In the sidebars.js file, add the following entry:

     {
        type: "category",
        label: "Reference",
        link: { type: "generated-index" },
        items: [
          {
            type: "autogenerated",
            dirName: "reference",
          }
        ],
      },

This will create a sidebar category entry Reference > in your existing Docusaurus sidebar. The Reference > category will contain JSON-RPC sub-category with the JSON-RPC method entries. IMPORTANT: You must have at least one Markdown file in the docs/reference Docusuarus directory for Docusaurus to autogenerate the sidebar entries for the Reference category.

Development

In development, you can use yarn link in this repo, then run yarn link "@metamask/docusaurus-openrpc" in your project (metamask-docs, for example). Finally, run yarn build:watch in this repo to rebuild the plugin as you make changes.