opendocs

Beautiful documentation, zero config. An open-source alternative to Mintlify.

What is opendocs?

opendocs is a complete documentation platform that lets you write docs in MDX, preview locally, and deploy anywhere. It includes a CLI for authoring, a server with built-in analytics, a management dashboard, and optional edge serving via Cloudflare Workers.

Features

• Zero-config MDX — Write in Markdown with JSX components out of the box
• Built-in components — Callouts, cards, code groups, tabs, steps, API playground
• Full-text search — Powered by Pagefind, runs entirely client-side
• Analytics — Pageviews, visitors, devices, geography, referrers, search queries
• User feedback — Collect and manage feedback directly in the dashboard
• Custom domains — Bring your own domain with automatic SSL via Cloudflare
• Deploy anywhere — Static hosting, Docker, Fly.io, or Cloudflare Workers
• Theming — Configurable colors, dark mode, logos via docs.json
• Syntax highlighting — Powered by Shiki with multi-language support
• CI/CD deploys — Deploy keys for automated deployments from your pipeline

Quick Start

Write docs locally

# Install the CLI
npm install -g @opendocsdev/cli

# Create a new docs project
opendocs init my-docs

# Start the dev server
cd my-docs
opendocs dev

Open http://localhost:4321 to see your docs.

Self-host the platform

# Clone the repo
git clone https://github.com/opendocs/opendocs.git
cd opendocs

# Install dependencies
pnpm install

# Set up environment
cp .env.example .env
# Edit .env with your database URL and secrets

# Run database migrations
cd packages/server
pnpm prisma migrate deploy

# Start everything
cd ../..
pnpm dev

This starts the server on :3001 and the dashboard alongside it.

Deploy with Docker

docker-compose up -d

See Deployment for production setup.

Architecture

opendocs/
├── packages/
│   ├── cli/            # CLI tool — init, dev, build, preview, deploy
│   ├── server/         # API server — auth, sites, analytics, deployments
│   ├── dashboard/      # Management UI — React SPA
│   └── docs-worker/    # Edge serving — Cloudflare Worker (optional)

How it works

1. Authors write MDX files and configure docs.json
2. CLI builds static HTML with Astro, Tailwind, and Pagefind search indexing
3. Deploy uploads the built site to the server (or any static host)
4. Server stores files in S3/R2, manages sites, tracks analytics
5. Dashboard provides a UI for managing sites, viewing analytics, and handling feedback
6. Worker (optional) serves docs from Cloudflare's 300+ edge locations

Deployment Modes

Mode	What	Best for
Server Only	Node.js serves API + dashboard + docs	Self-hosting, simplicity
Server + Worker	Node.js serves API + dashboard, Cloudflare Worker serves docs at the edge	Production, global performance

Configuration

Docs are configured via docs.json in your project root:

{
  "name": "My Docs",
  "logo": {
    "light": "/logo.svg",
    "dark": "/logo-dark.svg"
  },
  "navigation": [
    {
      "group": "Getting Started",
      "pages": ["introduction", "quickstart"]
    }
  ],
  "theme": {
    "primaryColor": "#10b981",
    "darkMode": true
  },
  "features": {
    "search": true,
    "feedback": true,
    "analytics": true
  }
}

Packages

Package	Description	Docs
@opendocsdev/cli	CLI for authoring and deploying docs	README
@opendocs/server	API server with auth, analytics, and storage	README
@opendocs/dashboard	Management dashboard (React SPA)	README
@opendocs/docs-worker	Edge docs serving via Cloudflare Workers	README

Deployment

Docker Compose (simplest)

docker-compose up -d

The default docker-compose.yml starts PostgreSQL and the server. Configure environment variables for R2 storage and other services.

Fly.io

fly launch
fly secrets set DATABASE_URL="..." BETTER_AUTH_SECRET="..." R2_ACCOUNT_ID="..." ...
fly deploy

Docker (manual)

docker build -t opendocs .
docker run -p 3001:3001 \
  -e DATABASE_URL="postgresql://..." \
  -e BETTER_AUTH_SECRET="..." \
  -e R2_ACCOUNT_ID="..." \
  -e R2_ACCESS_KEY_ID="..." \
  -e R2_SECRET_ACCESS_KEY="..." \
  -e R2_BUCKET_NAME="..." \
  -e DOCS_HOST="docs.example.com" \
  opendocs

See the Server README for full environment variable reference and deployment options.

Development

Prerequisites

• Node.js >= 20
• pnpm 9.15+
• PostgreSQL 16+

Setup

# Install dependencies
pnpm install

# Set up environment variables
cp .env.example .env

# Run database migrations
cd packages/server
pnpm prisma migrate dev
cd ../..

# Start all packages in dev mode
pnpm dev

Scripts

Command	Description
pnpm dev	Start server + dashboard in dev mode
pnpm dev:all	Start all packages including docs-worker
pnpm build	Build all packages
pnpm typecheck	Type-check all packages

Testing

# Run all tests
cd packages/server && pnpm test
cd packages/cli && pnpm test
cd packages/dashboard && pnpm test

Roadmap

What we're building next. Open an issue to influence the roadmap.

Phase 1: Payments & Core Features

• Payments & Billing — Free tier, Pro tier (teams, preview deploys, custom domains, analytics), Stripe
• OpenAPI Support — Parse OpenAPI 3.0 specs, auto-generate API reference pages, wire into API Playground
• GitHub Integration — Auto-deploy on push, preview deploys for PRs (Pro), status checks, "Edit this page" links
• Themes — 4 built-in themes (Clean, Slate, Ember, Ocean), custom fonts via docs.json
• New Components — Accordion, Tooltip, Badge, FileTree

Phase 2: Teams & Content

• Team Management — Org accounts with roles, invite via email, per-site access controls
• Versioning — Multiple doc versions, version selector, version-specific search
• Localization — Multi-language support, language switcher, per-locale config

Phase 3: Integrations

• Analytics — Google Analytics 4, PostHog, Plausible, custom script injection

Contributing

See CONTRIBUTING.md for development setup, coding standards, and the PR process.

License

This project is licensed under the AGPL-3.0 License. This means you can freely use, modify, and self-host opendocs. If you modify and host it as a service, you must share your changes under the same license.