Holydocs

HolyDocs Documentation Skill

Overview

HolyDocs is an AI-native documentation platform built on Cloudflare. Users write docs in MDX, configure with docs.json, and deploy via Git push or CLI. Sites are edge-rendered with sub-50ms page loads and include built-in AI search, an AI assistant, and an MCP server for IDE integration.

HolyDocs supports 11 visual themes, 38 MDX components, OpenAPI/AsyncAPI integration, versioning, i18n, auth-gated pages, and analytics integrations out of the box.

Creating a New Project

Follow these steps when a user wants to create a docs site:

Step 1: Check for Existing Docs

Look for any of these in the project root or common locations:

• docs.json or holydocs.json (HolyDocs config)
• mint.json (Mintlify config, can be migrated)
• docs/ directory
• .holydocs/ directory

If mint.json exists, offer to migrate: holydocs migrate mint.

Step 2: Create Directory Structure

docs/
  docs.json
  introduction.mdx
  quickstart.mdx
  guides/
    getting-started.mdx
  api/
    overview.mdx
  images/
    logo-light.svg
    logo-dark.svg

Step 3: Generate docs.json

Ask the user for:

1. Project name
2. Primary brand color (hex)
3. Logo (path or URL, light/dark variants if available)
4. Theme preference (show the 11 options)
5. Whether they have an OpenAPI spec

Then generate the config. Minimal working example:

{
  "name": "My Project",
  "theme": "mint",
  "colors": {
    "primary": "#0D9373"
  },
  "logo": {
    "light": "/images/logo-light.svg",
    "dark": "/images/logo-dark.svg"
  },
  "favicon": "/images/favicon.svg",
  "navigation": {
    "tabs": [
      {
        "tab": "Documentation",
        "groups": [
          {
            "group": "Getting Started",
            "pages": ["introduction", "quickstart"]
          },
          {
            "group": "Guides",
            "pages": ["guides/getting-started"]
          }
        ]
      },
      {
        "tab": "API Reference",
        "groups": [
          {
            "group": "API",
            "pages": ["api/overview"]
          }
        ]
      }
    ]
  },
  "topbarCtaButton": {
    "name": "Dashboard",
    "url": "https://example.com/dashboard"
  },
  "footerSocials": {
    "github": "https://github.com/example",
    "twitter": "https://twitter.com/example"
  }
}

Step 4: Create Starter Pages

introduction.mdx:

---
title: Introduction
description: Welcome to the project documentation.
icon: book-open
---

# Welcome to [Project Name]

A brief overview of what the project does and why it exists.

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Get up and running in under 5 minutes.
  </Card>
  <Card title="API Reference" icon="code" href="/api/overview">
    Explore the full API documentation.
  </Card>
</CardGroup>

quickstart.mdx:

---
title: Quickstart
description: Get started in under 5 minutes.
icon: rocket
---

# Quickstart

<Steps>
  <Step title="Install">
    Install the package using your preferred package manager.
    ```bash
    npm install my-package
    ```
  </Step>
  <Step title="Configure">
    Add your configuration.
    ```ts
    import { createClient } from 'my-package';
    const client = createClient({ apiKey: 'your-key' });
    ```
  </Step>
  <Step title="Use">
    Make your first API call.
    ```ts
    const result = await client.hello();
    console.log(result);
    ```
  </Step>
</Steps>

Step 5: Guide Deployment

Tell the user:

1. Push to a Git repository connected to HolyDocs (auto-deploys on push)
2. Or use the CLI: npx @holydocs/cli deploy
3. Or deploy from the HolyDocs dashboard

docs.json Essentials

The docs.json file is the single source of configuration. Key fields:

For the complete docs.json schema, read references/docs-json-schema.md.

MDX Page Format

Every .mdx file starts with YAML frontmatter:

---
title: Page Title
description: A brief description for SEO and search.
icon: lucide-icon-name
sidebarTitle: Short Title
mode: wide
openapi: GET /api/endpoint
---

Your content here in MDX (Markdown + JSX components).

Frontmatter Fields

Navigation Patterns

Flat Groups (Simple)

For small docs with no tabs:

{
  "navigation": {
    "groups": [
      {
        "group": "Getting Started",
        "pages": ["introduction", "quickstart"]
      },
      {
        "group": "Guides",
        "pages": ["guides/auth", "guides/deploy"]
      }
    ]
  }
}

