docs/src/content/en/guides/guide/docs-manager.mdx
import Steps from "@site/src/components/Steps"; import StepItem from "@site/src/components/StepItem";
In this guide, you'll build a documentation manager that maintains your project's docs. It creates well-structured markdown files, keeps documentation organized, and prevents accidental overwrites. You'll learn how to set up a workspace filesystem, create an agent with document management instructions, and use it to generate and update documentation through conversational prompts.
v22.13.0 or later installedThe workspace uses a local filesystem to manage documentation files. The agent reads and writes files within the workspace directory. In your src/mastra/index.ts file, import the Workspace and LocalFilesystem classes.
import { Mastra } from '@mastra/core'
// highlight-start
import { resolve } from 'node:path'
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
// highlight-end
// highlight-start
const workspace = new Workspace({
filesystem: new LocalFilesystem({
basePath: resolve(import.meta.dirname, '../../workspace'),
}),
})
// highlight-end
export const mastra = new Mastra({
// highlight-next-line
workspace,
})
At the root of your project, create a new folder called workspace. This is where all documentation files will be stored and managed by the agent.
Inside the workspace directory, create the following folders:
docs/guides/: For how-to guidesdocs/api/: For API reference documentationdocs/tutorials/: For step-by-step tutorialsCreate a workspace/docs/README.md file that serves as the documentation index:
# Project Documentation
Welcome to the documentation!
## Sections
- [Guides](./guides/): How-to guides
- [API](./api/): API reference
- [Tutorials](./tutorials/): Step-by-step tutorials
Add a sample guide so the agent can see the existing documentation style:
# Getting Started
Quickstart guide for the project.
## Installation
```bash npm2yarn
npm install example-package
```
## Quick example
```typescript
import { Example } from 'example-package'
const example = new Example()
example.run()
```
Now it's time to create the documentation manager agent. This agent will have instructions for creating and updating markdown files in the workspace. Create a new file src/mastra/agents/docs-manager.ts and define the agent:
import { Agent } from '@mastra/core/agent'
export const docsManager = new Agent({
id: 'docs-manager',
name: 'Docs Manager',
instructions: `You are a documentation manager that creates and maintains markdown docs.
When creating new docs:
1. Ask for topic and target audience
2. Create well-structured markdown with clear sections
3. Include relevant code examples with syntax highlighting
4. Save in the appropriate directory:
- /docs/guides/ for user guides and how-tos
- /docs/api/ for API reference
- /docs/tutorials/ for step-by-step tutorials
When updating existing docs:
1. ALWAYS read the file first
2. Make targeted updates without removing unrelated content
3. Preserve existing structure and formatting
Use kebab-case naming for files (getting-started.md).
Always explain what you're creating and why.`,
model: 'openai/gpt-5.4',
})
Define the agent by importing it inside src/mastra/index.ts and registering it with the Mastra instance:
import { Mastra } from '@mastra/core'
import { resolve } from 'node:path'
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
// highlight-next-line
import { docsManager } from './agents/docs-manager'
const workspace = new Workspace({
filesystem: new LocalFilesystem({
basePath: resolve(import.meta.dirname, '../../workspace'),
}),
})
export const mastra = new Mastra({
workspace,
// highlight-next-line
agents: { docsManager },
})
Start Mastra Studio and interact with the agent to see it in action.
npm run dev
Open localhost:4111 and navigate to the docs manager.
Ask the agent to create a tutorial:
Create a tutorial for setting up authentication. Cover installation, configuration, and a basic example.
The agent should create a file like docs/tutorials/authentication-setup.md. Since agent responses are non-deterministic, the exact content will vary, but you should see something similar to:
# Authentication Setup
Learn how to add authentication to your application.
## Installation
Install the auth package:
```bash npm2yarn
npm install @example/auth
```
## Configuration
Create a config file:
```typescript
// auth.config.ts
export const authConfig = {
provider: 'oauth',
clientId: process.env.AUTH_CLIENT_ID,
secret: process.env.AUTH_SECRET,
}
```
## Basic example
```typescript
import { createAuth } from '@example/auth'
import { authConfig } from './auth.config'
const auth = createAuth(authConfig)
app.get('/protected', auth.requireAuth(), (req, res) => {
res.json({ user: req.user })
})
```
Try updating an existing document:
Update the getting started guide to include a section on configuration after the Quick Example
The agent should read the existing getting-started.md file, find the right insertion point, and add the new section without disrupting existing content.
Ask the agent to create an index:
List all tutorial files and create an index page that links to all of them
The agent should create a file like /docs/tutorials/index.md that links to all available tutorials.
You can extend this manager to: