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

# Dashboard Settings

Configure every aspect of your documentation project through the settings panel.

## Overview

The Settings page is your central control panel for project configuration. Access it from the **Settings** item in the sidebar under the Manage section. Settings are organized into ten tabs, each covering a different area of your project.

Navigate between tabs using the underlined tab bar at the top of the settings page:

**General** | **Appearance** | **Domain** | **Git** | **Content** | **SEO** | **API** | **Auth** | **Exports** | **Advanced**

Changes to settings are saved immediately when you click **Save** on each tab. Some changes (like appearance or navigation) trigger an automatic redeployment to take effect on your live site.

---

## General

Basic project identity and configuration.

| Field | Description |
|---|---|
| **Project name** | Display name shown in the dashboard, sidebar, and organization project list |
| **Slug** | URL-safe identifier used in your default subdomain (`slug.holydocs.com`). Can only be changed if no custom domain is configured. |
| **Subdomain** | Your default HolyDocs URL, derived from the slug. Read-only. |
| **Description** | Optional project description for internal reference. Not displayed on the doc site. |
| **Default language** | Primary language for the documentation site (used for HTML `lang` attribute and AI features). |
| **Timezone** | Used for scheduled changelog entries and analytics date grouping. |

Choose your slug carefully — it appears in the default URL and in API references. While you can change it later, existing links to the old subdomain will stop working.

---

## Appearance

Control the visual presentation of your rendered documentation site.

### Theme Picker

Select from 11 built-in themes. Each theme defines a complete visual system including colors, typography scale, spacing, border radii, and component styles.

**Available themes**

| Theme | Description |
|---|---|
| **Mint** | Clean greens, modern sans-serif, generous whitespace |
| **Maple** | Warm reds and oranges, classic feel |
| **Palm** | Tropical greens, relaxed and open |
| **Willow** | Soft sage tones, gentle and organic |
| **Linden** | Golden yellows, bright and welcoming |
| **Almond** | Neutral cream and brown, understated elegance |
| **Aspen** | Cool blues with crisp contrast |
| **Holy** | Sharp 2px radii, dark sidebar, bordered cards — the HolyDocs signature theme |
| **Atlas** | Deep navy and gold, authoritative and structured |
| **Nova** | Purple gradients, bold and contemporary |
| **Cipher** | Monochrome with green accents, developer-focused |

### Primary Color

Use the color picker to set the primary accent color used for links, buttons, active navigation items, and focus rings across your documentation site. Enter a hex value directly or use the visual picker.

### Logo

Upload separate logos for light and dark mode. Supported formats: SVG, PNG, JPEG. SVG is recommended for crisp rendering at all sizes. Logos appear in the top-left of the rendered site navigation.

| Setting | Description |
|---|---|
| **Light mode logo** | Displayed when the reader is using light mode |
| **Dark mode logo** | Displayed when the reader is using dark mode |
| **Logo height** | Maximum height in pixels (default: 28px) |
| **Logo link** | URL the logo links to (default: documentation homepage) |

### Favicon

Upload a favicon (ICO, PNG, or SVG). HolyDocs automatically generates the required sizes for browsers, mobile bookmarks, and PWA icons.

### Fonts

Override the default theme fonts:

| Slot | Purpose | Default |
|---|---|---|
| **Heading font** | Page titles, section headings, sidebar group labels | Varies by theme |
| **Body font** | Paragraph text, table cells, list items | Varies by theme |
| **Code font** | Inline code and code blocks | Geist Mono |

Select from the built-in font library or enter a Google Fonts URL for custom fonts.

### Light / Dark Mode

Use the **Light / Dark** segmented toggle to preview your appearance settings in each mode. Both modes are rendered in the live preview panel on the right side of the settings page.

Your doc site supports light and dark mode out of the box. Readers can toggle between modes using the sun/moon icon in the site header. Their preference is stored in `localStorage`.

---

## Domain

Configure how your documentation is accessed on the web.

### Default Subdomain

Every project gets a subdomain at `slug.holydocs.com`. This is always active and cannot be disabled.

### Custom Domain

Add a custom domain like `docs.yourcompany.com`:

**Enter your domain**

Type your custom domain in the input field and click **Add domain**.
  **Configure DNS**

HolyDocs displays the required DNS records. Add a CNAME record pointing your domain to `proxy.holydocs.com`.

    | Type | Name | Target |
    |---|---|---|
    | CNAME | docs | proxy.holydocs.com |
  **Verify**

Click **Verify DNS** or wait for automatic verification (checked every 60 seconds). The status badge shows **Pending**, **Verified**, or **Failed**.
  **SSL provisioning**

After DNS verification, an SSL certificate is automatically provisioned via Cloudflare. This takes 1-2 minutes. The status badge updates to **SSL Active** when complete.

