Holocron: a self-hosted docs generator that speaks Mintlify

Mintlify's shape without Mintlify's cloud

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.

The design goal is stated as a compatibility target rather than a feature list. It is designed as a Mintlify-compatible replacement, with the same config shape, the same MDX components and the same frontmatter fields, and the README claims that if you have a Mintlify project you can migrate in about two minutes.

The comparison table makes the practical differences clear, and the rows that matter for a decision are the first few. Hosting is cloud only for Mintlify and self-hosted, or managed on holocron.so, for Holocron. The build is a cloud build on push for Mintlify and a local vite build with standard CI for Holocron. Pricing starts at 150 dollars a month for Mintlify, while Holocron is free and open source under MIT. The git workflow is Mintlify-managed deploys against standard git with pull requests, branches and diffs. And the framework is proprietary for Mintlify and Vite with React Server Components for Holocron.

Two rows point at what a company documents and what a tool does. Mintlify's API reference is an interactive playground and Holocron's is a read-only reference generated from an OpenAPI spec, which is a deliberate reduction in scope. And custom routes are not possible in Mintlify, while in Holocron you can mount a route alongside a Spiceflow app.

So the trade is not feature for feature. It is a cloud service with a monthly bill replaced by a build step you own.

Scaffolding a project

The quickstart is a CLI command:

npx -y "@holocron.so/cli" create

That creates a working docs site with sample pages, navigation and a vite.config.ts, and then pnpm install and pnpm dev gets you running.

The manual route is the same thing spelled out, and it is worth reading because it shows how little is required. You install the plugin and the runtime:

pnpm add @holocron.so/vite react react-dom vite

Then you create a vite.config.ts:

import { defineConfig } from 'vite'
import { holocron } from '@holocron.so/vite'

export default defineConfig({
  plugins: [holocron()],
})

And that is the whole configuration, because the plugin auto-adds Spiceflow, Tailwind CSS and React, and the README says no extra setup is needed.

The content side is two files. A docs.json at the project root, with a name, a primary colour and a navigation tree of groups and pages. And a page, written as index.mdx with frontmatter:

---
$schema: https://holocron.so/frontmatter.json
title: Welcome
description: My documentation site.
---

# Welcome

This is my first Holocron page.

The schema URL in the frontmatter is how an editor knows where to validate the fields, and the presence of a $schema line is a small sign that the project treats its config as a contract.

How the pipeline works, and the cache that makes rebuilds quick

The diagram in the README is compact and shows the three stages.

Your docs.json and MDX files go into the Vite plugin, holocron(), which reads the config, synchronises the navigation tree and processes the MDX. That produces something a Spiceflow application consumes, with Spiceflow being the React Server Components framework and Tailwind added automatically by the plugin, and the output is a full docs site with search, OpenAPI, dark mode and the AI exports.

The mechanism is worth spelling out. The plugin reads your config file, walks the navigation tree to discover the MDX pages, and generates virtual modules that the Spiceflow app consumes at render time. Nothing is copied into a build directory and nothing is regenerated from scratch, because the pages are virtual modules that exist only for the duration of the build.

And the caching is what makes that approach viable for a large documentation set. Only changed files get re-parsed on subsequent builds, thanks to a git-SHA-based cache. Since the cache key comes from git rather than from file timestamps, a build on a clean checkout and a rebuild after a commit agree about what changed, which is the difference between an incremental build that is reliable and one that is fast but occasionally wrong.

The compatibility rules, and what actually transfers

One detail decides whether a migration is painless. Holocron accepts unknown Mintlify fields via .passthrough(), so you can paste a full Mintlify docs.json without validation errors, and fields Holocron does not consume are silently ignored.

The migration steps are four. Install the dependencies. Create the vite.config.ts. Keep your docs.json, because your existing file works as is and the runtime ignores fields it does not consume. And run npx vite, after which your site should render at the local development address.

The README then lists what transfers directly, and it is a specific list rather than a vague promise. Navigation, meaning tabs, groups, pages, anchors, versions, dropdowns and products. MDX components, meaning accordions, cards, callouts, steps, tabs, code groups and expandables. Frontmatter, with the fields title, description, icon, sidebarTitle, tag, hidden and deprecated. Configuration, with colors, logo, favicon, navbar, footer, redirects, appearance, fonts and banner. And OpenAPI tabs, where a tab object with a tab name and an openapi key generates pages from your spec.

