0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00
mastra/docs/CONTRIBUTING.md
2026-11-09 16:59:20 -07:00

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:

  1. Build the docs locally to check for any build errors:

    pnpm run build
    
  2. Preview the production build:

    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:

    pnpm run vale:download
    

    Run every docs check. Pass the files you changed to scope file-level checks, and --fix to apply safe fixes:

    pnpm run check
    

    See 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:

---
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> tag
  • description: 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/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.

```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 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