Holocron

https://holocron.so/docs
Admin
Holocron is a documentation site generator built as a Vite plugin, designed as a Mintlify-compatible...
Tokens:37,979
Snippets:523
Trust Score:7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Docker Production Setup

Source: https://holocron.so/docs/deploy/node

A Dockerfile example for deploying the Node.js application. It installs dependencies, builds the project, and exposes the default port.

```dockerfile
FROM node:22-slim
WORKDIR /app
COPY package.json pnpm-lock.yaml ./ 
RUN corepack enable && pnpm install --frozen-lockfile
COPY . .
RUN pnpm build
EXPOSE 3000
CMD ["node", "dist/rsc/index.js"]
```

--------------------------------

### Running a Development Server

Source: https://holocron.so/docs/components/panel

Use this command to start the development server for the website. Ensure you have pnpm installed and are in the correct project directory.

```bash
pnpm -F website dev
```

--------------------------------

### Start the Node.js Server

Source: https://holocron.so/docs/deploy/node

Execute this command to start the Holocron Node.js server after building.

```bash
node dist/rsc/index.js
```

--------------------------------

### Known Paths with Navigation Example

Source: https://holocron.so/docs/create/broken-links

This example shows how to configure `knownPaths` alongside navigation in a project that serves both documentation and an API.

```json
{
  "navigation": [
    { "group": "Docs", "pages": ["index", "quickstart"] }
  ],
  "knownPaths": ["/api/*", "/health"]
}
```

--------------------------------

### Install MCP SDK

Source: https://holocron.so/docs/mcp-export

Install the necessary SDK package using npm. This is a prerequisite for running the export script.

```bash
npm install @modelcontextprotocol/sdk
```

--------------------------------

### Run the Vite Development Server

Source: https://holocron.so/docs/migration

Start the local development server to preview your documentation site. The site will be accessible at http://localhost:5173.

```bash
npx vite
```

--------------------------------

### Install Wrangler and Cloudflare Vite Plugin

Source: https://holocron.so/docs/deploy/cloudflare

Install the required packages for Cloudflare deployment using pnpm.

```bash
pnpm add -D wrangler @cloudflare/vite-plugin
```

--------------------------------

### OpenAPI Path Definition with Example

Source: https://holocron.so/docs/api-docs/request-response-examples

This YAML snippet shows an OpenAPI path definition for a GET request to /users. It includes a 200 response with a JSON schema and an example response body.

```yaml
paths:
  /users:
    get:
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
              example:
                - id: 1
                  name: Alice
                - id: 2
                  name: Bob
```

--------------------------------

### POST Request Example

Source: https://holocron.so/docs/components/examples

This snippet shows a cURL command for making a POST request to an example API endpoint. It includes the necessary content-type header and a JSON payload.

```bash
curl -X POST https://example.com/docs \
  -H "content-type: application/json" \
  -d '{"slug":"components/examples"}'
```

--------------------------------

### Full docs.json Configuration Reference

Source: https://holocron.so/docs/organize/docs-json

An extensive configuration example demonstrating all available options for Holocron sites, including theming, logos, navigation tabs, footer socials, and more.

```json
{
  "$schema": "https://holocron.so/docs.json",
  "name": "My Docs",
  "description": "Documentation for my project",
  "colors": { "primary": "#6366f1" },
  "logo": {
    "light": "/logo-light.svg",
    "dark": "/logo-dark.svg"
  },
  "favicon": "/favicon.svg",
  "appearance": { "default": "system" },
  "fonts": { "family": "Inter" },
  "icons": { "library": "lucide" },
  "navbar": {
    "links": [
      { "type": "github", "href": "https://github.com/example/docs" }
    ]
  },
  "banner": {
    "content": "New: [v2.0 is out](/changelog)",
    "dismissible": true
  },
  "navigation": {
    "tabs": [
      {
        "tab": "Documentation",
        "groups": [
          { "group": "Getting Started", "pages": ["index", "quickstart"] }
        ]
      },
      {
        "tab": "API Reference",
        "openapi": "openapi.json"
      }
    ]
  },
  "footer": {
    "socials": {
      "github": "https://github.com/example",
      "x": "https://x.com/example",
      "discord": "https://discord.gg/example"
    }
  },
  "redirects": [
    { "source": "/old", "destination": "/new" }
  ],
  "knownPaths": ["/api/*", "/dashboard"],
  "search": { "prompt": "Search docs..." },
  "seo": {
    "metatags": { "author": "My Company" }
  },
  "assistant": { "enabled": true }
}
```

--------------------------------

### Remote Image Example

Source: https://holocron.so/docs/create/images

Remote image URLs are supported. Remote URLs in JSX `<img>` tags can be fetched for metadata at build time. Markdown remote images render but do not get build-time dimensions or placeholders.

```mdx
<img src="https://example.com/photo.jpg" alt="Remote photo" />
```

