> ## 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.

# Projects

Create and manage documentation projects in HolyDocs. Each project maps to a single docs site with its own domain, configuration, and deployment pipeline.

## Overview

A **project** in HolyDocs represents a single documentation site. Each project has:

- A unique **slug** used for the default subdomain (`your-slug.holydocs.com`)
- A connected **Git repository** (GitHub or GitLab) for content source
- A **docs.json** configuration file defining navigation, theme, and features
- Its own **deployment pipeline**, custom domain, and AI index

## Creating a Project

### From the Dashboard

1. Log in at [app.holydocs.com](https://app.holydocs.com)
2. Click **New Project** from the sidebar
3. Enter a project name and slug
4. Connect a Git repository (optional — you can add this later)
5. Choose a starter template or start blank
6. Click **Create Project**

### From the CLI

```bash
holydocs init --name "My API Docs" --slug my-api-docs
```

### Via the API

```bash
curl -X POST https://api.holydocs.com/api/v1/projects \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API Docs",
    "slug": "my-api-docs",
    "repoProvider": "github",
    "repoOwner": "your-org",
    "repoName": "docs",
    "repoBranch": "main",
    "repoPath": "/"
  }'
```

## Project Settings

Each project has configurable settings accessible from the dashboard under **Settings**:

| Setting | Description |
|---|---|
| **Name** | Display name shown in the dashboard |
| **Slug** | URL-safe identifier, used as the default subdomain |
| **Subdomain** | Custom subdomain (e.g., `docs.holydocs.com`) |
| **Custom Domain** | Your own domain (e.g., `docs.yourcompany.com`) |
| **Repository** | Connected GitHub/GitLab repo, branch, and path |
| **Config JSON** | The `docs.json` configuration (editable in the dashboard) |
| **Base Path** | Subfolder hosting path (e.g., `/docs`) for embedding within an existing site |
| **Favicon** | Custom favicon URL or upload |
| **Logo** | Light and dark mode logo images |
| **SEO** | Meta tags, OG image settings, and indexing configuration |
| **Auth** | Content authentication provider and protected paths |
| **Webhooks** | Outbound webhook URLs triggered on deployments and feedback |

### Settings Categories

The dashboard Settings page is organized into tabs for easier navigation:

**General**

Project name, slug, and description. These are used in the dashboard and as defaults for SEO metadata when not overridden.
  **Appearance**

Theme selection, primary color, background colors, fonts, and logo uploads. Changes here are reflected in your live docs site after the next deployment.
  **Domain**

Custom domain configuration with automatic SSL provisioning. Also includes subfolder/base path hosting settings.
  **Git**

Connected repository, branch, docs directory path, and deployment triggers. You can switch repositories or branches without losing previous deployment history.
  **Content**

Navigation structure, versioning, internationalization settings, and content authentication. These map directly to `docs.json` fields.
  **Advanced**

API keys, webhook configuration, danger zone (project deletion), and export options.

## Project Limits by Plan

Project limits vary by plan. The free tier allows 1 project with up to 50 pages. Upgrade to Pro for unlimited projects.

| Plan | Projects | Pages per Project | Custom Domains | Builds/Day |
|---|---|---|---|---|
| Free | 1 | 50 | 0 | 10 |
| Starter | 3 | 200 | 1 | 30 |
| Pro | Unlimited | 500 | 5 | 100 |
| Business | Unlimited | Unlimited | 20 | 500 |
| Enterprise | Unlimited | Unlimited | Unlimited | Unlimited |

## Organization Scope

Projects belong to an **organization**. When you create a HolyDocs account, a default organization is created for you. Team members can be invited from **Settings → Members** in the dashboard.

All API requests are scoped to your current organization. The organization ID is derived from your session token (or API key), with an optional `X-Organization-Id` header as a fallback.

## Deleting a Project

Deleting a project permanently removes:

- All deployments and built assets from edge object storage
- The AI vector index for the project
- All analytics data and feedback
- Custom domain configuration

Project deletion is irreversible. Your Git repository is never modified — only the HolyDocs project and its cached/built artifacts are removed.

To delete a project, go to **Settings > Danger Zone** in the dashboard, or use the API:

```bash
curl -X DELETE https://api.holydocs.com/api/v1/projects/PROJECT_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Project Lifecycle

A typical HolyDocs project follows this lifecycle from creation to ongoing maintenance:

**Create**

Create a project from the dashboard, CLI, or API. Choose a template or start blank. A unique slug is assigned for your default subdomain.
  **Configure**

Set up your `docs.json` with navigation, theme, colors, and features. Connect a Git repository for automated deployments. Optionally add a custom domain.
  **Deploy**

Push content to your connected repository. HolyDocs builds and deploys your docs to the edge automatically. Preview deployments are created for pull requests.
  **Monitor**

Use the analytics dashboard to track page views, search queries, and reader feedback. The AI agent can run automated checks for broken links and stale content.
  **Iterate**

Update content, add pages, enable new features (AI assistant, translations, versioning). Each push triggers a fresh deployment with incremental AI indexing.

## Transferring Projects

Projects can be transferred between organizations. This is useful when:

- A project was created under a personal account and needs to move to a team organization
- Your company restructures and documentation ownership changes
- An agency hands off documentation to a client

To transfer a project:

1. Go to **Settings > Advanced > Transfer Project**
2. Enter the destination organization ID
3. The destination organization admin must accept the transfer
4. All deployments, analytics, and configuration transfer with the project

Custom domain DNS records must be updated manually after a transfer if the destination organization uses different DNS settings. The transfer does not modify DNS.

## Archiving Projects

Instead of deleting a project permanently, you can archive it. Archived projects:

- Stop serving traffic (visitors see a "This documentation has been archived" page)
- Retain all deployment history and analytics data
- Do not count toward your plan's project limit
- Can be unarchived at any time to restore full functionality

To archive a project, go to **Settings > Danger Zone** and click **Archive Project**. To unarchive, find the project in the **Archived** section of your dashboard sidebar.