The interesting part of that list is what is missing from the frontmatter. There is no layout, no full, no open, and those are exactly the fields that control whether a Mintlify page renders full-screen or with the sidebar chrome, so a page that used one of them will render differently after the migration even though the file was accepted.

What is deliberately different

The README has a second table, headed what is different, and it is the honest counterpart to the compatibility claims.

Hosting is Mintlify cloud against self-hosted on Node.js or Cloudflare Workers. The build is a cloud build on push against a local vite build. The API playground, which in Mintlify is interactive, becomes a read-only API reference in Holocron. Analytics, built into the Mintlify dashboard, become something you bring yourself. Custom domains, a dashboard setting in Mintlify, become a setting of your hosting provider. And search moves from Algolia or the built-in option to Orama, which is local and needs no configuration.

The Orama point is the one that changes the most in practice, in a good way. A documentation site that needs a hosted search service to answer a query about its own pages has an availability dependency and a configuration dependency, and Orama, which runs in the browser against an index built at deploy time, has neither. The cost is that the search quality and the feature set are Orama's rather than Algolia's.

The analytics row deserves the same treatment. Bringing your own means you can put the data wherever your privacy policy requires, and it also means there is no dashboard unless you set one up.

Taken together, the two tables describe a project that took a managed service and a self-hosted tool and made the second one behave like the first one, without pretending the differences do not exist.

Output that agents can read

Every Holocron site generates AI-friendly endpoints out of the box, and this is the part of the project that is unusual.

There are Markdown routes, where you append .md to any page URL to get the raw markdown of that page. There is an llms.txt endpoint, an index of all pages with their titles and their .md URLs, and the README says agents read this to discover the site structure. And there is a docs.zip endpoint to download every page as an archive.

Alongside those there is skill discovery, and the repository has a skills/ directory and an .agents/ directory, with an AGENTS.md and a MEMORY.md at the root.

The install path for the skills is a single command:

npx -y skills add remorses/holocron -g -y

That installs skills for AI agents like Claude Code, Cursor, Windsurf and others, and the README explains what the skills are for: they teach agents the workflows, the patterns and the tools specific to this project.

So the site is built to be read twice, once by a person in a browser and once by an agent that wants a map of the documentation before it asks anything. That is a different design goal from a documentation site that assumes a human reader, and it explains the .md routes and the llms.txt index, which are otherwise odd things to generate for a documentation site.

Three ways to deploy, and a monorepo with a lot in it

The deploy section covers three targets.

Holocron hosting is the fastest way to get a live URL, building and uploading the site to holocron.so with the CLI deploy command. In GitHub Actions the deploy command uses OIDC tokens automatically, with no API key needed, and you add the id-token write permission to the workflow.

The Node.js route is a local build and then running the output, and the README is explicit that the build output is a standard Node.js server that you can deploy to any platform that runs Node.

The Cloudflare Workers route is the same build followed by a wrangler deploy, with a link to the Cloudflare deploy documentation for the wrangler.jsonc setup.

The repository behind this is large for a documentation tool, and the top-level listing explains why. There is cli/ for the command line tool, hosting/ for the managed hosting, vite/ for the plugin, and website/ for the project site. There is example/ and example-cloudflare/ for the two deployment shapes, template/ for a starting point, and integration-tests/ for the test suite. There are some directories whose purpose the listing does not explain, db/, og-worker/, outrank/ and notaku-shell/, which are worth a look if you are trying to understand the full scope rather than the plugin.

The root package.json is a workspace with two scripts, watch and build, both running recursively over the packages, and the development dependencies include Spiceflow, TypeScript, Vite, Vitest and tsx. It also declares a pnpm setting for only built dependencies, allowing opencode-ai and sharp, which is the kind of detail that matters for a repository that installs native modules.

Editorial conclusion

Adopt Holocron if you have a Mintlify project and want it to build in your own CI on a standard git flow, because the compatibility work is the point and the README claims a migration of about two minutes. Do not adopt it if you need the interactive API playground, since Holocron gives you a read-only reference generated from your OpenAPI spec instead. Before you switch, run through the migration list in the README, since the frontmatter and MDX component sets transfer but the API reference, the analytics and the custom domain handling do not, and check that the licences are what you expect, since the README states MIT while the repository's own licence field is recorded as a custom classification.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. remorses/holocron on GitHub