feat: Create Snaps API documentation from generated schema

.github/workflows/ci.yml

@@ -4,7 +4,7 @@ name: ci
 on:
   workflow_call:
   pull_request:
-    branches: 
+    branches:
       - main
 
 permissions:
@@ -63,6 +63,14 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
+      - name: Use Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: '.nvmrc'
+      - name: Install dependencies
+        run: npm ci
+      - name: Generate docs
+        run: npm run docusaurus snaps:generate
       - name: LinkCheck
         uses: ConsenSys/github-actions/docs-link-check@main
         with:

.gitignore

@@ -22,4 +22,7 @@ npm-debug.log*
 .vercel
 .envrc
 .env
-.integrationBuilderCache
+.integrationBuilderCache
+
+# Generated Snaps docs
+snaps/reference/snaps-api/*.mdx

docusaurus.config.js

@@ -179,6 +179,7 @@ const config = {
     './src/plugins/docusaurus-plugin-tutorials',
     'docusaurus-plugin-sass',
     './src/plugins/mm-scss-utils',
+    './src/plugins/plugin-snaps-docs.ts',
     [
       '@docusaurus/plugin-content-docs',
       {
@@ -727,7 +728,17 @@ const config = {
       },
       prism: {
         theme: codeTheme,
-        additionalLanguages: ['csharp', 'gradle', 'bash', 'json', 'java', 'kotlin', 'swift', 'groovy', 'dart'],
+        additionalLanguages: [
+          'csharp',
+          'gradle',
+          'bash',
+          'json',
+          'java',
+          'kotlin',
+          'swift',
+          'groovy',
+          'dart',
+        ],
         magicComments: [
           {
             className: 'theme-code-block-highlighted-line',
@@ -803,10 +814,10 @@ const config = {
     }),
   stylesheets: [
     {
-      href: "https://cdn.jsdelivr.net/npm/katex@0.16.25/dist/katex.min.css",
-      type: "text/css",
-      integrity: "sha384-WcoG4HRXMzYzfCgiyfrySxx90XSl2rxY5mnVY5TwtWE6KLrArNKn0T/mOgNL0Mmi",
-      crossorigin: "anonymous",
+      href: 'https://cdn.jsdelivr.net/npm/katex@0.16.25/dist/katex.min.css',
+      type: 'text/css',
+      integrity: 'sha384-WcoG4HRXMzYzfCgiyfrySxx90XSl2rxY5mnVY5TwtWE6KLrArNKn0T/mOgNL0Mmi',
+      crossorigin: 'anonymous',
     },
   ],
 }

package.json

@@ -5,8 +5,8 @@
   "license": "(MIT OR Apache-2.0)",
   "scripts": {
     "docusaurus": "docusaurus",
-    "start": "docusaurus start -p 3003",
-    "build": "docusaurus build",
+    "start": "docusaurus snaps:generate && docusaurus start -p 3003",
+    "build": "docusaurus snaps:generate && docusaurus build",
     "swizzle": "docusaurus swizzle",
     "deploy": "docusaurus deploy",
     "clear": "docusaurus clear",
@@ -54,6 +54,7 @@
     "classnames": "^2.5.1",
     "clsx": "^2.1.1",
     "copy-to-clipboard": "^3.3.3",
+    "docusaurus-plugin-llms": "^0.2.2",
     "docusaurus-plugin-sass": "^0.2.5",
     "dotenv": "^17.2.1",
     "ethers": "^6.15.0",
@@ -73,6 +74,7 @@
     "react-dom": "^18.0.0",
     "react-dropdown-select": "^4.12.2",
     "react-icons": "^5.5.0",
+    "react-markdown": "^10.1.0",
     "react-modal": "^3.16.3",
     "react-player": "^3.3.1",
     "react-select": "^5.10.2",
@@ -83,8 +85,7 @@
     "remark-codesandbox": "^0.10.1",
     "remark-docusaurus-tabs": "^0.2.0",
     "remark-math": "^6.0.0",
-    "sass": "^1.93.0",
-    "docusaurus-plugin-llms": "^0.2.2"
+    "sass": "^1.93.0"
   },
   "devDependencies": {
     "@docusaurus/eslint-plugin": "3.9.2",

snaps-sidebar.js

@@ -16,38 +16,50 @@ const sidebar = {
 
   // But you can create a sidebar manually
   snapsSidebar: [
-    "index",
+    'index',
     {
-      type: "category",
-      label: "Get started",
+      type: 'category',
+      label: 'Get started',
       collapsed: false,
-      items: [{ type: "autogenerated", dirName: "get-started" }],
+      items: [{ type: 'autogenerated', dirName: 'get-started' }],
     },
     {
-      type: "category",
-      label: "Learn",
+      type: 'category',
+      label: 'Learn',
       collapsed: false,
-      items: [{ type: "autogenerated", dirName: "learn" }],
+      items: [{ type: 'autogenerated', dirName: 'learn' }],
     },
     {
-      type: "category",
-      label: "Features",
+      type: 'category',
+      label: 'Features',
       collapsed: false,
-      items: [{ type: "autogenerated", dirName: "features" }],
+      items: [{ type: 'autogenerated', dirName: 'features' }],
     },
     {
-      type: "category",
-      label: "How to",
+      type: 'category',
+      label: 'How to',
       collapsed: false,
-      items: [{ type: "autogenerated", dirName: "how-to" }],
+      items: [{ type: 'autogenerated', dirName: 'how-to' }],
     },
     {
-      type: "category",
-      label: "Reference",
+      type: 'category',
+      label: 'Reference',
       collapsed: false,
-      items: [{ type: "autogenerated", dirName: "reference" }],
+      items: [
+        {
+          type: 'category',
+          label: 'Snaps API',
+          collapsible: true,
+          collapsed: true,
+          link: { type: 'doc', id: 'reference/snaps-api/index' },
+          items: [
+            { type: 'autogenerated', dirName: 'reference/snaps-api' }
+          ],
+        },
+        { type: 'autogenerated', dirName: 'reference' },
+      ],
     },
   ],
-};
+}
 
 module.exports = sidebar;

snaps/features/cron-jobs.md

@@ -112,7 +112,7 @@ This interaction can be confusing to the user, since the Snap accesses the data
 without the user being aware.
 
 If the cron job requires access to encrypted data, use
-[`snap_getClientStatus`](../reference/snaps-api.md#snap_getclientstatus) to ensure that MetaMask is
+[`snap_getClientStatus`](../reference/snaps-api/snap_getclientstatus.mdx) to ensure that MetaMask is
 unlocked before accessing state.
 This will prevent an unexpected password request, improving the user's experience.
 

snaps/features/custom-evm-accounts/index.md

@@ -144,9 +144,9 @@ Site -->>- User: Done
 The companion dapp presents a user interface allowing the user to configure their custom account.
 The dapp creates an account using [`keyring_createAccount`](../../reference/keyring-api/account-management/index.md#keyring_createaccount).
 
-The Snap keeps track of the accounts that it creates using [`snap_manageState`](../../reference/snaps-api.md#snap_managestate).
+The Snap keeps track of the accounts that it creates using [`snap_manageState`](../../reference/snaps-api/snap_managestate.mdx).
 Once the Snap has created an account, it notifies MetaMask using
-[`snap_manageAccounts`](../../reference/snaps-api.md#snap_manageaccounts).
+[`snap_manageAccounts`](../../reference/snaps-api/snap_manageaccounts.mdx).
 
 Once the Snap has created an account, that account can be used to sign messages and transactions.
 
@@ -264,7 +264,7 @@ After approval, MetaMask calls
 [`keyring_submitRequest`](../../reference/keyring-api/account-management/index.md#keyring_submitrequest).
 
 Since the Snap doesn't answer the request directly, it stores the pending request in its internal
-state using [`snap_manageState`](../../reference/snaps-api.md#snap_managestate).
+state using [`snap_manageState`](../../reference/snaps-api/snap_managestate.mdx).
 The Snap sends a `{ pending: true, redirect? }` response to indicate that the request will be
 handled asynchronously.
 This response can optionally contain a redirect URL that MetaMask will open in a new tab to allow
@@ -274,7 +274,7 @@ The companion dapp gets the Snap's pending request using
 [`keyring_getRequest`](../../reference/keyring-api/account-management/index.md#keyring_getrequest).
 It resolves the request using
 [`keyring_approveRequest`](../../reference/keyring-api/account-management/index.md#keyring_approverequest),
-and the Snap resolves the request using [`snap_manageAccounts`](../../reference/snaps-api.md#snap_manageaccounts),
+and the Snap resolves the request using [`snap_manageAccounts`](../../reference/snaps-api/snap_manageaccounts.mdx),
 notifying MetaMask of the result.
 
 ## EOA methods

snaps/features/custom-ui/dialogs.md

@@ -6,7 +6,7 @@ sidebar_position: 2
 # Dialogs
 
 You can display a dialog in the MetaMask UI using the
-[`snap_dialog`](../../reference/snaps-api.md#snap_dialog) API method.
+[`snap_dialog`](../../reference/snaps-api/snap_dialog.mdx) API method.
 Dialogs can contain [custom UI](index.md) and [interactive UI](interactive-ui.md) components.
 
 The four types of dialogs include [alerts](#display-an-alert-dialog),
@@ -16,13 +16,13 @@ The four types of dialogs include [alerts](#display-an-alert-dialog),
 :::warning
 - Dialogs do not work when MetaMask is locked.
   To check if MetaMask is locked, use
-  [`snap_getClientStatus`](../../reference/snaps-api.md#snap_getclientstatus).
+  [`snap_getClientStatus`](../../reference/snaps-api/snap_getclientstatus.mdx).
 - [`metamask:` URLs](index.md#about-metamask-urls) are not supported in dialogs.
 :::
 
 ## Request permission to display dialogs
 
-To display dialogs, first request the [`snap_dialog`](../../reference/snaps-api.md#snap_dialog) permission.
+To display dialogs, first request the [`snap_dialog`](../../reference/snaps-api/snap_dialog.mdx) permission.
 Add the following to your Snap's manifest file:
 
 ```json title="snap.manifest.json"
@@ -34,7 +34,7 @@ Add the following to your Snap's manifest file:
 ## Display an alert dialog
 
 To display an alert that can only be acknowledged, call
-[`snap_dialog`](../../reference/snaps-api.md#snap_dialog) with `type: "alert"`.
+[`snap_dialog`](../../reference/snaps-api/snap_dialog.mdx) with `type: "alert"`.
 The following example displays custom UI that alerts the user when something happens in the system:
 
 ```tsx title="index.tsx"
@@ -63,7 +63,7 @@ await snap.request({
 ## Display a confirmation dialog
 
 To display a confirmation that can be accepted or rejected, call
-[`snap_dialog`](../../reference/snaps-api.md#snap_dialog) with `type: "confirmation"`.
+[`snap_dialog`](../../reference/snaps-api/snap_dialog.mdx) with `type: "confirmation"`.
 The following example displays custom UI that asks the user to confirm whether they would like to
 take an action:
 
@@ -95,7 +95,7 @@ if (result === true) {
 ## Display a prompt dialog
 
 To display a prompt where the user can enter a text response, call
-[`snap_dialog`](../../reference/snaps-api.md#snap_dialog) with `type: "prompt"`.
+[`snap_dialog`](../../reference/snaps-api/snap_dialog.mdx) with `type: "prompt"`.
 Prompt dialogs also accept a `placeholder` value that displays in the input field when no text is entered.
 
 The following example displays custom UI that prompts the user to enter a wallet address:
@@ -126,8 +126,8 @@ const walletAddress = await snap.request({
 
 ## Display a custom dialog
 
-To display a custom dialog, call [`snap_dialog`](../../reference/snaps-api.md#snap_dialog)
-without providing a `type`. Custom dialogs can be resolved by calling [`snap_resolveInterface`](../../reference/snaps-api.md#snap_resolveinterface). The UI passed to a custom dialog should contain a `Footer` element. Its buttons will be displayed at the bottom of the dialog. Here is a complete example:
+To display a custom dialog, call [`snap_dialog`](../../reference/snaps-api/snap_dialog.mdx)
+without providing a `type`. Custom dialogs can be resolved by calling [`snap_resolveInterface`](../../reference/snaps-api/snap_resolveinterface.mdx). The UI passed to a custom dialog should contain a `Footer` element. Its buttons will be displayed at the bottom of the dialog. Here is a complete example:
 
 ```tsx title="index.tsx"
 import {

snaps/features/custom-ui/index.md

@@ -34,7 +34,7 @@ yarn add @metamask/snaps-sdk
 Then, whenever you're required to return a custom UI component, import the components from the
 SDK at `@metamask/snaps-sdk/jsx` and build your UI with them.
 For example, to display a [`Box`](#box) using 
-[`snap_dialog`](../../reference/snaps-api.md#snap_dialog):
+[`snap_dialog`](../../reference/snaps-api/snap_dialog.mdx):
 
 ```javascript title="index.jsx"
 import { Box, Heading, Text } from "@metamask/snaps-sdk/jsx";

snaps/features/custom-ui/interactive-ui.md

@@ -21,9 +21,9 @@ The following interactive UI components are available:
 ## Create an interactive interface
 
 Create an interactive interface using the
-[`snap_createInterface`](../../reference/snaps-api.md#snap_createinterface) method.
+[`snap_createInterface`](../../reference/snaps-api/snap_createinterface.mdx) method.
 This method returns the ID of the created interface.
-You can pass this ID to [`snap_dialog`](../../reference/snaps-api.md#snap_dialog), returned from
+You can pass this ID to [`snap_dialog`](../../reference/snaps-api/snap_dialog.mdx), returned from
 [`onTransaction`](../../reference/entry-points.md#ontransaction), or from
 [`onHomePage`](../../reference/entry-points.md#onhomepage).
 
@@ -34,14 +34,14 @@ the Snap's storage.
 ### Add context to an interface
 
 You can optionally add context to an interface by passing a `context` object to the
-[`snap_createInterface`](../../reference/snaps-api.md#snap_createinterface) method.
+[`snap_createInterface`](../../reference/snaps-api/snap_createinterface.mdx) method.
 This object can contain any data you want to pass to the interface.
 This context will be passed to [`onUserInput`](../../reference/entry-points.md#onuserinput) when the user interacts with the interface.
 
 ## Update an interactive interface
 
 To update an interactive interface that is still active, use the
-[`snap_updateInterface`](../../reference/snaps-api.md#snap_updateinterface) method.
+[`snap_updateInterface`](../../reference/snaps-api/snap_updateinterface.mdx) method.
 Pass the ID of the interface to be updated, and the new UI.
 
 Updating an interface can be done as part of the
@@ -61,9 +61,9 @@ The following is an example flow:
 ## Get an interactive interface's state and context
 
 At any point, you can retrieve an interactive interface's state and context.
-To retrieve its state, call the [`snap_getInterfaceState`](../../reference/snaps-api.md#snap_getinterfacestate)
+To retrieve its state, call the [`snap_getInterfaceState`](../../reference/snaps-api/snap_getinterfacestate.mdx)
 method with the interface ID.
-To retrieve its context, call [`snap_getInterfaceContext`](../../reference/snaps-api.md#snap_getinterfacecontext)
+To retrieve its context, call [`snap_getInterfaceContext`](../../reference/snaps-api/snap_getinterfacecontext.mdx)
 with the interface ID.
 
 ## Example