@brainfish-ai/devdoc

@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: [e-mail]