metamask-docs is the Docusaurus source behind docs.metamask.io

A documentation site with several products in one tree

metamask-docs is the repository behind docs.metamask.io. The README describes it as the MetaMask developer documentation repository, and it says the site is built using Docusaurus, a static site generator purpose-built for technical documentation.

The primary language of the repository is MDX, which is the format Docusaurus uses for documentation pages: Markdown with React components available inside the text.

What makes this repository more than a documentation folder is that it hosts several product areas at once. The top level carries directories for snaps, metamask-connect, embedded-wallets and smart-accounts-kit, plus an agent-wallet directory and a gator set of versioned docs with its own versions file. Next to them sit the sidebar files that drive navigation, named mm-connect-sidebar.js, snaps-sidebar.js, ew-sidebar.js, gator-sidebar.js and agent-wallet-sidebar.js.

That structure explains a lot about how the project is worked on. Content and navigation are separate concerns, so a page can exist in the tree without appearing in the site unless a sidebar references it, and a navigation change is a code change in a JavaScript file rather than a front matter edit.

The last push to the default branch was on 2026-10-16 and the repository is not archived, so the tree moves constantly.

Building locally on Node 20 and port 3003

The README gives a complete local build, and it is short enough to follow exactly.

The prerequisites are Node.js version 20.x and Git. Then clone the repository:

git clone https://github.com/MetaMask/metamask-docs.git
cd metamask-docs

Install the dependencies:

npm install

And start the development server:

npm start

Once the server starts, the documentation is at http://localhost:3003. The port is not the Docusaurus default of 3000, and it is set in the script rather than in a configuration file you have to find.

The repository also carries an .nvmrc, an eslint configuration in eslint.config.mjs, a stylelint configuration, a prettier configuration with matching ignore file, a TypeScript configuration and a husky directory, so the local toolchain is pinned rather than left to whatever your machine has.

There is a middleware.ts at the top level and a vercel.json, which tells you how the site is served in production and that the deployment target is Vercel. For anyone extending the site, the babel.config.js is there because Docusaurus is a React application and needs the transpilation setup.

Contributing means forking and adding an upstream remote

The README spends a good part of its length on the contribution workflow, and the reason is stated plainly: if you do not have write access to the repository, you must fork it to your personal account and clone your fork instead.

The fork clone, with the upstream remote added so you can pull and push to the original, looks like this:

git clone https://github.com/<YOUR-USERNAME>/metamask-docs.git
cd metamask-docs
git remote add upstream https://github.com/MetaMask/metamask-docs.git

So the working model is fork, branch, pull request. The README points to the full contribution guidelines in CONTRIBUTING.md for the rest.

Two details in the repository suggest how much of the work is now mechanical rather than editorial. There is a .husky directory with a prepare script, so a pre-commit hook is installed when you set the project up, and there is a .linkspector.yml, which is the configuration for a link checker that runs over the documentation.

The .cursor directory and AGENTS.md at the top level also tell you something about the current tooling habits of the maintainers, since the repository carries rules for automated editing agents alongside the human contribution guidelines.

The script layer generates content before it serves it

The package.json scripts show that this site is not a plain Docusaurus instance. Two generation steps run before the site is served or built.

The start command is npm run glossary:generate followed by docusaurus snaps:generate, and then docusaurus start with port 3003. The build command runs the same two generation steps before docusaurus build. The glossary script is a Node program at scripts/generate-smart-accounts-glossary.js, and it produces a glossary for the smart accounts area, which means part of that documentation content is produced by a script rather than written by hand.

The snaps generation step is a Docusaurus command, docusaurus snaps:generate, which belongs to the snaps plugin and produces the pages for the snaps documentation.

Around those sit the usual static site commands: docusaurus for the CLI, swizzle to eject components, clear, serve and deploy, plus write-translations and write-heading-ids for the translation workflow.

Quality control is layered. Linting is split into lint:js, which runs eslint with a maximum of five warnings allowed, and lint:style, which runs stylelint over the CSS in src with the fix flag. Formatting is prettier with a check variant, and type checking is tsc, with a typecheck-staged variant that runs against staged files only. The lint-staged configuration applies eslint to JavaScript and TypeScript, stylelint to CSS and prettier to Markdown, MDX and everything else.

There is also a dedicated documentation check script:

npm run docs:ci

That runs bash scripts/docs-pre-commit-check.sh, which is the closest thing the repository has to a command that validates a documentation change end to end, and it is the one to run before opening a pull request.

Translations live in the repository, and so do versioned docs

Two structural choices in this repository are worth understanding before you contribute.

The first is internationalisation. There is an i18n directory and a crowdin.yml file, which is the configuration for Crowdin, the translation platform. The Docusaurus commands write-translations and write-heading-ids exist to extract the translatable strings and to keep the heading identifiers stable across locales, which matters because a translated heading would otherwise break every link that points at it.

The second is versioned documentation, and it is not applied uniformly. The gator area has its own versioned docs directory and its own sidebars file, with a gator_versions.json listing the versions, while the rest of the tree does not follow the same pattern. That is a common shape for a documentation set that grew over time: versioning is added where a product needed it, and the older content keeps whatever structure it had.

A third structure is the set of standalone sidebar scripts. These are JavaScript files that describe the navigation for each product area, and they sit at the top level rather than inside the content directories, which tells you the navigation is maintained centrally and deliberately.

The practical consequence for a contributor is that adding a page is a two-step job. The MDX file needs a sidebar entry, and because the sidebars are JavaScript rather than data files, a change there is reviewed as code.

What the alternative looks like, and the licence question

The alternative to this repository, for a team writing developer documentation, is the lightweight one: keep the content in the code repository as Markdown, and let a wiki or a README carry it. The difference is instructive rather than ideological.

That route needs no site infrastructure at all, and it keeps the documentation next to the code it describes, in the same pull request. What it lacks is exactly what this repository provides: versioned docs for a product area, a translation pipeline that keeps dozens of locales in step, a search index, and a navigation model that spans several products with shared concepts such as the smart accounts glossary.

The other alternative is to build your own site with a general purpose framework. That buys flexibility in layout and components, and costs you the parts Docusaurus already handles well for documentation, which is why so many projects reach for it.

On the licence, the metadata for the repository records Apache-2.0, while the package.json declares the license field as MIT OR Apache-2.0 and the repository carries both a LICENSE-APACHE and a LICENSE-MIT file. For contributors the practical question is which one applies to a given file, and the dual licensing is the standard way to let you choose. That is a licensing fact rather than legal advice, and reading the two files before you copy content into a closed source product is the sensible move.

The contribution guide in CONTRIBUTING.md and the agent rules in AGENTS.md are the two documents to read before your first change.

Editorial conclusion

Adopt the metamask-docs repository if you are writing MetaMask developer documentation, because it is where the published site comes from and where the sidebars, versioned docs and translation files live. Do not adopt it as a documentation framework for your own product, since it is a site configuration full of MetaMask specific sidebars, product directories and scripts rather than a reusable template. Before your first pull request, read CONTRIBUTING.md, run npm run docs:ci to reproduce the pre-commit check, and confirm that the area you are documenting has a sidebar entry, because the content directories and the navigation are separate files and a new page that no sidebar references will not appear in the site.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. MetaMask/metamask-docs on GitHub
4. Project website
5. README