Doccupine

Doccupine is an open-source CLI that turns a directory of MDX files into a full-featured Next.js documentation website. Write your docs in Markdown, and Doccupine watches for changes, generates pages, and starts a live dev server automatically.

Features

• Live preview - watches your MDX files and regenerates pages on every save
• Auto-generated navigation - sidebar built from frontmatter (category, order)
• Sections - organize docs into tabbed sections via frontmatter or sections.json
• API reference - point at an OpenAPI spec to generate interactive endpoint pages with a live playground
• Subscribable changelogs - pages using the Update component publish an RSS feed at {page-url}/rss.xml
• Theming - dark/light mode with customizable theme via theme.json
• AI chat assistant - built-in RAG-powered chat (OpenAI, Anthropic, or Google)
• MCP server - exposes search_docs, get_doc, and list_docs tools for AI agents
• Custom fonts - Google Fonts or local fonts via fonts.json
• Static assets - public/ directory is watched and synced to the generated app
• Password protection - gate the whole site behind a shared password with SITE_PASSWORD
• Zero config to start - npx doccupine scaffolds everything and starts the server

Quick Start

Make sure you have Node.js (v22.12.0+) installed.

npx doccupine

Doccupine will prompt you for:

1. A directory to store your MDX files (default: docs)
2. An output directory for the generated Next.js app (default: nextjs-app)
3. An optional path to an OpenAPI spec for an API reference (blank to skip)

It then scaffolds the app, installs dependencies, and starts the dev server. Open http://localhost:3000 to view your docs.

The source and output directories must not overlap. To prevent accidental data loss, Doccupine only claims an empty output directory, one containing harmless local metadata such as .DS_Store or .env.local, or an existing Doccupine-generated app. Run doccupine config --reset if an older configuration no longer passes validation.

CLI Commands

doccupine watch [options]   # Default. Watch MDX files and start dev server
doccupine build [options]   # Generate the site without installing or serving it
doccupine generate [options] # Alias for build
doccupine config --show     # Show current configuration
doccupine config --reset    # Re-prompt for configuration

Options

watch (default):

Flag	Description
--port <port>	Port for the dev server (default: 3000). Auto-increments if taken.
--verbose	Show all Next.js output including compilation details
--reset	Re-prompt for watch/output directories
--skip-install	Generate and serve without running the dependency installer (installs are skipped automatically when package.json is unchanged)
--package-manager <name>	Package manager for the generated app: pnpm or npm (default: auto-detect). Overrides the packageManager field in doccupine.json.

build:

Flag	Description
--reset	Re-prompt for watch/output directories

config:

Flag	Description
--show	Print the current configuration and exit
--reset	Re-prompt for watch/output directories

MDX Frontmatter

Each MDX file supports these frontmatter fields:

---
title: "Page Title"
description: "Page description for SEO"
category: "Getting Started"
categoryOrder: 0 # Sort order for the category group
order: 1 # Sort order within the category
navIcon: "book-open" # Lucide icon name shown next to the page in the sidebar
categoryIcon: "rocket" # Lucide icon name shown next to the category group
name: "My Docs" # Override site name in title suffix
icon: "https://..." # Page favicon URL
image: "https://..." # OpenGraph image URL
date: "2025-01-01" # Page date metadata
updated: "2025-02-01" # Last-modified date (JSON-LD dateModified)
section: "API Reference" # Section this page belongs to
sectionOrder: 1 # Sort order for the section in the tab bar
openapi: "GET /users/{id}" # Embed an API playground for this endpoint (see API Reference)
rss: true # Show an RSS button linking to the page's feed (pages with Update components)
---

Navigation is auto-generated from category, categoryOrder, and order. Pages without a category appear ungrouped.

Use sectionLabel on your root index.mdx to rename the default "Docs" tab:

---
title: "Welcome"
sectionLabel: "Guides"
---

Sections

Sections let you split your docs into separate tabbed groups (e.g. "Docs", "API Reference", "SDKs"). There are two ways to configure them:

Via frontmatter

Add a section field to your MDX files. The section slug is derived from the label automatically. Use sectionOrder to control tab order (lower numbers appear first):

---
title: "Authentication"
section: "API Reference"
sectionOrder: 1
---

Pages without a section field stay at the root URL under the default "Docs" tab.

Via sections.json

For full control, create a sections.json file in your project root:

[
  { "label": "Docs", "slug": "" },
  { "label": "API Reference", "slug": "api" },
  { "label": "SDKs", "slug": "sdks" }
]

Each entry has:

• label - display name shown in the section bar
• slug - URL prefix for this section (use "" for the root section)
• directory (optional) - subdirectory containing this section's MDX files, only needed when the directory name differs from the slug

[
  { "label": "Guides", "slug": "", "directory": "guides" },
  { "label": "API Reference", "slug": "api", "directory": "api-reference" }
]

API Reference

Point Doccupine at an OpenAPI document (.json, .yaml, or .yml, OpenAPI 3.0/3.1) and it generates an interactive API reference: a directory at /api-reference linking every operation, plus one page per operation with a live playground for sending requests. Set the openapi field in doccupine.json:

{
  "openapi": "openapi.json"
}

The endpoint pages are grouped into their own "API Reference" tab, and your hand-written docs move under a "Documentation" tab. The spec file is watched, so edits regenerate the reference live.

You can pass multiple specs as an array of paths, or name them explicitly:

{
  "openapi": [
    { "name": "Public API", "file": "openapi.json" },
    { "name": "Admin API", "file": "admin-openapi.yaml" }
  ]
}

To embed a single endpoint's playground inline within a hand-written page, add an openapi frontmatter field set to "METHOD /path" (or the operation's operationId):

---
title: "Fetch a User"
openapi: "GET /users/{id}"
---

Configuration Files

