# @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:

```bash
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:

```bash
npx @brainfish-ai/devdoc create my-docs --template openapi
npx @brainfish-ai/devdoc create my-docs --template graphql
```

Then start the development server:

```bash
cd my-docs
npm run dev
```

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

## Installation

For existing projects:

```bash
npm install @brainfish-ai/devdoc
```

Or install globally:

```bash
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

```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:

```mdx
---
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

```bash
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    |

### Command Options

**devdoc create**

```bash
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**

```bash
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**

```bash
devdoc build [options]

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

**devdoc start**

```bash
devdoc start [options]

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

**devdoc deploy**

```bash
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

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

### Navigation

```json
{
  "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

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

### Redirects

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

## MDX Components

### Note / Warning / Tip

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

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

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

### Cards

```mdx
<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

```mdx
<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

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

### Accordion

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

### Tabs

```mdx
<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:

```bash
npx @brainfish-ai/devdoc deploy
```

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

### Manual Deployment

```bash
# 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

```bash
# 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

```bash
# 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](./LICENSE) for details.

For commercial licensing, contact: support@brainfi.sh