--------------------------------

### Holocron Configuration Example

Source: https://holocron.so/docs/mcp-export

Example of how to configure Holocron to use the generated MCP definitions file. This JSON snippet should be added to your 'docs.json'.

```json
{
  "tab": "MCP Tools",
  "mcp": "mcp-tools.json"
}
```

--------------------------------

### Basic Dropdown Configuration

Source: https://holocron.so/docs/organize/dropdowns

Configure multiple dropdowns, each with its own tabs and groups, to organize documentation content. This setup is used for switching between different products or sections.

```json
{
  "navigation": {
    "dropdowns": [
      {
        "dropdown": "Platform",
        "tabs": [
          {
            "tab": "Docs",
            "groups": [
              { "group": "Overview", "pages": ["platform/index"] }
            ]
          }
        ]
      },
      {
        "dropdown": "CLI",
        "tabs": [
          {
            "tab": "Docs",
            "groups": [
              { "group": "Overview", "pages": ["cli/index"] }
            ]
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### Markdown Image Example

Source: https://holocron.so/docs/create/images

Use standard Markdown image syntax for local images. Place image files in your `public/` directory and reference them with absolute paths.

```mdx
![Alt text](/images/screenshot.png)
```

--------------------------------

### Code Group: pnpm Installation

Source: https://holocron.so/docs/create/code

Installs the @holocron.so/vite package using pnpm.

```bash
pnpm add @holocron.so/vite
```

--------------------------------

### Custom Entry Setup with API Routes and Middleware

Source: https://holocron.so/docs/spiceflow

Demonstrates how to configure a custom entry point for Holocron to integrate Spiceflow, allowing for custom API routes, middleware, and mounting the Holocron app.

```APIDOC
## Custom Entry Setup

To extend your documentation site with custom functionality, you can create a custom entry file for the Holocron plugin.

### Configuration (`vite.config.ts`)

Pass the `entry` option to the `holocron` plugin to specify your custom server file.

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

export default defineConfig({
  plugins: [
    holocron({ entry: './src/server.tsx' }),
  ],
})
```

### Server File (`src/server.tsx`)

Create a server file that initializes a `Spiceflow` app. You can define your own API routes and middleware before mounting the Holocron app using `.use()`. This ensures your custom routes are prioritized.

```tsx
// src/server.tsx
import { Spiceflow } from 'spiceflow'
import { app as holocronApp } from '@holocron.so/vite/app'

export const app = new Spiceflow()
  // Define custom API routes
  .get('/api/health', () => ({ status: 'ok' }))
  .post('/api/webhook', async ({ request }) => {
    const body = await request.json()
    // process webhook...
    return { received: true }
  })
  // Mount the Holocron app last to handle documentation pages
  .use(holocronApp)
```

Requests are first checked against your custom routes. If no custom route matches, the request is passed to the `holocronApp` to serve documentation pages, search, and assets.
```

--------------------------------

### Markdown Table Example

Source: https://holocron.so/docs/create/mdx

Illustrates how to create tables in MDX, which will be rendered with Holocron's editorial styling.

```mdx
| Method | Path | Description |
|--------|------|-------------|
| GET | /users | List users |
| POST | /users | Create user |
```

--------------------------------

### Code Group: yarn Installation

Source: https://holocron.so/docs/create/code

Installs the @holocron.so/vite package using yarn.

```bash
yarn add @holocron.so/vite
```

--------------------------------

### Markdown Links Example

Source: https://holocron.so/docs/create/broken-links

These are examples of markdown links that Holocron checks. Ensure these links point to existing pages.

```mdx
[Getting Started](/getting-started)
[Next section](./next)
[Parent page](../overview)
```

--------------------------------

### Custom Spiceflow App Setup

Source: https://holocron.so/docs/spiceflow

Create a custom Spiceflow app in your server file. Import the holocron app and mount it last using `.use()` so your custom routes and middleware take precedence.

```tsx
import { Spiceflow } from 'spiceflow'
import { app as holocronApp } from '@holocron.so/vite/app'

export const app = new Spiceflow()
  // API routes
  .get('/api/health', () => ({ status: 'ok' }))
  .post('/api/webhook', async ({ request }) => {
    const body = await request.json()
    // process webhook...
    return { received: true }
  })
  // mount holocron last — it handles all docs pages
  .use(holocronApp)
```

--------------------------------

### Mixing Guides with Tool Pages

Source: https://holocron.so/docs/mcp-tools

Interleave hand-written MDX pages with auto-generated tool pages using selective mode by defining groups and pages.

```json
{
  "tab": "MCP Tools",
  "mcp": "mcp-tools.json",
  "groups": [
    {
      "group": "Getting Started",
      "pages": ["mcp/overview", "mcp/authentication"]
    },
    {
      "group": "Database",
      "pages": ["query_database", "..."]
    }
  ]
}
```

