Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

delightful docsfor humans & agents

Login with GitHubGitHub Repo ↗
Holocron turns MDX pages and a docs.json config into a full documentation site. It runs as a Vite plugin, builds locally, and deploys anywhere.
Designed as a Mintlify-compatible replacement: same config shape, same MDX components, same frontmatter fields. If you have a Mintlify project, you can migrate in about 2 minutes.

Install skill for AI agents

npx -y skills add remorses/holocron
This installs skills for AI coding agents like Claude Code, Cursor, Windsurf, and others. Skills teach agents the workflows, patterns, and tools specific to this project.

Quickstart

Scaffold a new project with the CLI:
npx -y "@holocron.so/cli" create
This creates a working docs site with sample pages, navigation, and a vite.config.ts. Run pnpm install && pnpm dev and you're live.

Manual setup

pnpm add @holocron.so/vite react react-dom vite
Create a vite.config.ts:
import { defineConfig } from 'vite'
import { holocron } from '@holocron.so/vite'

export default defineConfig({
  plugins: [holocron()],
})
The plugin auto-adds Spiceflow, Tailwind CSS, and React. No extra setup needed.
Create a docs.json at the project root:
{
  "name": "My Docs",
  "colors": { "primary": "#6366f1" },
  "navigation": [
    {
      "group": "Getting Started",
      "pages": ["index"]
    }
  ]
}
Write your first page as index.mdx:
---
$schema: https://holocron.so/frontmatter.json
title: Welcome
description: My documentation site.
---

# Welcome

This is my first Holocron page.
Run the dev server:
npx vite
Open http://localhost:5173 and you should see your docs site.
Build for production:
npx vite build
node dist/rsc/index.js

What you get

  • Local builds with vite build, deploy the output anywhere
  • Mintlify-compatible docs.json schema and MDX components
  • OpenAPI reference pages generated from your spec
  • Search powered by Orama, built into the sidebar
  • Dark mode with system detection and manual toggle
  • AI exports for agents: .md per page, /llms.txt, /docs.zip, skill discovery
  • React Server Components under the hood via Spiceflow and Vite

Holocron vs Mintlify

AreaMintlifyHolocron
HostingCloud onlySelf-hosted, or holocron.so managed hosting
BuildCloud build on pushLocal vite build, standard CI
PricingStarts at $150/moFree, open source (MIT)
Git workflowMintlify-managed deploysStandard git: PRs, branches, diffs
Configdocs.jsonSame docs.json (compatible)
ComponentsProprietary MDX setSame components, open source
API referenceInteractive playgroundRead-only API reference from OpenAPI
SearchAlgolia / built-inOrama (local, zero config)
Custom domainsDashboard settingYour hosting provider
AnalyticsBuilt-in dashboardBring your own
AI exports/llms.txt, .md routes/llms.txt, /docs.zip, .md routes, skill discovery
Custom routesNot possibleMount alongside a Spiceflow app
FrameworkProprietaryVite + React Server Components
Holocron accepts unknown Mintlify fields via .passthrough(), so you can paste a full Mintlify docs.json without validation errors. Fields Holocron does not consume are silently ignored.

Migration from Mintlify

In your existing Mintlify docs directory:
1. Install dependencies
pnpm add @holocron.so/vite react react-dom vite
2. Create vite.config.ts
import { defineConfig } from 'vite'
import { holocron } from '@holocron.so/vite'

export default defineConfig({
  plugins: [holocron()],
})
3. Keep your docs.json
Your existing docs.json works as-is. Holocron's schema accepts unknown Mintlify fields; the runtime ignores fields it does not consume.
4. Run it
npx vite
Your site should render at http://localhost:5173.

What transfers directly

  • Navigation: tabs, groups, pages, anchors, versions, dropdowns, products
  • MDX components: Accordions, Cards, Callouts, Steps, Tabs, Code Groups, Expandables
  • Frontmatter: title, description, icon, sidebarTitle, tag, hidden, deprecated
  • Config: colors, logo, favicon, navbar, footer, redirects, appearance, fonts, banner
  • OpenAPI tabs: { "tab": "API Reference", "openapi": "openapi.json" } generates pages from your spec

What is different

AreaMintlifyHolocron
HostingMintlify cloudSelf-hosted (Node.js or Cloudflare Workers)
BuildCloud build on pushLocal vite build
API playgroundInteractive playgroundRead-only API reference
AnalyticsBuilt-in dashboardBring your own
Custom domainsDashboard settingYour hosting provider
SearchAlgolia/built-inOrama (local, built-in)

How it works

  docs.json + MDX files
          │
          ▼
  ┌────────────────┐
  │  Vite Plugin   │  reads config, syncs navigation tree, processes MDX
  │  (holocron())  │
  └───────┬────────┘
          │
          ▼
  ┌────────────────┐
  │   Spiceflow    │  React Server Components framework
  │   + Tailwind   │  auto-added by the plugin
  └───────┬────────┘
          │
          ▼
  Full docs site with search, OpenAPI, dark mode, AI exports
The plugin reads your config file, walks the navigation tree to discover MDX pages, and generates virtual modules that the Spiceflow app consumes at render time. Only changed files get re-parsed on subsequent builds thanks to a git-SHA-based cache.

Deploy

Holocron hosting

The fastest way to get a live URL. Builds and uploads your site to holocron.so:
npx -y "@holocron.so/cli" deploy
In GitHub Actions, the deploy command uses OIDC tokens automatically (no API key needed). Add permissions: id-token: write to your workflow.

Node.js

npx vite build
node dist/rsc/index.js
The build output is a standard Node.js server. Deploy it to any platform that runs Node.

Cloudflare Workers

npx vite build
npx wrangler deploy
See Cloudflare deploy docs for wrangler.jsonc setup.

AI-readable docs

Every Holocron site generates AI-friendly endpoints out of the box:
  • .md routes: append .md to any page URL to get raw markdown. https://your-site.com/quickstart.md
  • /llms.txt: an index of all pages with titles and .md URLs. Agents read this to discover the site structure.
  • /docs.zip: download every page as a .md file in one zip. Agents can grep it locally.
  • Skill discovery: /.well-known/agent-skills/index.json exposes your docs as an installable AI skill.
curl https://your-site.com/llms.txt
curl -L https://your-site.com/docs.zip -o docs.zip

Project structure

my-docs/
├── index.mdx           # pages are MDX files
├── guides/
│   ├── install.mdx
│   └── deploy.mdx
├── docs.json           # navigation and config
├── vite.config.ts      # one-line plugin setup
├── package.json
└── public/             # static assets (logos, images)

Explore

Full documentation at holocron.so.

License

MIT. If you use Holocron for your docs, please keep the "Powered by Holocron" footer link. It helps others discover the project.

Explore

Quickstart
Get a docs site running in under a minute.
Migration from Mintlify
Move an existing Mintlify project to Holocron.
Mintlify open source alternative
Drop-in Mintlify replacement. Same docs.json and MDX, MIT licensed.
Navigation
Tabs, groups, pages, anchors, versions, and dropdowns.
Theme and Colors
shadcn-compatible CSS variables and color tokens.
OpenAPI Reference
Generate API docs from an OpenAPI spec.
AI-Readable Docs
/llms.txt, /docs.zip, .md routes, and skill discovery.
MDX Components
Accordions, Cards, Callouts, Steps, Tabs, and more.
Deploy
Node.js, Cloudflare Workers, and build output.

Questions