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:
bashnpm install -g @holydocs/cli # 1. installmkdir my-docs && cd my-docs && holydocs init # 2. scaffold your docsholydocs 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
Choose Your Path
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.
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 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:
bashnpm install -g @holydocs/cli
bashpnpm add -g @holydocs/cli
bashnpx @holydocs/cli init
Initialize your project
Run the init command in your repository root (or a docs/ subdirectory):
bashholydocs 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:
bashholydocs dev
Open 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 and create a new project. Connect your GitHub or GitLab repository through the dashboard:
- Click New Project in the dashboard
- Select your Git provider and authorize access
- Choose the repository and branch
- Set the docs directory path (default:
/)
Deploy
Push your changes to trigger an automatic deployment:
bashgit 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:
bashholydocs deploy
Project Structure
After initialization, your docs directory will look like this:
textdocs/ 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
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.
The holydocs dev server defaults to port 3333. If another process is using it, specify a different port: holydocs dev --port 3001.
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).
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.
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.
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.
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).