Dashboard Settings

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.

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.

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.

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:

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:

Verification Status Badges

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:

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:

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

Playground Settings

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

Authentication Config

Define how the playground handles authentication:

json
{  "api": {    "auth": {      "type": "bearer",      "name": "Authorization",      "inputPrefix": "Bearer "    }  }}

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

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):

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

Export Settings

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:

Danger Zone

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

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