DOCSEARCHbyAlgolia
Submit Docs

Holocron Documentation Framework

repository·main·Indexed 19 days ago

https://github.com/remorses/holocron

A Vite-based, open-source documentation framework and self-hostable replacement for Mintlify. Holocron uses MDX and a docs.json configuration to generate high-performance sites with built-in search, OpenAPI support, and AI-optimized exports including /llms.txt and .md raw endpoints. It supports deployment to holocron.so, Node.js, and Cloudflare Workers, and provides a CLI for project scaffolding, domain management, and OIDC-authenticated GitHub Actions deploys.

Tokens
128K
Snippets
479
Records
648
Agent score
70%

What's inside Holocron

  1. What is Holocron

    main

    Holocron is an open-source documentation site generator that operates as a Vite plugin. It allows you to write documentation using MDX files and define site navigation via a docs.json configuration file.

    Key capabilities include:

    • Local Builds: Generates static output via vite build for deployment to any hosting provider (e.g., Node.js or Cloudflare Workers).
    • Mintlify Compatibility: Designed as a replacement for Mintlify; it supports existing docs.json structures, common MDX components (Tabs, Cards, Callouts, Steps), and standard frontmatter fields.
    • AI-First Features: Automatically generates AI-readable exports including /llms.txt, /docs.zip, individual .md routes for every page, and .well-known/agent-skills/ for agent discovery.
    • Vite-Native: Leverages Spiceflow (a React Server Components framework) and Tailwind CSS for fast rebuilds and HMR.

  3. Holocron Overview

    main

    Holocron is an open-source documentation site generator designed as a Vite plugin. It serves as a free replacement for Mintlify, allowing developers to write documentation in MDX and configure it via docs.json.

    Key features include:

    • Search functionality
    • OpenAPI specification support for generating API documentation
    • AI-ready exports (e.g., /llms.txt, /docs.zip)
    • Deployment support for various environments (Node.js, Cloudflare Workers, etc.)

  4. Browse Holocron components by use case

    main

    Holocron components are organized into functional categories to help you structure your documentation. Available categories include:

    • Structure content: Columns, cards, steps, tiles, and tree layouts.
    • Draw attention: Callouts, badges, banner config, tooltips, and updates.
    • Show hidden content: Accordions, expandables, tabs, and views.
    • Document APIs: Fields, responses, request examples, response examples, and panel layouts.
    • Visual helpers: Icons, color tokens, frames, mermaid diagrams, and previews.
    • AI-oriented UI: Prompt cards and examples useful for agent-facing docs.

  5. How the AI Assistant works

    main

    The assistant uses the hosted Holocron AI gateway to process questions via Cloudflare Workers AI.

    • Data Flow: The docs app sends the current page content plus either inline docs (local development) or a docs.zip URL (production) to the gateway, which then streams the answer back to the UI.
    • Authentication: Authenticated sites should send a HOLOCRON_KEY. Unauthenticated requests use a temporary fallback with stricter IP rate limits.
    • Default Model: The default model used is GLM 4.7 Flash.
    • Skill Loading: Currently, the built-in docs assistant answers from the current docs content and the docs.zip payload; it does not yet support remote docs.json skill URLs.

  6. Understand the Vite build directory structure

    main

    Running npx vite build generates a dist/ directory containing all necessary files to serve your documentation site. The structure is as follows:

    • dist/rsc/: Contains the server entry point (index.js) and React Server Component files.
    • dist/client/: Contains browser assets, including CSS, JavaScript, and public files.
    • dist/holocron-cache.json: A navigation cache used to accelerate subsequent builds.
    dist/
├── rsc/
│   ├── index.js          # server entry
│   └── ...
├── client/               # browser assets, CSS, JS, public files
└── holocron-cache.json   # Navigation cache for fast rebuilds

  8. Implement the Source-of-Truth pattern for configuration types

    main

    To prevent type mismatches between user input and normalized runtime configuration, follow the Source-of-Truth pattern using Zod.

    The Pattern Workflow

    1. Define Input Shape: Create Zod schemas in vite/src/schema.ts. This is the single source of truth for the raw input shape.
    2. Raw Types: Use HolocronConfigRaw = z.input<typeof holocronConfigSchema> for the shape as written by the user before any normalization occurs.
    3. Normalized Types: Derive runtime types in config.ts using z.output<typeof holocronConfigSchema>. This ensures that if normalize() transforms a field (e.g., converting a string to an object), the type system reflects that change.
    4. Hand-written Wrappers: Only use hand-written types for fields where normalize() collapses unions (e.g., logo, favicon, navigation, navbar, ConfigNavTab).

    Warning: Avoid hand-writing narrower types for fields that are validated by Zod. Always derive from the validation source so the compiler can surface necessary adapters when the schema changes.

  9. Prevent content from bleeding with `no-bleed`

    main

    The .no-bleed class sets --bleed: 0px for all descendants, ensuring that elements like code blocks, lists, and images stay strictly within the container's width.

    Container components such as Callout, Accordion, Expandable, Panel, Steps, and Card apply no-bleed automatically. You can manually apply it to any wrapper to constrain its children.

    <div className='no-bleed'>
  Code blocks and images inside here will not bleed.
</div>

  10. How Imageboard media processing works

    main

    The Imageboard uses a build-time pipeline to optimize media rendering:

    • Images: Dimensions are read using sharp to reserve aspect ratios and prevent layout shifts. A pixelated placeholder is used for instant rendering, followed by a fade-in of the full image. Images use native loading="lazy".
    • Videos: Supports .mp4, .webm, .mov, and .mkv. Dimensions are probed from the container header, and videos use preload="metadata" to minimize initial data usage.
    • Interaction: Clicking a tile opens a zoom dialog.
    • Layout: The grid uses CSS multi-columns where items flow top-to-bottom per column. The layout is responsive; the number of columns shrinks fluidly based on viewport width without requiring manual breakpoint configuration.

  11. Metadata Override Requirements

    main

    When overriding page-level <meta> tags, you must emit every variant of the tag that the site-level layout provides.

    Because Spiceflow's Head component dedups meta tags by key, different keys like meta:property:og:description and meta:name:description are treated as distinct. If the site layout emits both, a page-level override that only emits name="description" will leave the site's og:description intact, leading to inconsistent metadata.

  12. Rules for Sidebar Group Visibility

    main

    When filtering group.hidden: true from the sidebar, the system uses specific logic to decide whether to prune a group or keep it as a section divider. This is implemented via hasVisibleSidebarEntries(group) in navigation.ts.

    Pruning Logic:

    • If group.hidden === true: Prune (always).
    • If group.pages.length === 0: Render (this acts as an intentional section label/divider).
    • If group.pages.length > 0 AND every descendant is hidden: Prune (prevents empty wrappers).
    • Otherwise: Render.