@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

Open http://localhost:3000 to preview 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

Open http://localhost:3000 to preview 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

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: 3000)
  -H, --host <host>  Host to bind to (default: localhost)

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.

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:

npx @brainfish-ai/devdoc deploy

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

Manual Deployment

# Build for production
npx @brainfish-ai/devdoc 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 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]