--------------------------------

### GitHub Actions Deploy with Base Path

Source: https://holocron.so/docs/deploy/base-path

Example GitHub Actions workflow to deploy documentation using the `@holocron.so/cli` with the `--base-path` option set to `/docs`.

```yaml
name: Deploy docs
on:
  push:
    branches: [main]

permissions:
  id-token: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm install
      - run: npx -y @holocron.so/cli deploy --base-path /docs
```

--------------------------------

### Holocron Documentation Configuration

Source: https://holocron.so/docs/components/code-groups

Example JSON configuration for Holocron documentation, specifying the project name and navigation structure. This is shown in `docs.json`.

```json
{
  "name": "Holocron Docs",
  "navigation": [{ "group": "Guides", "pages": ["index"] }]
}
```

--------------------------------

### TanStack Start API Route for Proxying Docs

Source: https://holocron.so/docs/deploy/base-path

Use this server-only route to proxy requests to the documentation base URL. It captures the path and forwards the request.

```typescript
// app/routes/docs/$.ts
import { createAPIFileRoute } from '@tanstack/react-start/api'

const DOCS_URL = 'https://docs-base-my-docs-remorses-site.holocron.so'

function proxy(request: Request) {
  const url = new URL(request.url)
  const target = new URL(url.pathname + url.search, DOCS_URL)
  return fetch(target, {
    method: request.method,
    headers: { 'X-Forwarded-Host': url.hostname },
    body: request.method !== 'GET' && request.method !== 'HEAD'
      ? request.body
      : undefined,
  })
}

export const APIRoute = createAPIFileRoute('/docs/$')({
  GET: ({ request }) => proxy(request),
  POST: ({ request }) => proxy(request),
})
```

--------------------------------

### Sequence Diagram

Source: https://holocron.so/docs/components/mermaid-diagrams

Example of a sequence diagram using mermaid syntax within a Mermaid component.

```mermaid
sequenceDiagram
participant Author
participant Holocron
participant Browser
Author->>Holocron: write docs.json + MDX
Holocron->>Browser: stream rendered page
Browser-->>Author: interactive docs UI
```

--------------------------------

### Install Holocron Vite Dependencies with pnpm

Source: https://holocron.so/docs/components/code-groups

Install the necessary Holocron Vite packages and their peer dependencies using pnpm. This command includes `@holocron.so/vite`, `react`, `react-dom`, and `vite`.

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

--------------------------------

### Install Holocron Vite Dependencies with npm

Source: https://holocron.so/docs/components/code-groups

Install the necessary Holocron Vite packages and their peer dependencies using npm. This command includes `@holocron.so/vite`, `react`, `react-dom`, and `vite`.

```bash
npm install @holocron.so/vite react react-dom vite
```

--------------------------------

### Prompt with Description and Icon

Source: https://holocron.so/docs/components/prompt

Use this snippet to display a prompt with an associated description and icon. This is useful for guiding AI actions or documenting specific workflows.

```html
<Prompt description="Ask Holocron to explain a component difference" icon="sparkles">
  Compare Holocron's `Tabs` implementation with Mintlify's `Tabs` docs and list any unsupported behavior.
</Prompt>
```

--------------------------------

### JSON Response Example

Source: https://holocron.so/docs/components/examples

This snippet provides a sample JSON response from an API. It indicates a successful operation with an 'ok' status and the identifier of the requested page.

```json
{
  "ok": true,
  "page": "components/examples"
}
```

--------------------------------

### Example Panel Response

Source: https://holocron.so/docs/components/panel

This JSON object represents a typical response when a panel component is rendered. It includes the URL and rendering status.

```json
{
  "url": "/components/panel",
  "status": "rendered"
}
```

--------------------------------

### Flowchart Diagram

Source: https://holocron.so/docs/components/mermaid-diagrams

Example of a flowchart diagram using mermaid syntax within a Mermaid component.

```mermaid
flowchart LR
A[MDX source] --> B[Holocron parser]
B --> C[Rendered editorial page]
```

--------------------------------

### systemd Service Configuration

Source: https://holocron.so/docs/deploy/node

A systemd unit file example to manage the Node.js server as a service. It defines the service description, working directory, execution command, and restart policy.

```ini
[Unit]
Description=Docs site
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/docs
ExecStart=/usr/bin/node dist/rsc/index.js
Restart=on-failure

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Serving Extra Files and Redirects

Source: https://holocron.so/docs/spiceflow

Serve custom files like 'llms.txt' or implement custom redirects using Spiceflow routes. This example shows how to serve raw file content and perform a 302 redirect.

```tsx
import readmeRaw from '../README.md?raw'

export const app = new Spiceflow()
  .get('/llms.txt', () => {
    return new Response(readmeRaw, {
      headers: { 'Content-Type': 'text/plain' },
    })
  })
  .get('/gh', ({ request }) => {
    return Response.redirect('https://github.com/example/repo', 302)
  })
  .use(holocronApp)
