metamask-docs / rules

---
description: Maps folder conventions to Diataxis content types so AI tools produce the right structure for each doc category.
globs: **/*.md,**/*.mdx
alwaysApply: false
---

# Content types (Diataxis)

This repository follows the [Diataxis framework](https://diataxis.fr/) to organize documentation by
function. The folder a file lives in usually determines the content type and structure expectations.
`get-started/` is a mix of onboarding topics; see that section for when quickstart rules apply.

## Folder-to-type mapping

### `concepts/` and `learn/` - Explanation

- Explain **why** something exists and **how** it works at a high level.
- Provide context: design decisions, historical reasons, trade-offs, and alternatives.
- Make connections to other parts of the system or to broader concepts.
- Do not include step-by-step instructions. Link to related guides or quickstarts instead.
- Keep explanation closely bounded. Do not let instructions or reference details creep in.
- End every concept page with a "Next steps" section linking to actionable content.
- Example: `smart-accounts-kit/concepts/smart-accounts.md`

### `guides/` and `how-to/` - How-to

- Goal-oriented steps that help the reader achieve a specific outcome.
- Title the page with the goal (for example, "Configure gas limits"), not a generic label.
- State the goal in the first sentence or heading.
- List prerequisites before the first step.
- Number the steps. Each step should contain one action.
- Assume the reader has basic knowledge of the product.
- Omit the unnecessary. Practical usability matters more than completeness.
- Do not digress into explanations or teaching. Link to concept pages instead.
- Example: `smart-accounts-kit/guides/advanced-permissions/execute-on-metamask-users-behalf.md`

### `quickstart/` and `get-started/`

The folder name alone does not imply a single content type for every file under `get-started/`.

**Tutorial-adjacent quickstart** (end-to-end, copy-paste-and-run path to a working integration)
applies only when:

- The file lives under a `quickstart/` directory, or
- The file lives under `get-started/` and **quickstart** appears in the file or directory name
  (for example, `smart-account-quickstart/index.md`).

For those quickstart pages:

- State what the reader will build or achieve.
- Provide complete, working code that can be copied and pasted.
- Keep the scope narrow. Link to guides for extended scenarios.

**Other `get-started/` pages** are onboarding essentials readers should see before the rest of
the docs: installation, system requirements, supported networks, supported clients, dashboard
setup, and similar. They are not necessarily quickstarts. Choose structure based on the topic
(how-to steps, short explanation, or reference-style facts) and match conventions of neighboring
pages in the same `get-started/` section.

Examples:

- Quickstart: `smart-accounts-kit/get-started/smart-account-quickstart/index.md`
- Onboarding in `get-started/` (not quickstart): `smart-accounts-kit/get-started/install.md`

### `reference/` - Reference

- Precise, complete, structured descriptions of APIs, methods, parameters, and return values.
- Describe and only describe. Be austere, neutral, and factual.
- Match the parameter format used in surrounding reference pages. Some areas use tables (name,
  type, required/optional, description); others use nested bulleted lists (for example, JSON-RPC
  method docs in Snaps). Be consistent with the existing convention in the same product section.
- Adopt standard patterns. Consistent structure lets readers find information quickly.
- Mirror the structure of the API or code itself (for example, one section per method or endpoint).
- Include short usage examples to illustrate parameters and return values.
- Keep explanatory prose to the minimum needed to use the API correctly.
- Do not include tutorials or extended how-to steps.
- Examples: `snaps/reference/config-options.md`,
  `smart-accounts-kit/reference/delegation/delegation-scopes.md`,
  `snaps/reference/snaps-api/wallet_snap`

### `tutorials/` - Tutorial

- Learning-oriented, reproducible, end-to-end walkthrough.
- State what the reader will build or accomplish at the very start.
- Do not assume the reader has prior knowledge of the subject or tools.
- Deliver visible results early and often. Each step should produce output the reader can verify.
- Show expected output (for example, "You should see `Server running on port 3000`").
- Ruthlessly minimize explanation. Keep the focus on doing, not theory. Link to concept pages for
  deeper understanding.
- Ignore options and alternatives. Guide the reader along a single path to a successful conclusion.
- Provide a complete working project or code sample.
- Aspire to perfect reliability. Test every step. A learner who doesn't get the expected result
  loses confidence immediately.
- Example: `src/pages/tutorials/create-wallet-ai-agent.md`

### `troubleshooting/` - Problem/solution

- State the symptom or error message first, then the fix.
- One problem per section or page.
- Include the exact error text when available so readers can search for it.
- Example: `smart-accounts-kit/troubleshooting/allowance-exceeded.md`

## Frontmatter

For required and optional documentation frontmatter (`description`, `keywords`, `sidebar_label`,
`title` vs duplicate H1), see **Frontmatter** in `markdown-formatting.mdc`.