@brainfish-ai/devdoc

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/devdoc 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/devdoc create my-docs --template openapi
npx @brainfish-ai/devdoc create my-docs --template graphql

Then start the development server:

cd my-docs
npm run dev

Your browser will automatically open to http://localhost:3333 with your docs.

Installation

For existing projects:

npm install @brainfish-ai/devdoc

Or install globally:

npm install -g @brainfish-ai/devdoc

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 devdoc dev

Your browser will automatically open to http://localhost:3333 with your docs.

CLI Commands

| Command | Description | | --------------- | ---------------------------------------- | | devdoc create | Create a new DevDoc documentation site | | devdoc dev | Start development server with hot reload | | devdoc build | Build documentation for production | | devdoc start | Start production server | | devdoc check | Validate configuration and MDX files | | devdoc deploy | Deploy documentation to DevDoc platform | | devdoc sdk | Generate client SDKs from OpenAPI spec | | devdoc ai | Set up AI agent configuration | | devdoc domain | Manage custom domains | | devdoc keys | Manage API keys |

Command Options

devdoc create

devdoc 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

devdoc dev

devdoc dev [options]

Options:
  -p, --port <port>  Port to run server on (default: 3333)
  -H, --host <host>  Host to bind to (default: localhost)
  -o, --open         Open browser automatically (default: true)
  --no-open          Disable automatic browser opening

The browser automatically opens when the server starts. Use --no-open to disable this.

devdoc build

devdoc build [options]

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

devdoc start

devdoc start [options]

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

devdoc deploy

devdoc deploy [options]

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

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

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

devdoc sdk

Generate client SDKs from your OpenAPI specification:

# Initialize SDK configuration
devdoc sdk init

# Generate SDKs for all configured languages
devdoc sdk generate

# Generate for a specific language
devdoc sdk generate --lang typescript

# Validate your OpenAPI spec
devdoc sdk validate

# List available generators
devdoc sdk list

Supported languages:

• Native (no Java required): TypeScript, Python, Go
• OpenAPI Generator (requires Java): Java, C#, Ruby, PHP, Swift, Kotlin, Rust

SDK configuration is stored in sdk.json:

{
  "openapi": "./api-reference/openapi.json",
  "packageName": "my-api",
  "output": "./sdks",
  "languages": {
    "typescript": { "enabled": true, "packageName": "@my-org/sdk" },
    "python": { "enabled": true, "packageName": "my_sdk" }
  }
}

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/devdoc`
  </Step>
  <Step title="Configure">
    Create your `docs.json` file
  </Step>
  <Step title="Run">
    Start the dev server with `devdoc 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:

npm run deploy

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

Manual Deployment

# Build for production
npm run 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-ai/devdoc-platform

# Install dependencies
cd devdoc-platform
npm install

# Build and test the CLI
npm run devdoc:dev

Building for publish

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

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

License

AGPL-3.0 - See LICENSE for details.

For commercial licensing, contact: [email protected]