Tabbed Navigation (Larger Sites)

For docs with distinct sections:

{
  "navigation": {
    "tabs": [
      {
        "tab": "Documentation",
        "icon": "book",
        "groups": [
          {
            "group": "Getting Started",
            "pages": ["introduction", "quickstart"]
          }
        ]
      },
      {
        "tab": "API Reference",
        "icon": "code",
        "groups": [
          {
            "group": "Endpoints",
            "pages": ["api/users", "api/projects"]
          }
        ]
      }
    ]
  }
}

Nested Groups

Groups can contain sub-groups for deep hierarchies:

{
  "group": "Authentication",
  "pages": [
    "auth/overview",
    {
      "group": "Providers",
      "pages": ["auth/oauth", "auth/saml", "auth/api-keys"]
    }
  ]
}

OpenAPI Auto-Generation

Add an OpenAPI spec and pages are generated automatically:

{
  "tab": "API Reference",
  "groups": [
    {
      "group": "Users API",
      "openapi": "https://api.example.com/openapi.json"
    }
  ]
}

Key Components (Quick Reference)

HolyDocs ships 38 MDX components. The most commonly used:

For all 38 components with full props and examples, read references/components.md.

Theming Quick Reference

Set the theme and customize colors/fonts in docs.json:

{
  "theme": "holy",
  "colors": {
    "primary": "#0D9373",
    "light": "#07C983",
    "dark": "#0D9373",
    "background": {
      "light": "#FFFFFF",
      "dark": "#0F1117"
    }
  },
  "fonts": {
    "heading": {
      "family": "Fraunces",
      "weight": 700,
      "source": "google"
    },
    "body": {
      "family": "Inter",
      "weight": 400,
      "source": "google"
    }
  }
}

Available Themes

For full theme details, read references/themes.md.

Deployment

Git Push (Recommended)

Connect your repository in the HolyDocs dashboard. Every push to the configured branch triggers an automatic build and deploy.

CLI Deploy

npx @holydocs/cli login
npx @holydocs/cli deploy

Programmatic Domain Management

Use the authenticated CLI API helper for custom domains:

npx @holydocs/cli login
npx @holydocs/cli api put /domains/proj_abc123 --json '{"customDomain":"docs.example.com"}'
npx @holydocs/cli api post /domains/proj_abc123/verify

To remove a domain:

npx @holydocs/cli api delete /domains/proj_abc123

Dashboard Deploy

Click "Deploy" in the HolyDocs dashboard to trigger a manual build from the latest commit.

Preview Deployments

Every pull request gets a unique preview URL automatically. Preview URLs follow the pattern: preview-{pr-number}.{project}.holydocs.com.

API Documentation

OpenAPI Integration

Add your OpenAPI spec to auto-generate API reference pages:

{
  "api": {
    "openapi": "https://api.example.com/openapi.json",
    "playground": {
      "display": "interactive",
      "proxy": "https://api.example.com"
    }
  }
}

You can also use a local file path: "openapi": "./openapi.yaml"

Multiple specs are supported as an array:

{
  "api": {
    "openapi": [
      "./specs/users-api.yaml",
      "./specs/billing-api.yaml"
    ]
  }
}

AsyncAPI

For event-driven APIs, use AsyncAPI specs the same way:

{
  "api": {
    "asyncapi": "./asyncapi.yaml"
  }
}

AI Features

AI Assistant

Enable the embedded AI assistant widget that answers questions using your docs:

{
  "assistant": {
    "enabled": true,
    "name": "Docs AI",
    "greeting": "Hi! Ask me anything about our docs.",
    "suggestedQuestions": [
      "How do I get started?",
      "What authentication methods are supported?"
    ],
    "position": "bottom-right"
  }
}

AI Search

Automatic on all plans. Combines keyword and semantic search across all pages, including API endpoints.

MCP Server

Automatic for Starter plan and above. Provides a Model Context Protocol server so IDEs (Claude Code, Cursor, Windsurf) can query your docs programmatically. The MCP endpoint is:

https://{project}.holydocs.com/mcp

Reference Pointers

• For the complete docs.json schema, read references/docs-json-schema.md
• For all 38 MDX components with props, read references/components.md
• For all 11 themes, read references/themes.md
• For CLI commands, read references/cli.md