Skip to content
Back to search

holocron

Open source drop-in replacement for Mintlify as a Vite plugin

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/remorses/holocron with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/remorses/holocron'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/remorses--holocron/badge.svg)](/listings/remorses--holocron)

HTML

<a href="/listings/remorses--holocron"><img src="/api/listings/remorses--holocron/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

This installs [skills](https://skills.sh) for AI coding agents like Claude Code, Cursor, Windsurf, and others. Skills teach agents the workflows, patterns, and tools specific to this project.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 273 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align='center' class="hidden">
  2. <br/>
  3. <br/>
  4. <h3>holocron</h3>
  5. <p>Delightful docs. Mintlify drop-in replacement as a Vite plugin.</p>
  6. <br/>
  7. <br/>
  8. </div>
  9. 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.
  10. 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.
  11. ## Install skill for AI agents
  12. ```bash
  13. npx -y skills add remorses/holocron -g -y
  14. ```
  15. This installs [skills](https://skills.sh) for AI coding agents like
  16. Claude Code, Cursor, Windsurf, and others. Skills teach agents the
  17. workflows, patterns, and tools specific to this project.
  18. ## Quickstart
  19. Scaffold a new project with the CLI:
  20. ```bash
  21. npx -y "@holocron.so/cli" create
  22. ```
  23. This creates a working docs site with sample pages, navigation, and a `vite.config.ts`. Run `pnpm install && pnpm dev` and you're live.
  24. ### Manual setup
  25. ```bash
  26. pnpm add @holocron.so/vite react react-dom vite
  27. ```
  28. Create a `vite.config.ts`:
  29. ```ts
  30. import { defineConfig } from 'vite'
  31. import { holocron } from '@holocron.so/vite'
  32. export default defineConfig({
  33. plugins: [holocron()],
  34. })
  35. ```
  36. The plugin auto-adds Spiceflow, Tailwind CSS, and React. No extra setup needed.
  37. Create a `docs.json` at the project root:
  38. ```json
  39. {
  40. "name": "My Docs",
  41. "colors": { "primary": "#6366f1" },
  42. "navigation": [
  43. {
  44. "group": "Getting Started",
  45. "pages": ["index"]
  46. }
  47. ]
  48. }
  49. ```
  50. Write your first page as `index.mdx`:
  51. ```mdx
  52. ---
  53. $schema: https://holocron.so/frontmatter.json
  54. title: Welcome
  55. description: My documentation site.
  56. ---
  57. # Welcome
  58. This is my first Holocron page.
  59. ```
  60. Run the dev server:
  61. ```bash
  62. npx vite
  63. ```
  64. Open `http://localhost:5173` and you should see your docs site.
  65. Build for production:
  66. ```bash
  67. npx vite build
  68. node dist/rsc/index.js
  69. ```
  70. ## What you get
  71. - **Local builds** with `vite build`, deploy the output anywhere
  72. - **Mintlify-compatible** `docs.json` schema and MDX components
  73. - **OpenAPI** reference pages generated from your spec
  74. - **Search** powered by Orama, built into the sidebar
  75. - **Dark mode** with system detection and manual toggle
  76. - **AI exports** for agents: `.md` per page, `/llms.txt`, `/docs.zip`, skill discovery
  77. - **React Server Components** under the hood via Spiceflow and Vite
  78. ## Holocron vs Mintlify
  79. | Area | Mintlify | Holocron |
  80. |------|----------|----------|
  81. | **Hosting** | Cloud only | Self-hosted, or [holocron.so](/docs/deploy/holocron) managed hosting |
  82. | **Build** | Cloud build on push | Local `vite build`, standard CI |
  83. | **Pricing** | Starts at $150/mo | Free, open source ([MIT](https://github.com/remorses/holocron/blob/main/LICENSE)) |
  84. | **Git workflow** | Mintlify-managed deploys | Standard git: PRs, branches, diffs |
  85. | **Config** | `docs.json` | Same `docs.json` (compatible) |
  86. | **Components** | Proprietary MDX set | Same components, open source |
  87. | **API reference** | Interactive playground | Read-only API reference from OpenAPI |
  88. | **Search** | Algolia / built-in | Orama (local, zero config) |
  89. | **Custom domains** | Dashboard setting | Your hosting provider |
  90. | **Analytics** | Built-in dashboard | Bring your own |
  91. | **AI exports** | `/llms.txt`, `.md` routes | `/llms.txt`, `/docs.zip`, `.md` routes, skill discovery |
  92. | **Custom routes** | Not possible | Mount alongside a Spiceflow app |
  93. | **Framework** | Proprietary | Vite + React Server Components |
  94. 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.
  95. ## Migration from Mintlify
  96. In your existing Mintlify docs directory:
  97. **1. Install dependencies**
  98. ```bash
  99. pnpm add @holocron.so/vite react react-dom vite
  100. ```
  101. **2. Create vite.config.ts**
  102. ```ts
  103. import { defineConfig } from 'vite'
  104. import { holocron } from '@holocron.so/vite'
  105. export default defineConfig({
  106. plugins: [holocron()],
  107. })
  108. ```
  109. **3. Keep your docs.json**
  110. Your existing `docs.json` works as-is. Holocron's schema accepts unknown Mintlify fields; the runtime ignores fields it does not consume.
  111. **4. Run it**
  112. ```bash
  113. npx vite
  114. ```
  115. Your site should render at `http://localhost:5173`.
  116. ### What transfers directly
  117. - **Navigation**: tabs, groups, pages, anchors, versions, dropdowns, products
  118. - **MDX components**: Accordions, Cards, Callouts, Steps, Tabs, Code Groups, Expandables
  119. - **Frontmatter**: `title`, `description`, `icon`, `sidebarTitle`, `tag`, `hidden`, `deprecated`
  120. - **Config**: `colors`, `logo`, `favicon`, `navbar`, `footer`, `redirects`, `appearance`, `fonts`, `banner`
  121. - **OpenAPI tabs**: `{ "tab": "API Reference", "openapi": "openapi.json" }` generates pages from your spec
  122. ### What is different
  123. | Area | Mintlify | Holocron |
  124. |------|----------|----------|
  125. | Hosting | Mintlify cloud | Self-hosted (Node.js or Cloudflare Workers) |
  126. | Build | Cloud build on push | Local `vite build` |
  127. | API playground | Interactive playground | Read-only API reference |
  128. | Analytics | Built-in dashboard | Bring your own |
  129. | Custom domains | Dashboard setting | Your hosting provider |
  130. | Search | Algolia/built-in | Orama (local, built-in) |
  131. ## How it works
  132. ```diagram
  133. docs.json + MDX files
  134. │
  135. ▼
  136. ┌────────────────┐
  137. │ Vite Plugin │ reads config, syncs navigation tree, processes MDX
  138. │ (holocron()) │
  139. └───────┬────────┘
  140. │
  141. ▼
  142. ┌────────────────┐
  143. │ Spiceflow │ React Server Components framework
  144. │ + Tailwind │ auto-added by the plugin
  145. └───────┬────────┘
  146. │
  147. ▼
  148. Full docs site with search, OpenAPI, dark mode, AI exports
  149. ```
  150. 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.
  151. ## Deploy
  152. ### Holocron hosting
  153. The fastest way to get a live URL. Builds and uploads your site to `holocron.so`:
  154. ```bash
  155. npx -y "@holocron.so/cli" deploy
  156. ```
  157. In **GitHub Actions**, the deploy command uses OIDC tokens automatically (no API key needed). Add `permissions: id-token: write` to your workflow.
  158. ### Node.js
  159. ```bash
  160. npx vite build
  161. node dist/rsc/index.js
  162. ```
  163. The build output is a standard Node.js server. Deploy it to any platform that runs Node.
  164. ### Cloudflare Workers
  165. ```bash
  166. npx vite build
  167. npx wrangler deploy
  168. ```
  169. See [Cloudflare deploy docs](/docs/deploy/cloudflare) for `wrangler.jsonc` setup.
  170. ## AI-readable docs
  171. Every Holocron site generates AI-friendly endpoints out of the box:
  172. - **`.md` routes**: append `.md` to any page URL to get raw markdown. `https://your-site.com/quickstart.md`
  173. - **`/llms.txt`**: an index of all pages with titles and `.md` URLs. Agents read this to discover the site structure.
  174. - **`/docs.zip`**: download every page as a `.md` file in one zip. Agents can grep it locally.
  175. - **Skill discovery**: `/.well-known/agent-skills/index.json` exposes your docs as an installable AI skill.
  176. ```bash
  177. curl https://your-site.com/llms.txt
  178. curl -L https://your-site.com/docs.zip -o docs.zip
  179. ```
  180. ## Project structure
  181. ```diagram
  182. my-docs/
  183. ├── index.mdx # pages are MDX files
  184. ├── guides/
  185. │ ├── install.mdx
  186. │ └── deploy.mdx
  187. ├── docs.json # navigation and config
  188. ├── vite.config.ts # one-line plugin setup
  189. ├── package.json
  190. └── public/ # static assets (logos, images)
  191. ```
  192. ## Explore
  193. Full documentation at **[holocron.so](https://holocron.so)**.
  194. - [Quickstart](/docs/quickstart)
  195. - [Navigation](/docs/organize/navigation): tabs, groups, pages, anchors, versions, dropdowns
  196. - [Theme and Colors](/docs/customize/theme): shadcn-compatible CSS variables
  197. - [OpenAPI Reference](/docs/api-docs/openapi): generate API docs from a spec
  198. - [MDX Components](/docs/components): Accordions, Cards, Callouts, Steps, Tabs, and more
  199. - [Deploy](/docs/deploy/node): Node.js, Cloudflare Workers, and holocron.so hosting
  200. ## License
  201. [MIT](https://github.com/remorses/holocron/blob/main/LICENSE). If you use Holocron for your docs, please keep the "Powered by Holocron" footer link. It helps others discover the project.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.