opendocs

Beautiful docs with zero config. An open-source alternative to Mintlify.

Write documentation in MDX, get built-in search, syntax highlighting, theming, and deploy anywhere.

Installation

npm install -g @opendocsdev/cli

Or use directly with npx:

npx @opendocsdev/cli init my-docs

Commands

opendocs init [name]

Scaffold a new documentation project.

opendocs init my-docs

Creates a directory with a starter docs.json, example MDX pages, and a public/ folder for static assets.

opendocs dev

Start a local development server with hot reload.

opendocs dev
opendocs dev --port 3000

opendocs build

Build the documentation site for production. Outputs static HTML to dist/.

opendocs build

opendocs preview

Preview the production build locally.

opendocs preview
opendocs preview --port 3000

opendocs deploy

Deploy docs to the hosted platform.

opendocs deploy
opendocs deploy --skip-build  # Use existing dist/

Requires OPENDOCS_API_KEY and OPENDOCS_SITE_ID environment variables (or configure in docs.json).

Configuration

All configuration lives in docs.json at the project root.

{
  "name": "My Docs",
  "logo": {
    "light": "/logo.svg",
    "dark": "/logo-dark.svg"
  },
  "favicon": "/favicon.svg",
  "navigation": [
    {
      "group": "Getting Started",
      "pages": ["introduction", "quickstart"]
    },
    {
      "group": "Guides",
      "pages": [
        "components",
        {
          "group": "Advanced",
          "pages": ["custom-components", "theming"]
        }
      ]
    }
  ],
  "theme": {
    "primaryColor": "#10b981",
    "accentColor": "#8b5cf6",
    "darkMode": true
  },
  "features": {
    "search": true,
    "feedback": true,
    "analytics": true
  },
  "snippets": ["snippets"],
  "backend": {
    "siteId": "your-site-id",
    "apiUrl": "https://app.opendocs.dev"
  },
  "metadata": {
    "url": "https://docs.example.com",
    "ogImage": "/og-image.png"
  }
}

Navigation

Navigation supports flat pages and nested groups:

{
  "navigation": [
    {
      "group": "Group Name",
      "pages": [
        "page-slug",
        {
          "group": "Nested Group",
          "pages": ["nested/page-one", "nested/page-two"]
        }
      ]
    }
  ]
}

Page slugs map to MDX files relative to the project root (e.g., "quickstart" maps to quickstart.mdx).

Snippets

Reusable MDX content that can be imported across pages:

{
  "snippets": ["snippets"]
}

Place .mdx files in the snippets/ directory and import them in any page.

Built-in Components

All components are available in MDX files without imports.

Callout

<Callout type="info" title="Note">
  This is an informational callout.
</Callout>

Types: info, warning, error, tip

Card

<Card title="Getting Started" href="/quickstart">
  Learn how to set up your docs in minutes.
</Card>

CardGroup

<CardGroup cols={2}>
  <Card title="First" href="/first">Description</Card>
  <Card title="Second" href="/second">Description</Card>
</CardGroup>

CodeGroup

Tabbed code blocks for showing the same example in multiple languages:

<CodeGroup>
```bash npm
npm install @opendocsdev/cli
```

```bash pnpm
pnpm add @opendocsdev/cli
```

```bash yarn
yarn add @opendocsdev/cli
```
</CodeGroup>

Tabs / Tab

<Tabs>
  <Tab title="React">
    React content here.
  </Tab>
  <Tab title="Vue">
    Vue content here.
  </Tab>
</Tabs>

Steps

<Steps>
  ### Install the CLI

  Run `npm install -g @opendocsdev/cli`.

  ### Create a project

  Run `opendocs init my-docs`.

  ### Start writing

  Edit the MDX files in your project.
</Steps>

ApiPlayground

Interactive API endpoint explorer:

<ApiPlayground
  method="GET"
  endpoint="/api/users"
  description="List all users"
/>

Theming

Colors are configured in docs.json and support both light and dark mode:

{
  "theme": {
    "primaryColor": "#10b981",
    "accentColor": "#8b5cf6",
    "darkMode": true
  }
}

The engine automatically generates light/dark variants from your chosen colors.

Tech Stack

• Astro — Static site generation
• Tailwind CSS — Styling
• Shiki — Syntax highlighting
• Pagefind — Client-side search
• MDX — Markdown with JSX components

Development

cd packages/cli

# Run tests
pnpm test

# Watch mode
pnpm test:watch

# Type check
pnpm typecheck

# Build
pnpm build

The Astro engine source is at src/engine/ and is separate from the CLI's tsconfig.

Self-Hosting

opendocs also includes a server with analytics, a management dashboard, and edge serving. See the full repository for self-hosting instructions.

License

AGPL-3.0