> ## Documentation Index
> Fetch the complete documentation index at: https://docs.holydocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

Get your HolyDocs documentation site live in under 5 minutes.

## 30-Second Start

Three commands to go from nothing to a live docs site:

```bash
npm install -g @holydocs/cli   # 1. install
mkdir my-docs && cd my-docs && holydocs init   # 2. scaffold your docs
holydocs login && holydocs deploy              # 3. authenticate + ship
```

`holydocs login` uses a browser-based device flow by default. Your browser opens with a one-time code, you sign in once, and the CLI stores a write-scoped API key in `~/.holydocs/config.json`. In CI or headless environments, use `HOLYDOCS_API_KEY` or `holydocs login --api-key hd_...` instead.

After login, if you don't already have a project, the CLI offers to create one for you in 1–2 prompts and runs your first deployment as proof.

Headless environment (CI, SSH, container)? Pass `--no-browser` to print the code without opening a browser, or use `holydocs login --api-key hd_…` to skip the device flow entirely.

## Prerequisites

Before you begin, make sure you have:

- **Node.js 20+** installed
- A **GitHub** or **GitLab** account
- A **HolyDocs account** at [app.holydocs.com](https://app.holydocs.com)

## Choose Your Path

**CLI (Recommended)**

The CLI gives you the most control and is the recommended path for developers comfortable with the terminal. Follow the steps below to get started.
  **Dashboard**

Prefer a visual workflow? You can set everything up from the dashboard without installing anything locally:

    **Create a project**

Log in at [app.holydocs.com](https://app.holydocs.com) and click **New Project**. Choose a name, slug, and starter template.
      **Connect your repository**

In the project settings, click **Connect Repository**. Authorize GitHub or GitLab and select your repo and branch.
      **Edit in the browser**

Use the built-in editor to create and modify MDX pages directly in the dashboard. The visual editor supports all HolyDocs components.
      **Deploy**

Click **Deploy** from the project overview, or push changes to your connected repository to trigger an automatic build.

## CLI Setup

**Install the CLI**

Install the HolyDocs CLI globally using your preferred package manager:

    **npm**

```bash
        npm install -g @holydocs/cli
        ```
      **pnpm**

```bash
        pnpm add -g @holydocs/cli
        ```
      **npx**

```bash
        npx @holydocs/cli init
        ```
  **Initialize your project**

Run the init command in your repository root (or a `docs/` subdirectory):

    ```bash
    holydocs init
    ```

    This creates a `docs.json` configuration file and a few starter MDX pages. You will be prompted to choose a template:

    - **Blank** — empty project with a single introduction page
    - **API Docs** — preconfigured for OpenAPI reference documentation
    - **Product Docs** — guides, tutorials, and feature documentation
    - **Open Source** — README-style docs with contribution guides
  **Preview locally**

Start the local development server to preview your docs:

    ```bash
    holydocs dev
    ```

    Open [http://localhost:3333](http://localhost:3333) in your browser. Changes to MDX files and `docs.json` are reflected immediately with hot reload.
  **Connect your repository**

Go to [app.holydocs.com](https://app.holydocs.com) and create a new project. Connect your GitHub or GitLab repository through the dashboard:

    1. Click **New Project** in the dashboard
    2. Select your Git provider and authorize access
    3. Choose the repository and branch
    4. Set the docs directory path (default: `/`)
  **Deploy**

Push your changes to trigger an automatic deployment:

    ```bash
    git add .
    git commit -m "docs: initial HolyDocs setup"
    git push origin main
    ```

    Your docs site will be live at `your-project.holydocs.com` within seconds. You can also deploy manually from the CLI:

    ```bash
    holydocs deploy
    ```

## Project Structure

After initialization, your docs directory will look like this:

```
docs/
  docs.json          # Configuration file
  introduction.mdx   # Landing page
  quickstart.mdx     # Getting started guide
  images/            # Static assets (logos, screenshots)
    logo-light.svg
    logo-dark.svg
```

## Configuration Overview

The `docs.json` file controls your entire documentation site. Here is a minimal example:

```json
{
  "name": "My Docs",
  "colors": {
    "primary": "#007AFF"
  },
  "navigation": {
    "groups": [
      {
        "group": "Getting Started",
        "pages": ["introduction", "quickstart"]
      }
    ]
  }
}
```

Page slugs in the navigation correspond to file paths relative to your docs root. For example, `"guides/setup"` maps to `guides/setup.mdx`.

### Common Configuration Fields

Here is a more complete example showing the most commonly used fields:

```json
{
  "name": "My API Docs",
  "logo": {
    "light": "/images/logo-light.svg",
    "dark": "/images/logo-dark.svg"
  },
  "favicon": "/images/favicon.png",
  "theme": "holy",
  "colors": {
    "primary": "#FBBF24",
    "light": "#FCD34D",
    "dark": "#D97706",
    "background": {
      "light": "#FFFBF0",
      "dark": "#000000"
    }
  },
  "fonts": {
    "heading": { "family": "Fraunces", "weight": "600" },
    "body": { "family": "Sora", "weight": "400" }
  },
  "navigation": {
    "tabs": [
      {
        "tab": "Documentation",
        "groups": [
          {
            "group": "Getting Started",
            "pages": ["introduction", "quickstart", "installation"]
          },
          {
            "group": "Guides",
            "pages": ["guides/themes", "guides/components", "guides/deployment"]
          }
        ]
      },
      {
        "tab": "API Reference",
        "groups": [
          {
            "group": "Endpoints",
            "pages": ["api/users", "api/projects", "api/deployments"]
          }
        ]
      }
    ]
  },
  "search": {
    "placeholder": "Search our docs..."
  },
  "assistant": {
    "enabled": true,
    "name": "Docs Helper"
  },
  "seo": {
    "indexing": "navigable"
  },
  "integrations": {
    "ga4": { "measurementId": "G-XXXXXXXXXX" }
  }
}
```

| Field | Required | Description |
|---|---|---|
| `name` | Yes | Site name, used in the header and SEO |
| `logo` | No | Light and dark mode logo image paths |
| `favicon` | No | Favicon path or URL |
| `theme` | No | One of the 11 built-in themes (default: `mint`) |
| `colors` | No | Primary, light, dark, and background color overrides |
| `fonts` | No | Custom heading and body font families |
| `navigation` | Yes | Tabs, groups, and page slugs defining the sidebar |
| `search` | No | Search modal placeholder and hotkey |
| `assistant` | No | AI chat assistant configuration |
| `seo` | No | Meta tags, indexing mode, OG image settings |
| `integrations` | No | Third-party analytics and monitoring |

## Troubleshooting

**holydocs: command not found**

Make sure the CLI is installed globally. Run `npm install -g @holydocs/cli` and verify with `holydocs --version`. If using `npx`, you do not need a global install — use `npx @holydocs/cli` followed by the command.
  **Port 3333 is already in use**

The `holydocs dev` server defaults to port 3333. If another process is using it, specify a different port: `holydocs dev --port 3001`.
  **Pages not appearing in the sidebar**

Every page must be listed in the `navigation` section of `docs.json` to appear in the sidebar. Check that the slug matches the file path exactly (without the `.mdx` extension).
  **Git repository not connecting**

Verify that the HolyDocs GitHub App has access to the repository. Go to your GitHub settings > Applications > HolyDocs and ensure the repo is included in the app's permissions. For GitLab, check that the OAuth token has `read_repository` scope.
  **Build fails with 'Invalid docs.json'**

The `docs.json` file must be valid JSON and match the HolyDocs config schema. Common issues include trailing commas, invalid color values, or missing required fields like `name`, `colors.primary`, or `navigation`. Run `holydocs check` locally before pushing.
  **Images not loading in preview**

Image paths in MDX are relative to the docs root. If your images are in `docs/images/`, reference them as `/images/screenshot.png`. Absolute URLs (https://...) also work.
  **Hot reload not working**

The dev server watches `.mdx` files and `docs.json` for changes. If hot reload stops working, restart the server with `holydocs dev`. Ensure your editor is saving files to disk (some editors use swap files).

## What's Next?

**[MDX Basics](/mdx-basics)**

Learn the MDX syntax and frontmatter fields available in HolyDocs.
  **[Navigation Config](/navigation-config)**

Configure tabs, groups, anchors, and sidebar navigation.
  **[Custom Domains](/custom-domains)**

Set up a custom domain with automatic SSL.
  **[AI Features](/ai-assistant)**

Enable the AI assistant and semantic search on your docs.