@brainfish-ai/carp

Documentation framework for developers. Write docs in MDX, preview locally, deploy to Brainfish.

Quick Start

Create a new documentation site with one command:

npx @brainfish-ai/carp create my-docs

This will prompt you to select a template:

• Basic - Simple documentation site with guides and pages
• OpenAPI - Documentation with REST API reference (OpenAPI/Swagger)
• GraphQL - Documentation with GraphQL API playground

You can also specify the template directly:

npx @brainfish-ai/carp create my-docs --template openapi
npx @brainfish-ai/carp create my-docs --template graphql

Then start the development server:

cd my-docs
npm run dev

Open http://localhost:3000 to preview your docs.

Installation

For existing projects:

npm install @brainfish-ai/carp

Or install globally:

npm install -g @brainfish-ai/carp

Project Structure

my-docs/
├── docs.json          # Configuration
├── index.mdx          # Homepage
├── quickstart.mdx     # Getting started guide
├── api-reference/     # API specs (OpenAPI/GraphQL)
└── public/            # Static assets
    └── logo.svg

2. Configure docs.json

{
  "name": "My Documentation",
  "favicon": "/favicon.svg",
  "navigation": {
    "tabs": [
      {
        "tab": "Guides",
        "type": "docs",
        "groups": [
          {
            "group": "Getting Started",
            "pages": ["index", "quickstart"]
          }
        ]
      }
    ]
  }
}

3. Write your docs

Create MDX files with frontmatter:

---
title: Welcome
description: Get started with our documentation
---

# Welcome

This is your documentation homepage.

<Note>
  This is a helpful note for your readers.
</Note>

4. Run the dev server

npx carp dev

Open http://localhost:3000 to preview your docs.

CLI Commands

| Command | Description | | --------------- | ---------------------------------------- | | carp create | Create a new Carp documentation site | | carp dev | Start development server with hot reload | | carp build | Build documentation for production | | carp start | Start production server | | carp check | Validate configuration and MDX files | | carp deploy | Deploy documentation to Carp platform |

Command Options

carp create

carp create [project-directory] [options]

Options:
  -t, --template <type>  Template to use (basic, openapi, graphql)
  --no-git               Skip git initialization
  --no-install           Skip installing dependencies

Templates available:

• basic - Simple docs with guides
• openapi - Docs + REST API reference (OpenAPI/Swagger)
• graphql - Docs + GraphQL API playground

carp dev

carp dev [options]

Options:
  -p, --port <port>  Port to run server on (default: 3000)
  -H, --host <host>  Host to bind to (default: localhost)

carp build

carp build [options]

Options:
  -o, --output <dir>  Output directory (default: dist)

carp start

carp start [options]

Options:
  -p, --port <port>  Port to run server on (default: 3000)

carp deploy

carp deploy [options]

Options:
  -u, --url <url>  API URL (default: https://carp.sh)

Deploy your documentation to the Carp platform and get a public URL (e.g., https://my-docs.carp.sh).

On first deploy, a .carp.json file is created to track your project. Subsequent deploys will update the same project.

Configuration (docs.json)

Basic Configuration

{
  "name": "My Product",
  "logo": {
    "light": "/logo/light.svg",
    "dark": "/logo/dark.svg"
  },
  "favicon": "/favicon.ico",
  "colors": {
    "primary": "#10b981"
  }
}

Navigation

{
  "navigation": {
    "tabs": [
      {
        "tab": "Documentation",
        "type": "docs",
        "groups": [
          {
            "group": "Getting Started",
            "icon": "rocket-launch",
            "pages": ["index", "quickstart"]
          },
          {
            "group": "Guides",
            "pages": [
              "guides/overview",
              {
                "group": "Advanced",
                "pages": ["guides/advanced/topic1", "guides/advanced/topic2"]
              }
            ]
          }
        ]
      },
      {
        "tab": "API Reference",
        "type": "openapi",
        "path": "/api-reference",
        "versions": [
          { "version": "v2", "spec": "api-reference/v2/openapi.json", "default": true },
          { "version": "v1", "spec": "api-reference/v1/openapi.json" }
        ]
      },
      {
        "tab": "GraphQL API",
        "type": "graphql",
        "path": "/graphql-api",
        "schema": "api-reference/schema.graphql",
        "endpoint": "https://api.example.com/graphql"
      },
      {
        "tab": "Changelog",
        "type": "changelog",
        "path": "/changelog"
      }
    ]
  }
}

Notice Banner

{
  "notice": {
    "content": "🚀 Check out [what's new](/changelog) in the latest release!",
    "dismissible": true,
    "background": "#1e293b"
  }
}

Redirects

{
  "redirects": [
    {
      "source": "/old-page",
      "destination": "/new-page"
    },
    {
      "source": "/docs/:slug*",
      "destination": "/guides/:slug*"
    }
  ]
}

MDX Components

Note / Warning / Tip

<Note title="Important">
  This is important information.
</Note>

<Warning>
  Be careful with this operation.
</Warning>

<Tip>
  Here's a helpful tip.
</Tip>

Cards

<Card title="Getting Started" href="/quickstart">
  Learn how to get started quickly.
</Card>

<CardGroup cols={2}>
  <Card title="Installation">Install the package</Card>
  <Card title="Configuration">Configure your project</Card>
</CardGroup>

Steps

<Steps>
  <Step title="Install">
    Run `npm install @brainfish/carp`
  </Step>
  <Step title="Configure">
    Create your `docs.json` file
  </Step>
  <Step title="Run">
    Start the dev server with `carp dev`
  </Step>
</Steps>

Code Blocks

```javascript title="example.js" {2-3}
function hello() {
  // These lines are highlighted
  console.log("Hello, world!");
}
```

Accordion

<Accordion title="Click to expand">
  Hidden content that can be revealed.
</Accordion>

Tabs

<Tabs>
  <Tab title="npm">
    ```bash
    npm install package
    ```
  </Tab>
  <Tab title="yarn">
    ```bash
    yarn add package
    ```
  </Tab>
</Tabs>

Deployment

Brainfish (Recommended)

Deploy to Brainfish with a single command:

npx @brainfish-ai/carp deploy

Your docs will be live at https://your-project.carp.sh

Manual Deployment

# Build for production
npx @brainfish-ai/carp build

# The output is in the dist/ directory
# Deploy this to any static hosting (Vercel, Netlify, etc.)

Development

Testing locally

# Clone the repo
git clone https://github.com/brainfish/brainfish-api-docs

# Install dependencies
cd brainfish-api-docs
npm install

# Build and test the CLI
npm run carp:dev

Building for publish

# Build the full bundle (CLI + renderer)
npm run carp:bundle

# This creates packages/carp/renderer/ with the built app

License

AGPL-3.0 - See LICENSE for details.

For commercial licensing, contact: [email protected]