Botpress Documentation

Welcome to the Botpress documentation repository. This project powers the docs site of Botpress, the complete AI Agent platform.

To get started with contributions, please review the entire README.

Prerequisites

To contribute, install the following software if you haven't already:

• VS Code, Cursor, or another text editor
• Node.js (v18 or higher)
• pnpm package manager
• Vale for writing style checks (optional but recommended)

Getting started

1. Clone the repository:

   git clone https://github.com/botpress/docs.git
   cd docs

2. Install dependencies:

   pnpm install

3. Start the development server:

   mint dev

   This will start a local Mintlify server at http://localhost:3000.

Project structure

The Botpress documentation is built with Mintlify. Here's how the project is organized:

docs/
├── docs.json              # Mintlify configuration & navigation
├── home.mdx               # Homepage content
├── learn/                 # Learning materials and guides
├── integrations/          # Integration documentation
├── webchat/              # Webchat-specific docs
├── for-developers/       # Developer-focused content
├── api-reference/        # API documentation
├── snippets/             # Reusable content snippets
├── changelog.mdx         # Product changelog
├── *-openapi.json        # OpenAPI specifications
└── assets/               # Images and other static files

Content guidelines

MDX

All documentation is written in MDX (Markdown with JSX components). You can find full list of supported components in the Mintlify documentation.

Note

If you're using VS Code or Cursor, we recommend also installing the official Mintlify extension. This will enable autocomplete for most Mintlify components.

Images

• Mintlify supports responsive light/dark images. If you're using UI screenshots, make sure you include both a light and dark version.
• Wrap all images in Mintlify's Frame component.
• Include appropriate alt text for all images

If you're using VS Code or Cursor, you can use the snippet at /.vscode/mdx.code-snippets for any images.

Navigation

The docs.json file at the root of the repository determines the navigation structure of the documentation. If you're adding new pages, make sure you update docs.json to include them.

Check writing

Botpress uses Vale to enforce consistent style and branding throughout the documentation. Vale executes on all pull requests in this repository.

You can also run Vale locally using the Vale CLI:

1. Install Vale if you haven't already
2. Download the required packages:

vale sync

3. Run a writing check against files you've modified:

make check-writing

Note

If you need Vale to ignore a certain flag within the context you're writing about, you can use comment-based configuration to disable rules within a given section.

Check links

To check for broken links, run:

mint broken-links

This check also runs on every pull request in the repository.

Development workflow

Make a change

1. Fork the repository
2. Create a feature branch: git checkout -b name/feature/your-improvement
3. Make your changes following our style guidelines
4. Test your changes locally with mint dev
5. Validate writing style with make check-writing (if Vale is installed)
6. Check for broken links using mint broken-links
7. Submit a pull request with a clear description of your changes

Raise an issue

Use this repository for specific documentation-related issues only. Report any product bugs (or general documentation feedback) via Discord.

Support

Join the conversation on our Discord server for any other questions related to Botpress—we'd love to hear from you.

Thank you for helping us improve the Botpress documentation!