### Verification Status Badges

| Badge | Meaning |
|---|---|
| **Pending** | DNS record not yet detected. Propagation can take up to 48 hours. |
| **Verified** | DNS is correctly configured. SSL provisioning in progress or complete. |
| **SSL Active** | Fully operational. Your domain serves over HTTPS. |
| **Failed** | DNS record is incorrect or conflicting. Check the error message for details. |

Removing a custom domain immediately stops serving your docs at that URL. Make sure to update any external links before removing a domain.

---

## Git

Manage the connection between your HolyDocs project and your source code repository.

### Connected Repository

Displays the currently connected GitHub or GitLab repository with:

- **Repository** — Organization/repo name with a link to the repository
- **Branch** — The branch HolyDocs watches for changes (default: `main`)
- **Path** — The directory within the repo containing your docs (default: `/`)
- **Webhook status** — Whether the webhook is active and receiving push events

### Changing the Branch

Select a different branch from the dropdown. HolyDocs triggers a redeployment from the new branch immediately.

### Changing the Path

Update the docs root directory if your MDX files are not at the repository root. Common values: `/docs`, `/documentation`, `/content`.

### Reconnecting

If the webhook stops firing or your OAuth token expires, click **Reconnect** to re-authorize the GitHub or GitLab integration. This generates a fresh installation token without affecting your project configuration.

### Switching Repositories

To connect a different repository, click **Change repository**. A repository picker shows all accessible repos from your connected GitHub/GitLab account. Switching repositories triggers a fresh build from the new source.

Switching repositories does not delete previous deployment history or analytics data. The new repository's content replaces the old content on the next successful deployment.

---

## Content

Direct control over your documentation structure and navigation.

### docs.json Editor

An inline JSON editor for your `docs.json` configuration file. Edit navigation groups, page order, tab structure, and all other configuration options with syntax highlighting and schema validation.

The editor validates your `docs.json` against the HolyDocs schema in real time. Errors are highlighted inline with descriptive messages. You cannot save invalid configuration.

### Navigation Config

A visual drag-and-drop interface for managing your navigation structure:

- **Tabs** — Top-level navigation tabs shown in the site header
- **Groups** — Collapsible groups within each tab
- **Pages** — Individual pages within each group

Drag items to reorder them. The changes are written back to `docs.json` when you save.

### Page Management

View all pages in your project with metadata:

| Column | Description |
|---|---|
| **Path** | File path relative to docs root |
| **Title** | Title from frontmatter |
| **Last modified** | Timestamp from the most recent commit touching this file |
| **Status** | Published, Draft, or Hidden |

---

## SEO

Optimize how your documentation appears in search engines and social media.

### Meta Tags

Set global meta tags applied to every page on your site:

```json
{
  "seo": {
    "metatags": {
      "og:site_name": "Acme Documentation",
      "twitter:site": "@acmecorp",
      "twitter:card": "summary_large_image"
    }
  }
}
```

### Open Graph Images

HolyDocs auto-generates OG images for every page using your project name, page title, and theme colors. Configure OG image settings:

| Setting | Description |
|---|---|
| **Style** | Choose from default, minimal, or branded templates |
| **Custom background** | Upload a background image for the OG card |
| **Logo on OG** | Toggle whether your logo appears on the generated image |

### Sitemap

HolyDocs automatically generates a `sitemap.xml` at your docs root. Configure sitemap behavior:

- **Indexing scope** — `navigable` (only pages in the navigation) or `all` (every MDX file)
- **Change frequency** — Default `weekly`, configurable per-page via frontmatter
- **Priority** — Auto-calculated based on navigation depth, overridable per-page

### JSON-LD Structured Data

Structured data is automatically added to every page for improved search engine understanding:

- `Article` schema with title, description, author, and date
- `BreadcrumbList` for navigation hierarchy
- `WebSite` schema on the homepage with search action
- `FAQPage` schema on pages containing AccordionGroup components

---

## API

Configure OpenAPI specification parsing and the interactive API playground.

### OpenAPI Spec

| Field | Description |
|---|---|
| **Spec URL** | URL to your OpenAPI 3.x JSON or YAML specification |
| **Spec file path** | Alternatively, path to a spec file within your repository |
| **Auto-generate pages** | Automatically create a page for each API endpoint |
| **Group by tag** | Organize generated pages into navigation groups by OpenAPI tag |

### Playground Settings

Configure the interactive API playground that appears on API reference pages:

| Setting | Description |
|---|---|
| **Enable playground** | Toggle the "Try it" panel on API pages |
| **Base URL** | The default server URL for playground requests |
| **Proxy mode** | Route playground requests through a CORS proxy for browser compatibility |

### Authentication Config

Define how the playground handles authentication:

**Bearer Token**

```json
    {
      "api": {
        "auth": {
          "type": "bearer",
          "name": "Authorization",
          "inputPrefix": "Bearer "
        }
      }
    }
    ```
  **API Key**

```json
    {
      "api": {
        "auth": {
          "type": "apiKey",
          "name": "X-API-Key",
          "in": "header"
        }
      }
    }
    ```
  **OAuth 2.0**

```json
    {
      "api": {
        "auth": {
          "type": "oauth2",
          "authorizationUrl": "https://auth.example.com/authorize",
          "tokenUrl": "https://auth.example.com/token",
          "scopes": ["read", "write"]
        }
      }
    }
    ```

---

## Auth

Protect your documentation behind authentication when you need to restrict access to specific audiences.

### Enable Authentication

Toggle site-wide authentication on or off. When enabled, readers must sign in before accessing any protected page.

### Doc Site Auth Method

Choose how readers authenticate to access your published docs site (separate from how you sign into the HolyDocs dashboard, which uses Better Auth):

| Method | Description |
|---|---|
| **None** | Public site — no reader authentication required (default). |
| **Password** | A single shared password gates the entire site. Useful for quick private docs without identity management. |
| **OAuth** | Standard OAuth 2.0 / OIDC flow against any provider that supports it (Google, GitHub, Auth0, Okta, Azure AD, your IdP, etc.). |
| **JWT** | Bring your own auth: paste a JWKS URL and HolyDocs verifies reader-issued JWTs against it. The most flexible option for custom IdPs and SSO. |

### Public Paths

Define paths that remain accessible without authentication. Useful for keeping your landing page and quickstart guide public while protecting advanced content.

```json
{
  "auth": {
    "publicPaths": [
      "/",
      "/quickstart",
      "/introduction",
      "/api/authentication"
    ]
  }
}
```

### RBAC Groups

Role-Based Access Control lets you restrict specific pages or sections to user groups:

```json
{
  "auth": {
    "groups": {
      "beta-testers": {
        "pages": ["/beta/*"],
        "description": "Access to beta feature documentation"
      },
      "enterprise": {
        "pages": ["/enterprise/*", "/sso", "/audit-logs"],
        "description": "Enterprise-only features"
      }
    }
  }
}
```

Users are assigned to groups through your auth provider's user metadata or through the HolyDocs dashboard.

Enabling authentication adds a sign-in step for your readers. Consider the trade-off between content protection and documentation discoverability. Public docs perform better for SEO and developer adoption.

---

## Exports

Export your documentation in multiple formats for offline use, compliance, or migration.

### Available Formats

**PDF**

A formatted PDF with table of contents, page numbers, and your branding. Ideal for compliance and offline reading.
  **Static HTML**

A self-contained HTML bundle with all styles and assets inlined. Can be hosted on any static file server.
  **Markdown Archive**

A ZIP file containing all MDX source files and assets. Useful for migration or backup.

### Export Settings

| Option | Description |
|---|---|
| **Include draft pages** | Whether to include pages marked as draft in the export |
| **Include API pages** | Whether to include auto-generated OpenAPI pages |
| **Page size** | PDF page size — A4, Letter, or Legal |
| **Cover page** | Include a branded cover page in PDF exports |

### Triggering an Export

Click **Export** on the desired format card. Exports are processed asynchronously — you receive an email with a download link when the export is ready. Large projects (500+ pages) may take a few minutes.

---

## Advanced

Danger zone and low-level project configuration.

### Environment Variables

Define key-value pairs that are available during the build process. Use these for conditional content or dynamic configuration:

```json
{
  "env": {
    "API_VERSION": "v2",
    "SHOW_BETA_FEATURES": "true"
  }
}
```

Access environment variables in your MDX files using the `{process.env.VARIABLE_NAME}` syntax.

### Feature Flags

Toggle experimental or in-development features for your documentation site:

| Flag | Description |
|---|---|
| **AI Assistant** | Enable the AI chat assistant on your doc site |
| **AI Search** | Enable semantic AI-powered search |
| **Feedback widget** | Show the "Was this helpful?" widget on pages |
| **Version picker** | Display the version selector in the site header |
| **Changelog page** | Include the changelog as a page on your doc site |
| **Roadmap page** | Include the roadmap as a page on your doc site |

### Danger Zone

Actions in the Danger Zone are destructive and cannot be undone. Proceed with care.

| Action | Description |
|---|---|
| **Transfer project** | Move this project to a different organization or personal account |
| **Archive project** | Remove the project from the active list. Docs stop serving but data is retained for 30 days. |
| **Delete project** | Permanently delete the project, all deployments, analytics data, and configuration. This action is irreversible. |

Deleting a project requires typing the project name as confirmation and entering your password or re-authenticating.