# Contributing to Mastra's documentation
You can _best_ help by creating high-quality issues with good reproductions and descriptions. Thanks for taking the time to contribute!
> **Tip for new contributors:**
> Take a look at [GitHub's Docs](https://docs.github.com/en/get-started/quickstart/hello-world) and [https://github.com/firstcontributions/first-contributions](https://github.com/firstcontributions/first-contributions) for helpful information on working with GitHub.
## Project setup
To begin developing locally, check out this project from your machine.
```shell
git clone git@github.com:mastra-ai/mastra.git
pnpm install
```
Run the following from your terminal in the `docs` directory:
```shell
cd docs
pnpm run dev
```
This will start a local development server at `http://localhost:3000` where you can preview your changes.
### Testing your changes
Before submitting a PR, make sure to:
1. **Build the docs locally** to check for any build errors:
```shell
pnpm run build
```
2. **Preview the production build**:
```shell
pnpm run serve
```
3. **Check for broken links**: The build process will warn you about broken links.
4. **Verify code examples**: If you've added code examples, test them if possible to ensure they work.
5. **Run linters**: Install Vale, then run the linting and validation commands.
Download Vale:
```bash
pnpm run vale:download
```
Run every docs check. Pass the files you changed to scope file-level checks, and `--fix` to apply safe fixes:
```shell
pnpm run check
```
See [`styleguides/CHECKS.md`](./styleguides/CHECKS.md) for rule IDs and how to disable a rule on one page.
6. **Add redirect** (optional): If you've renamed or deleted a doc, add a redirect to `vercel.redirects.json` and run `pnpm run generate-vercel-redirects` to update the generated `vercel.json`.
## Documentation structure
The Mastra documentation is organized into several sections:
- **docs/**: Main documentation (`src/content/en/docs/`)
- **guides/**: Step-by-step guides (`src/content/en/guides/`)
- **reference/**: API reference documentation (`src/content/en/reference/`)
- **models/**: Model provider documentation (`src/content/en/models/`). These docs are auto-generated and should not be edited manually.
- **course/**: Tutorial and course content (`src/course/`)
All documentation should be written in English and placed in the appropriate section under `src/content/en/`. English is the only supported language and there are no plans to support other languages at this time.
## Editing content
All documentation content is located in `src/content/en`. Mastra's documentation content is written in a variation of Markdown called MDX, which allows embedding React components directly in content. The site also supports GitHub Flavored Markdown, adding support for tables and task lists.
### File metadata
Each file has a few required frontmatter fields, which are defined like so:
```yaml
---
title: 'Memory Overview'
description: 'Learn about Mastra's memory system'
packages:
- '@mastra/memory'
- '@mastra/core'
---
```
- `title`: The title of the page. Used to populate the HTML `
` tag
- `description`: A short description of the page's content. Used in the HTML `` tag for SEO purposes.
- `packages`: An array of npm packages that are relevant to the content on the page. Enables embedded docs, see [EMBEDDED_DOCS.md](../scripts/EMBEDDED_DOCS.md) for more details.
Every listed package ships its own copy of the page, so list only the packages whose users need the page:
- List the package that owns the documented API. Don't add `@mastra/core` when a dedicated package such as `@mastra/mcp` or `@mastra/evals` owns the API.
- Add `@mastra/core` to broader framework guides, because every Mastra project installs it.
- On overview pages that compare several adapters, list the shared interface package, not every adapter. Each adapter's own page lists the adapter package.
- Keep the list to four packages or fewer. `pnpm check` warns above that.
### Headings
Headings should be nested by their rank. Headings with an equal or higher rank start a new section, headings with a lower rank start new subsections that are part of the higher-ranked section.
All headings should be written in sentence-casing, where only the first word of the heading is capitalized. Example: "This is a heading".
### Code blocks
Syntax-highlighted code blocks are rendered wherever Markdown code blocks are used. To add syntax highlighting, specify a language next to the backticks before the fenced code block.
````md
```typescript
function add(a: number, b: number) {
return a + b
}
```
````
You can also specify a filename by passing the `title` prop.
````md
```typescript title="add.ts"
function add(a: number, b: number) {
return a + b
}
```
````
#### Highlighting
You can highlight specific lines in a code block using the `{}` notation. For example, to highlight line 2 and lines 5-7:
````md
```typescript {2,5-7}
function add(a: number, b: number) {
return a + b
}
```
````
Alternatively you can use `// highlight-next-line` and `// highlight-start` / `// highlight-end` comments to specify which lines to highlight.
````md
```typescript
function add(a: number, b: number) {
// highlight-next-line
return a + b
}
```
````
#### oxfmt-mdx formatting
By default, oxfmt-mdx will format code blocks in all Markdown/MDX files. If you want to disable oxfmt-mdx for a specific code block, add `oxfmt:false` to the code block's metadata.
**Important:** This is an anti-pattern! This is an escape hatch for edge cases where oxfmt-mdx's formatting produces undesirable results. In general, you should strive to write code that can be formatted by oxfmt-mdx to maintain a consistent style across the documentation.
````md
```typescript oxfmt:false
function add(a: number, b: number) {
return a + b
}
```
````
### `npm install` code blocks
When including `npm install` code blocks, please use the following format to ensure consistent styling across the documentation:
````md
```bash npm2yarn
npm install @mastra/core
```
````
By including `npm2yarn` after `bash`, the documentation site will automatically generate a toggle that allows users to switch between different package managers.
### Admonitions
In addition to the basic Markdown syntax, we have a special admonitions syntax by wrapping text with a set of 3 colons, followed by a label denoting its type.
Example:
```md
:::note
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
:::
:::tip
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
:::
:::warning
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
:::
:::danger
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
:::
:::beta
Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
:::
```
`info` is an alias for `note` and renders identically, so prefer `note`.
### ``
Docusaurus provides the `` component that you can use in Markdown thanks to MDX:
```mdx
import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'
This is an apple 🍎
This is an orange 🍊
This is a banana 🍌
```
### ``
Use this on reference documentation pages to display the parameters and return types of a function, method, or class constructor. You need to use it like so:
```mdx
```
Provide an array of objects with the following properties:
- `name`: The name of the parameter or return type
- `type`: The data type of the parameter or return type
- `isOptional`: A boolean indicating whether the parameter is optional (default: `false`)
- `description`: A brief description of the parameter or return type