```

--------------------------------

### Expandable Component Example

Source: https://holocron.so/docs/components/expandables

Demonstrates how to use the Expandable component to hide and show advanced options. It supports custom titles and can be set to be open by default. Nested markdown and code blocks are also supported within the expandable content.

```html
<Expandable title="Show advanced options" defaultOpen>
  Expandables work well for secondary details, object internals, or long examples that should not dominate the page.

  * Nested markdown is supported
  * Code blocks are supported

  ```json
  { "advanced": true, "source": "holocron" }
  ```
</Expandable>
```

--------------------------------

### Absolute Imports

Source: https://holocron.so/docs/create/local-imports

Import components using absolute paths starting with '/'. Holocron checks the pages directory first, then the project root.

```mdx
import { Chart } from '/components/chart'
```

--------------------------------

### Basic Linked Card Example

Source: https://holocron.so/docs/components/cards

Use a card as a navigational block inside a docs page. This snippet demonstrates a basic card with a title, icon, and a link.

```javascript
<Card title="Basic linked card" icon="arrow-right" href="/docs/components/code-groups">
  Use a card as a navigational block inside a docs page.
</Card>
```

--------------------------------

### Mixing Guides and Endpoint Pages

Source: https://holocron.so/docs/api-docs/openapi

Configure an OpenAPI tab in selective mode to interleave hand-written pages with specific endpoints. Use 'groups' or 'pages' arrays to define the order and content.

```json
{
  "tab": "API Reference",
  "openapi": "openapi.json",
  "groups": [
    {
      "group": "Getting Started",
      "pages": [
        "api/overview",
        "api/authentication",
        "POST /auth/login",
        "GET /users"
      ]
    },
    {
      "group": "Orders",
      "pages": ["api/orders-intro", "POST /orders"]
    }
  ]
}
```

--------------------------------

### HTML img Tag Example

Source: https://holocron.so/docs/create/images

You can also use `<img>` tags. Holocron's remark plugin converts these to its internal image component with dimensions when it can read image metadata.

```mdx
<img src="/images/diagram.png" alt="Architecture diagram" />
```

--------------------------------

### Write Your First MDX Page

Source: https://holocron.so/docs/quickstart

Create an index.mdx file to define your first documentation page. This includes frontmatter for title and description, and the page content.

```mdx
---
title: Welcome
description: My documentation site.
---

# Welcome

This is my first Holocron page.
```

--------------------------------

### Download and Search All Docs

Source: https://holocron.so/docs/ai/llms-txt

Use this command to download all documentation as a zip file and then search across all markdown files locally. This is useful for comprehensive searches.

```bash
curl -L https://example.com/docs.zip -o docs.zip
unzip docs.zip -d docs
grep -R "search term" docs/
```

--------------------------------

### Build the Vite Project

Source: https://holocron.so/docs/deploy/node

Run this command to create a production bundle for your Node.js server.

```bash
npx vite build
```

--------------------------------

### Basic Tile Usage

Source: https://holocron.so/docs/components/tiles

Demonstrates how to use the Tile component to create visual preview links for different sections. Each tile includes a title, description, and a simple preview element.

```javascript
<Columns cols={2}>
  <Tile href="/docs/components/accordions" title="Accordions" description="Disclosure patterns and grouped accordions">
    <div className="rounded-md bg-muted p-6 text-center">Accordion preview</div>
  </Tile>

  <Tile href="/docs/components/color" title="Color" description="Palette and token documentation">
    <div className="rounded-md bg-muted p-6 text-center">Color preview</div>
  </Tile>
</Columns>
```

--------------------------------

### Basic Holocron Deployment

Source: https://holocron.so/docs/deploy/holocron

Run the basic deploy command to build your docs site and upload it to Holocron hosting. This command handles the build process, uploads only changed files, finalizes the deployment, and outputs the live URL.

```bash
npx -y @holocron.so/cli deploy
```

--------------------------------

### Build Website Package

Source: https://holocron.so/docs/components/update

Command to build the website package for the Holocron project.

```bash
pnpm -F website build
```

--------------------------------

### Deploy Docs with Subpath Hosting

Source: https://holocron.so/docs/pricing

Use this command to deploy your documentation site with a specified base path, enabling subpath hosting on your own domain. This requires a reverse proxy or rewrite configuration in your framework to direct traffic correctly.

```bash
npx -y @holocron.so/cli deploy --base-path /docs
```

--------------------------------

### Marquee with Disabled Fade

Source: https://holocron.so/docs/components/marquee

Disable edge fading by setting the `fade` prop to `false`. This example also customizes duration and gap.

```javascript
<Marquee fade={false} duration={18} gap={48}>
  <Icon icon="lucide:terminal" size={28} color="var(--muted-foreground)" />

  <Icon icon="lucide:monitor" size={28} color="var(--muted-foreground)" />

  <Icon icon="lucide:cpu" size={28} color="var(--muted-foreground)" />

  <Icon icon="lucide:hard-drive" size={28} color="var(--muted-foreground)" />

  <Icon icon="lucide:wifi" size={28} color="var(--muted-foreground)" />

  <Icon icon="lucide:bluetooth" size={28} color="var(--muted-foreground)" />
