feat: Create Snaps API documentation from generated schema

[Mrtenz]

Description

This adds a Docusaurus plugin for dynamically generating Snaps API documentation from a schema file. The schema file will be generated automatically based on the implementations in MetaMask/snaps. This allows for easier maintenance of the documentation, as some methods have become quite outdated currently.

The plugin works by fetching the schema file, and writing a new MDX file to disk for each JSON-RPC method. I've considered a similar approach to the Wallet API documentation, but it had several drawbacks, like needing to hack the sidebar to show the dynamic items. By generating the MDX files before running Docusaurus, @docusaurus/plugin-content-docs will just pick it up as any other documentation page.

Related to: https://consensyssoftware.atlassian.net/browse/WPC-347 and https://consensyssoftware.atlassian.net/browse/WPC-442.

Preview

Checklist

• If this PR updates or adds documentation content that changes or adds technical meaning, it has received an approval from an engineer or DevRel from the relevant team.
• If this PR updates or adds documentation content, it has received an approval from a technical writer.

External contributor checklist

• I've read the contribution guidelines.
• I've created a new issue (or assigned myself to an existing issue) describing what this PR addresses.

---

Note

Medium Risk
Adds a build-time docs generation step that fetches a remote schema and writes MDX files, which can break builds/CI or produce inconsistent docs if the schema changes or is unavailable.

Overview
Snaps API reference is now generated from a schema instead of maintained manually. A new Docusaurus plugin (plugin-snaps-docs) adds a snaps:generate CLI command that fetches the Snaps JSON-RPC schema and writes one MDX page per method under snaps/reference/snaps-api/, rendered via a new SnapsAPIReference component suite (description/parameters/returns/examples/tags) using react-markdown.

The docs navigation and content are updated to match the new structure: the old monolithic snaps/reference/snaps-api.md (and wallet-api-for-snaps.md) are removed, the Snaps sidebar now nests a Snaps API reference section, and many docs links are rewritten to point at the new generated per-method routes.

Build/CI now runs generation automatically (start/build prepend docusaurus snaps:generate, and the CI linkCheck job installs deps and generates the reference before link checking); generated files are added to .gitignore.

^{Written by Cursor Bugbot for commit ebe6f62. This will update automatically on new commits. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
metamask-docs	Ready	Preview, Comment	Mar 10, 2026 8:33am

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	react-markdown@​10.1.0

View full report

[bgravenorst]

Should there be an await?
Just asking because our existing examples often use it for snap.request

[bgravenorst]

The ToC on the right is incorrect. It's not showing Returns and Examples.

[bgravenorst]

General feedback:

• No examples for snap_closeWebSocket, snap_getPreferences, and a few others
• snap_dialog is hard to understand. The description introduces a bullet list (which is actually the parameters section). Also due to the formatting it's hard to follow what's happening in the Parameters section.
• Some examples have manifests, others don't
• snap_getLocale should this have a deprecated label?
• snap_scheduleBackgroundEvent, the “Common properties” section is confusing here because request isn’t an optional shared add-on, it’s a required top-level field in both union variants (I assume). so it would be clearer to document the parameter object once and state that exactly one of date or duration must be provided, along with the required request object.
• snap_sendWebSocketMessage Options is missing some text

[Mrtenz]

The ToC on the right is incorrect. It's not showing Returns and Examples.

@bgravenorst Do you have a good way to resolve this? It seems that Docusaurus isn't picking up the conditionally rendered headings. 😕

[Mrtenz]

@bgravenorst

• snap_dialog is hard to understand. The description introduces a bullet list (which is actually the parameters section). Also due to the formatting it's hard to follow what's happening in the Parameters section.

Agreed, I added the list description temporarily until we figure out a better way to show this. Can look into this as a follow-up if that's alright?

• Some examples have manifests, others don't

Only examples where additional permissions are needed have a manifest.

• snap_getLocale should this have a deprecated label?

Intended to remove this from the docs, but didn't push the change to the schema yet. It will be removed soon.

• snap_scheduleBackgroundEvent, the “Common properties” section is confusing here because request isn’t an optional shared add-on, it’s a required top-level field in both union variants (I assume). so it would be clearer to document the parameter object once and state that exactly one of date or duration must be provided, along with the required request object.

In this case I actually feel like it's pretty clear that request must be provided to one of the options? Do you have an example of what you were thinking?

• snap_sendWebSocketMessage Options is missing some text

This is a limitation in the schema generation script, will add some extra explanation to the message description for the time being, but can try and find a better solution in a follow-up.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

[m4sterbunny]

Working fine with local build of this (drops me into new reference page) but the vercel build here is throwing me elsewhere.

[Mrtenz]

This links me to the right place in the Vercel build?

[m4sterbunny]

many links from this on are absolute instead of relative

[Mrtenz]

Not sure what you mean? These links are relative.

[m4sterbunny]

[link](absolute/link)

vs
[link](./relative/sibling-link)
or
[link](../relative/one-level-up-link)