@metamask/docusaurus-openrpc

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:

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

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

• 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"),
          ...
  
  

• 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.