</Marquee>
```

--------------------------------

### Holocron Build Process Diagram

Source: https://holocron.so/docs/what-is-holocron

Illustrates the workflow from `docs.json` and MDX files through the Vite plugin and Spiceflow to the final documentation site.

```diagram
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
```

--------------------------------

### Create Holocron Configuration File

Source: https://holocron.so/docs/quickstart

Create a docs.json file at the project root to configure your documentation site's name, theme colors, and navigation structure.

```json
{
  "name": "My Docs",
  "colors": { "primary": "#6366f1" },
  "navigation": [
    {
      "group": "Getting Started",
      "pages": ["index"]
    }
  ]
}
```

--------------------------------

### Build and Deploy Commands

Source: https://holocron.so/docs/deploy/cloudflare

Build your project and deploy it to Cloudflare Workers using wrangler.

```bash
npx vite build
npx wrangler deploy
```

--------------------------------

### JSX Component Hrefs Example

Source: https://holocron.so/docs/create/broken-links

Holocron checks href attributes on specific JSX components. Ensure these hrefs resolve to valid pages.

```mdx
<Card href="/quickstart">Get Started</Card>
<Tile href="/guides/deploy">Deploy</Tile>
<a href="/api/overview">API Reference</a>
```

--------------------------------

### Normal Build Directory Structure

Source: https://holocron.so/docs/deploy/build-output

Illustrates the typical directory structure generated by a Vite build, including server entry points, browser assets, and navigation cache files.

```diagram
dist/
├── rsc/
│   ├── index.js          # server entry
│   └── ...
├── client/               # browser assets, CSS, JS, public files
└── holocron-cache.json   # Navigation cache for fast rebuilds
```

--------------------------------

### Basic Version Configuration

Source: https://holocron.so/docs/organize/versions

This JSON configuration sets up a version switcher with two versions, 'v2' and 'v1'. 'v2' is marked as the default version. Each version includes tabs and groups for organizing documentation pages.

```json
{
  "navigation": {
    "versions": [
      {
        "version": "v2",
        "default": true,
        "tabs": [
          {
            "tab": "Docs",
            "groups": [
              { "group": "Getting Started", "pages": ["v2/index", "v2/quickstart"] }
            ]
          }
        ]
      },
      {
        "version": "v1",
        "tabs": [
          {
            "tab": "Docs",
            "groups": [
              { "group": "Getting Started", "pages": ["v1/index", "v1/quickstart"] }
            ]
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### Intro Page with Remaining Endpoints

Source: https://holocron.so/docs/api-docs/openapi

Use the special '...' entry to include a short intro page followed by all remaining endpoints, grouped by tag. This allows for a custom intro while auto-including the rest of the API.

```json
{
  "tab": "API Reference",
  "openapi": "openapi.json",
  "pages": ["api/authentication", "..."]
}
```

--------------------------------

### Create a New Holocron Project via CLI

Source: https://holocron.so/docs/api-docs/authentication

Use this command to create a new project if you do not already have one. The project will be named 'My Docs'.

```bash
npx -y @holocron.so/cli projects create --name "My Docs"
```

--------------------------------

### Basic Redirect Configuration

Source: https://holocron.so/docs/create/redirects

Define a list of redirects in your `docs.json` file. Each object specifies a source path and its corresponding destination.

```json
{
  "redirects": [
    { "source": "/old-page", "destination": "/new-page" },
    { "source": "/guides/:slug", "destination": "/docs/:slug" }
  ]
}
```

--------------------------------

### Wrangler Configuration

Source: https://holocron.so/docs/deploy/cloudflare

Create a wrangler.jsonc file with your project name, entry point, and compatibility settings.

```jsonc
{
  "name": "my-docs",
  "main": "spiceflow/cloudflare-entrypoint",
  "compatibility_date": "2026-04-13",
  "compatibility_flags": ["nodejs_compat"]
}
```

--------------------------------

### Basic Markdown Syntax

Source: https://holocron.so/docs/create/mdx

Demonstrates standard Markdown elements like headings, lists, links, and inline code.

```mdx
# Heading 1
## Heading 2
### Heading 3

Regular paragraph text with **bold**, *italic*, and `inline code`.

- Bullet list
- Another item

1. Numbered list
2. Second item

> Blockquote text

[Link text](https://example.com)
```

--------------------------------

### Vite Configuration for Cloudflare Deployment

Source: https://holocron.so/docs/spiceflow

Configure your Vite build process to include the Cloudflare plugin after the Holocron plugin. This setup is essential for deploying to Cloudflare Workers.

```ts
import { cloudflare } from '@cloudflare/vite-plugin'
import { holocron } from '@holocron.so/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    holocron({ entry: './src/server.tsx' }),
    cloudflare({
      viteEnvironment: {
        name: 'rsc',
        childEnvironments: ['ssr'],
      },
    }),
  ],
})
```

--------------------------------

### Horizontal Card Example

Source: https://holocron.so/docs/components/cards

Horizontal layout for cards is suitable for denser landing pages. This snippet shows a horizontal card with a title, icon, link, and a call to action.

```javascript
<Card title="Horizontal card" icon="panel-left" horizontal href="/docs/components/columns" cta="Open page">
  Horizontal layout works for denser landing pages.
</Card>
```

--------------------------------

### Nginx Configuration for Docs Proxy

Source: https://holocron.so/docs/deploy/base-path

Configure an Nginx location block to proxy requests starting with `/docs/` to the specified documentation server. Includes a redirect for the root `/docs` path.

```nginx
location /docs/ {
    proxy_pass https://docs-base-my-docs-remorses-site.holocron.so/docs/;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Real-IP $remote_addr;
}

location = /docs {
    return 301 /docs/;
}
```

--------------------------------

### Connect to Live MCP Server

Source: https://holocron.so/docs/mcp-tools

Alternatively, specify a remote MCP server URL directly in your docs.json to connect via Streamable HTTP transport at build time.

```json
{
  "tab": "MCP Tools",
  "mcp": "https://api.example.com/mcp"
}
```

--------------------------------

### Download and Unzip Documentation

Source: https://holocron.so/docs/ai/docs-zip

Use curl to download the docs.zip archive and unzip it to a local directory for offline access or processing.

```bash
curl -L https://your-docs-site.com/docs.zip -o docs.zip
unzip docs.zip -d docs
```

--------------------------------

### Get Initial Theme Class from Cookie

Source: https://holocron.so/docs/custom-entry

Reads the 'color-theme' cookie on the server to set the initial class on the <html> element before the page paints. This ensures consistent theme rendering.

```tsx
function getInitialThemeClass(request: Request) {
  const cookie = request.headers.get('cookie') ?? ''
  return /(?:^|;\s*)color-theme=dark(?:;|$)/.test(cookie) ? 'dark' : undefined
}

export const app = new Spiceflow()
  .layout('/dashboard/*', ({ children, request }) => (
    <html lang='en' className={getInitialThemeClass(request)} suppressHydrationWarning>
      <body>{children}</body>
    </html>
  ))
```

--------------------------------

### Icon Carousel with Marquee

Source: https://holocron.so/docs/components/marquee

Demonstrates scrolling a set of icons using the Marquee component. Customize icon size and color as needed for visual appeal. This example uses Lucide icons.

```mdx
<Marquee duration={15} slowOnHover gap={48}>
  <Icon icon="lucide:rocket" size={28} color="var(--muted-foreground)" />
  <Icon icon="lucide:zap" size={28} color="var(--muted-foreground)" />
  <Icon icon="lucide:shield" size={28} color="var(--muted-foreground)" />
  <Icon icon="lucide:database" size={28} color="var(--muted-foreground)" />
</Marquee>
```

--------------------------------

### Custom Intro Content for Changelog

Source: https://holocron.so/docs/changelog-tab

Prepend custom MDX content to the changelog page by referencing an MDX file using the 'initialContent' field. The content of the referenced file will be spliced above the release entries.

```json
{
  "tab": "Changelog",
  "changelog": "https://github.com/owner/repo",
  "initialContent": "changelog/intro"
}
```

--------------------------------

### Using Built-in MDX Components

Source: https://holocron.so/docs/create/mdx

Shows how to use Holocron's pre-built components like `Note` and `Steps` directly within MDX without explicit imports.

```mdx
<Note>
This is a note callout. No import needed.
</Note>

<Steps>
  <Step title="First step">
    Do this first.
  </Step>
  <Step title="Second step">
    Then do this.
  </Step>
</Steps>
```

--------------------------------

### Image Card Example

Source: https://holocron.so/docs/components/cards

Cards can include an optional image in the header using the `img` prop. The `arrow` prop adds a directional indicator. This snippet demonstrates an image card with a title, icon, link, image, and arrow.

```javascript
<Card title="Image card" icon="image" href="/docs/components/cards" img="https://placehold.co/1200x600/101828/ffffff?text=Holocron+Card+Preview" arrow>
  Cards support an optional `img` prop for a header image. The `arrow` prop adds a directional indicator.
</Card>
```

--------------------------------

### TypeScript Script to Export MCP Definitions

Source: https://holocron.so/docs/mcp-export

This script connects to an MCP server, fetches tools, resources, and prompts, and saves them to a JSON file. Ensure the MCP SDK is installed and provide the MCP server URL as a command-line argument.

```typescript
import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
import fs from 'node:fs'

const url = process.argv[2]
if (!url) {
  console.error('Usage: npx tsx scripts/export-mcp.ts <MCP_SERVER_URL>')
  process.exit(1)
}

const client = new Client({ name: 'holocron-export', version: '1.0.0' })
const transport = new StreamableHTTPClientTransport(new URL(url))

await client.connect(transport)
console.log('Connected to', url)

const [toolsResult, resourcesResult, promptsResult] = await Promise.all([
  client.listTools().catch(() => ({ tools: [] })),
  client.listResources().catch(() => ({ resources: [] })),
  client.listPrompts().catch(() => ({ prompts: [] })),
])

const output = {
  serverUrl: url,
  tools: toolsResult.tools ?? [],
  resources: resourcesResult.resources ?? [],
  prompts: promptsResult.prompts ?? [],
}

await client.close()

const outPath = 'mcp-tools.json'
fs.writeFileSync(outPath, JSON.stringify(output, null, 2) + '\n')
console.log(`Wrote ${output.tools.length} tools, ${output.resources.length} resources, ${output.prompts.length} prompts to ${outPath}`)
```

--------------------------------

### Minimal docs.json Configuration

Source: https://holocron.so/docs/organize/docs-json

A basic configuration for a Holocron site, including the site name and navigation structure.

```json
{
  "name": "My Docs",
  "navigation": [
    {
      "group": "Getting Started",
      "pages": ["index", "quickstart"]
    }
  ]
}
```

--------------------------------

### Configure Navbar Links and Primary CTA

Source: https://holocron.so/docs/customize/navbar-footer-banner

Set up navigation links, including platform-specific ones like GitHub, and define a primary call-to-action button for the navbar.

```json
{
  "navbar": {
    "links": [
      { "type": "github", "href": "https://github.com/example/docs" },
      { "label": "Blog", "href": "https://example.com/blog" }
    ],
    "primary": {
      "type": "button",
      "label": "Get Started",
      "href": "/quickstart"
    }
  }
}
```

--------------------------------

### Importing README for GitHub and Holocron

Source: https://holocron.so/docs/create/local-imports

Import a README.md file to render content on both GitHub and the Holocron site. Ensure links within the README use correct relative paths to real files.

```mdx
README.md   [pricing](./docs/pricing.md)   ◄── correct relative path to a real file
        │
        ├───────────────────────► GitHub opens ./docs/pricing.md
        │
        ▼  imported into the index page
   Holocron recomputes the path ──► strips .md ──► lands on the page rendering pricing
        │
        ▼
   /docs/pricing   ◄── resolves as long as a page renders that file and it is in docs.json
```

--------------------------------

### React Router splat route loader and action

Source: https://holocron.so/docs/deploy/base-path

Implement a splat resource route in React Router to handle GET requests (loader) and other HTTP methods (action) for the /docs/* path. This forwards requests to the Holocron deployment, preserving headers and body.

```typescript
// app/routes/docs.$.ts
const DOCS_URL = 'https://docs-base-my-docs-remorses-site.holocron.so'

export async function loader({ request }: { request: Request }) {
  const url = new URL(request.url)
  const target = new URL(url.pathname + url.search, DOCS_URL)
  return fetch(target, {
    headers: {
      'X-Forwarded-Host': url.hostname,
    },
  })
}

export async function action({ request }: { request: Request }) {
  const url = new URL(request.url)
  const target = new URL(url.pathname + url.search, DOCS_URL)
  return fetch(target, {
    method: request.method,
    headers: request.headers,
    body: request.body,
  })
}
```

--------------------------------

### Local Deployment Login and Deploy

Source: https://holocron.so/docs/deploy/holocron

For local deployments, log in to your Holocron account first using the CLI, then execute the deploy command. This ensures your local environment is authenticated for deployment.

```bash
npx -y @holocron.so/cli login
npx -y @holocron.so/cli deploy
```

--------------------------------

### Basic Tree Structure

Source: https://holocron.so/docs/components/tree

Demonstrates how to use the Tree component to render a nested file and folder hierarchy. Includes folders with default open states and files.

```jsx
<Tree>
  <Tree.Folder name="website" defaultOpen>
    <Tree.File name="docs.json" />

    <Tree.File name="index.mdx" />

    <Tree.Folder name="components" defaultOpen>
      <Tree.File name="accordions.mdx" />

      <Tree.File name="tabs.mdx" />

      <Tree.File name="view.mdx" />
    </Tree.Folder>
  </Tree.Folder>

  <Tree.Folder name="vite" openable={false}>
    <Tree.File name="src/" />
  </Tree.Folder>
</Tree>
```

--------------------------------

### Deploy with a base path

Source: https://holocron.so/docs/deploy/base-path

Use the --base-path flag with the Holocron CLI to deploy your documentation to a specific subpath. This command prefixes all routes and assets under the specified path.

```bash
HOLOCRON_KEY=holo_xxx npx -y @holocron.so/cli deploy --base-path /docs
```

--------------------------------

### Serving Extra Files and Custom Redirects

Source: https://holocron.so/docs/spiceflow

Shows how to serve additional static files or implement custom redirects using Spiceflow routes, such as serving a raw text file or redirecting to an external URL.

```APIDOC
## Serving Extra Files

Spiceflow allows you to define custom routes for serving static files or implementing specific redirect logic beyond what `docs.json` can handle.

### Serving a Raw Text File (`llms.txt`)

This example demonstrates serving the content of a README file as a raw text response.

```tsx
import readmeRaw from '../README.md?raw'

export const app = new Spiceflow()
  .get('/llms.txt', () => {
    return new Response(readmeRaw, {
      headers: { 'Content-Type': 'text/plain' },
    })
  })
  // ... other routes and .use(holocronApp)
```

### Custom Redirect (`/gh` to GitHub)

This example shows how to create a custom redirect route.

```tsx
export const app = new Spiceflow()
  .get('/gh', ({ request }) => {
    return Response.redirect('https://github.com/example/repo', 302)
  })
  // ... other routes and .use(holocronApp)
```
```

--------------------------------

### Default Library Icon

Source: https://holocron.so/docs/components/icons

Renders an icon from the default library using its name.

```mdx
<Card title="Default library icon" icon="rocket">
  `rocket`
</Card>
```

--------------------------------

### CI Deployment with API Key

Source: https://holocron.so/docs/deploy/holocron

For continuous integration (CI) deployments, use a project API key stored in the `HOLOCRON_KEY` environment variable. This method bypasses interactive login and is suitable for automated workflows.

```bash
HOLOCRON_KEY=holo_xxx npx -y @holocron.so/cli deploy
```

--------------------------------

### Project Structure for Custom Entry

Source: https://holocron.so/docs/custom-entry

When mounting Holocron alongside your own app, always place MDX files within a subfolder like 'docs/'. This ensures all documentation resides under '/docs/*' and prevents conflicts with your application's routes.

```treeview
my-project/
├── docs/               ← all MDX pages live here
│   ├── getting-started.mdx
│   └── configuration.mdx
├── docs.json
├── server.tsx
├── vite.config.ts
└── package.json
```

--------------------------------

### Exact Path Redirect

Source: https://holocron.so/docs/create/redirects

Use this for a direct mapping of a specific old URL to a new one.

```json
{ "source": "/changelog", "destination": "/updates" }
```

--------------------------------

### Create a Holocron API Key via CLI

Source: https://holocron.so/docs/api-docs/authentication

Generate a new API key for a specific project. You can either specify the project ID or let the CLI prompt you to pick from a list.

```bash
npx -y @holocron.so/cli keys create --name production --project <projectId>
```

--------------------------------

### Fetch llms.txt Index

Source: https://holocron.so/docs/ai/llms-txt

This command fetches the agent-readable index file (llms.txt) from a documentation site. This is the primary discovery endpoint for AI agents.

```bash
curl https://your-docs-site.com/llms.txt
```

--------------------------------

### Set Icon Library

Source: https://holocron.so/docs/customize/icons

Configure the default icon library for your project. Supported libraries include 'fontawesome', 'lucide', and 'tabler'.

```json
{
  "icons": { "library": "lucide" }
}
```

--------------------------------

### Basic Changelog Tab Configuration

Source: https://holocron.so/docs/changelog-tab

Configure a changelog tab in your docs.json navigation by providing the GitHub repository URL. The generated page will be served at /changelog.

```json
{
  "navigation": {
    "tabs": [
      {
        "tab": "Documentation",
        "groups": [{ "group": "Getting Started", "pages": ["index"] }]
      },
      {
        "tab": "Changelog",
        "changelog": "https://github.com/owner/repo"
      }
    ]
  }
}
```

--------------------------------

### Link-Only Dropdown Configuration

Source: https://holocron.so/docs/organize/dropdowns

Create a dropdown entry that acts as a direct link to a URL instead of switching sidebar content. This is useful for linking to external resources like changelogs.

```json
{
  "dropdown": "Changelog",
  "href": "https://example.com/changelog"
}
```

--------------------------------

### Configure Banner in docs.json

Source: https://holocron.so/docs/components/banner

Add this JSON object to your docs.json file to enable and configure the site-wide banner. It includes the banner content and an option for dismissibility.

```json
{
  "banner": {
    "content": "Holocron is under active development. Browse the [component examples](/docs/components).",
    "dismissible": true
  }
}
```
Tokens:
Raw