8 KiB
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 and 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.
git clone git@github.com:mastra-ai/mastra.git
pnpm install
Run the following from your terminal in the docs directory:
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:
-
Build the docs locally to check for any build errors:
pnpm run build -
Preview the production build:
pnpm run serve -
Check for broken links: The build process will warn you about broken links.
-
Verify code examples: If you've added code examples, test them if possible to ensure they work.
-
Run linters: Install Vale, then run the linting and validation commands.
Download Vale:
pnpm run vale:downloadRun every docs check. Pass the files you changed to scope file-level checks, and
--fixto apply safe fixes:pnpm run checkSee
styleguides/CHECKS.mdfor rule IDs and how to disable a rule on one page. -
Add redirect (optional): If you've renamed or deleted a doc, add a redirect to
vercel.redirects.jsonand runpnpm run generate-vercel-redirectsto update the generatedvercel.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:
---
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<title>tagdescription: A short description of the page's content. Used in the HTML<meta name="description">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 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/corewhen a dedicated package such as@mastra/mcpor@mastra/evalsowns the API. - Add
@mastra/coreto 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 checkwarns 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.
```typescript
function add(a: number, b: number) {
return a + b
}
```
You can also specify a filename by passing the title prop.
```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:
```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.
```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.
```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:
```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:
:::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.
<Tabs>
Docusaurus provides the <Tabs> component that you can use in Markdown thanks to MDX:
import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'
<Tabs>
<TabItem value="apple" label="Apple" default>
This is an apple 🍎
</TabItem>
<TabItem value="orange" label="Orange">
This is an orange 🍊
</TabItem>
<TabItem value="banana" label="Banana">
This is a banana 🍌
</TabItem>
</Tabs>
<PropertiesTable>
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:
<PropertiesTable
content={[
{
name: 'id',
type: 'string',
isOptional: true,
description: 'Unique identifier for the agent. Defaults to `name` if not provided.',
},
]}
/>
Provide an array of objects with the following properties:
name: The name of the parameter or return typetype: The data type of the parameter or return typeisOptional: A boolean indicating whether the parameter is optional (default:false)description: A brief description of the parameter or return type