Place these JSON files in your project root (where you run doccupine). They are auto-copied to the generated app and watched for changes.

File	Purpose
doccupine.json	CLI config (watchDir, outputDir, port, packageManager, openapi). Auto-generated on first run. Paths are stored relative to the project root, so the file is safe to commit.
config.json	Site metadata: name, description, icon, image, url (public site URL for sitemap/robots)
theme.json	Theme overrides for cherry-styled-components
navigation.json	Manual navigation structure (overrides auto-generated)
links.json	Static header/footer links
fonts.json	Font configuration (Google Fonts or local)
sections.json	Section definitions for tabbed doc groups (see Sections)
analytics.json	Analytics provider configuration (PostHog supported)

Public Directory

Place static assets (images, favicons, etc.) in a public/ directory at your project root. Doccupine copies it to the generated Next.js app on startup and watches for changes, so added, modified, or deleted files are synced automatically.

Sitemap and robots.txt

Doccupine generates robots.ts automatically for every site. When you set a url in config.json, it also generates sitemap.ts covering every page (across all sections) and links the sitemap from robots.txt.

{
  "name": "My Docs",
  "url": "https://docs.example.com"
}

You can override the URL at deploy time by setting the NEXT_PUBLIC_SITE_URL environment variable. When no URL is configured, /sitemap.xml is still served but stays empty, and robots.txt omits its sitemap reference until a public URL is available. The variable is baked in at build time, so changing it needs a redeploy.

llms.txt

Doccupine generates llms.txt artifacts so AI agents can discover and ingest your docs. On every regeneration, the following files are written to the generated app's public/ directory:

File	Contents
llms.txt	Index of every page (title, description, URL), grouped by section and category
llms-full.txt	Full-text bundle: every page's body concatenated for one-shot ingestion
public/<slug>.md	Per-page Markdown mirror of each MDX page, suitable for direct fetching at /<slug>.md

The site name and description used in llms.txt come from config.json (name, description). Page URLs are absolute when url is set in config.json (or via NEXT_PUBLIC_SITE_URL), and root-relative otherwise.

A .doccupine-artifacts.json file in the generated app tracks generated route ownership and per-page mirrors so renamed or deleted sources clean up only their own outputs. Don't commit this file; it is regenerated automatically.

AI Chat Setup

The generated app includes an AI chat assistant. To enable it, create a .env file in the generated app directory:

LLM_PROVIDER=openai # openai | anthropic | google

# API Keys (set the one matching your provider)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...

If LLM_PROVIDER is not set, the chat component is hidden automatically.

Note: Anthropic does not provide an embeddings API. When using anthropic as your provider, you must also set OPENAI_API_KEY for embeddings to work.

Optional overrides

LLM_CHAT_MODEL=gpt-4.1-nano                 # Override the default chat model
LLM_EMBEDDING_MODEL=text-embedding-3-small  # Override the default embedding model
LLM_TEMPERATURE=0                           # Set temperature (0-1, default: 0)
LLM_EMBEDDING_DIMS=512                       # Dimensions for the prebuilt search index (default: 512)
RAG_RUNTIME_EMBED_MAX_CHUNKS=400             # Max chunks embedded on demand in production (default: 400; 0 requires a prebuilt index)
# RAG_API_KEY=...                            # Optional bearer auth for direct /api/rag requests

LLM_EMBEDDING_DIMS Matryoshka-truncates document vectors so the prebuilt search index stays small; lower values shrink the index at a slight cost to recall. RAG_RUNTIME_EMBED_MAX_CHUNKS caps how many chunks the chat will embed on demand in production before requiring a prebuilt index (it's unlimited under next dev).

Public documentation leaves browser chat available by default. Setting RAG_API_KEY requires a bearer token for /api/rag and is intended for server-to-server use; the built-in browser cannot safely hold that secret. Use SITE_PASSWORD instead when authenticated browser visitors should retain chat access.

Default models per provider:

Provider	Chat model	Embedding model
OpenAI	gpt-4.1-nano	text-embedding-3-small
Anthropic	claude-sonnet-4-5-20250929	OpenAI fallback
Google	gemini-2.5-flash-lite	gemini-embedding-001

MCP Server

The generated app exposes an MCP endpoint at /api/mcp with three tools:

• search_docs - semantic search across all documentation
• get_doc - retrieve a specific document by path
• list_docs - list all available documents

This lets AI agents (Claude, ChatGPT, etc.) query your docs programmatically. Semantic search_docs requires the AI setup above for embeddings; get_doc and list_docs work from the generated content manifest without an embedding provider.

Password Protection

Gate your entire documentation site behind a shared password by setting SITE_PASSWORD in the generated app's environment - add it to .env for local development, or your host's environment variables in production:

SITE_PASSWORD=choose-a-strong-shared-password

When set, every visitor sees a login screen until they enter the password. Protection is enforced across three layers:

• Pages are gated behind the login screen.
• Content APIs (/api/rag chat, /api/search, and the /api/playground proxy) return 401 without a valid session, so the docs can't be scraped and the proxy can't relay anonymous requests around the login. Each route re-checks the session itself, not just the middleware.
• Search engines and crawlers are blocked: robots.txt disallows everything, pages carry a noindex, nofollow tag, and responses include an X-Robots-Tag header.

A successful login sets a signed, httpOnly cookie that lasts 30 days. The cookie stores an HMAC of the password, never the password itself. Leave SITE_PASSWORD unset (the default) to keep the site fully public. Documentation pages stay statically rendered either way - the gate is enforced in middleware.

Note: The MCP endpoint uses DOCS_API_KEY bearer authentication when configured. Without an API key, a password-protected site requires the normal gate session for MCP as well.

License

This project is licensed under a modified MIT license with a SaaS restriction. See LICENSE for details.