# Vib Docs Engine A static multi-product documentation engine with zero-touch .vibtools/ auto-discovery and AI-readable documentation endpoints. Version: 1.0.0 Documentation: https://docs.vib.tools/vib-docs-engine/ ## Pages - [Overview](https://docs.vib.tools/vib-docs-engine/) - [.vibtools/ Configuration](https://docs.vib.tools/vib-docs-engine/vibtools-config/) - [Adding Projects](https://docs.vib.tools/vib-docs-engine/adding-projects/) - [Deployment](https://docs.vib.tools/vib-docs-engine/deployment/) - [Portal User Guide](https://docs.vib.tools/vib-docs-engine/portal-user-guide/) ## Full documentation # Vib Docs Engine — Operator & AI Agent Guide `vib-docs-engine` builds static documentation portals for multiple products (`https://docs.vib.tools` for end-user product docs and `https://developer.vibtools.io` for open-source/developer docs). During a build, the engine inspects each product repository's `.vibtools/docs.config.json` (or `.vibtools/config.docs.json`) via 2-step Git sparse checkout, validates and normalizes Markdown/MDX documentation from the configured `docsPath`, generates the portal manifest and sidebar tree, builds Astro static HTML + raw `.md` + `llms.txt` routes, and indexes all articles with Pagefind. --- ## 1. AI Agent & Automated Repository Setup Quick-Start If you are an **AI coding agent** (or developer) asked to configure `.vibtools/` and `docs/` inside a product repository so it syncs with `https://docs.vib.tools` or `https://developer.vibtools.io`, read these machine-readable resources first: | Resource | Path | Format & Purpose | | :--- | :--- | :--- | | **JSON Schema (Canonical)** | `/schemas/vibtools-docs.schema.json` | Draft 2020-12 JSON Schema for `.vibtools/docs.config.json` & `.vibtools/config.docs.json` | | **`.vibtools/` & `docs/` Full Spec (HTML)** | `/vib-docs-engine/vibtools-config/` | Complete human & AI specification for `.vibtools/` and `docs/` authoring | | **`.vibtools/` & `docs/` Full Spec (Raw Markdown)** | `/vib-docs-engine/vibtools-config.md` | Raw YAML-free Markdown of the complete `.vibtools/` + `docs/` specification | | **Adding Projects Guide (Raw Markdown)** | `/vib-docs-engine/adding-projects.md` | Repository registration (`config/projects.json`) & webhook setup | | **Deployment Guide (Raw Markdown)** | `/vib-docs-engine/deployment.md` | Dual-portal Cloudflare Pages & Docker/Nginx deployment | | **Product AI Bundle (`vib-docs-engine`)** | `/vib-docs-engine/llms.txt` | Complete concatenated Markdown for all `vib-docs-engine` guides in one request | | **Portal AI Directory** | `/llms.txt` | High-level index of all products, pages, raw `.md` URLs, and schema link on this portal | | **Full Portal AI Corpus** | `/llms-full.txt` | Complete Markdown corpus of every product and page hosted on this portal | ### 3-Step Checklist for AI Agents Configuring a Product Repository When asked to set up `.vibtools/` and `docs/` in a target repository: 1. **Create `.vibtools/docs.config.json` in the repository root:** - Include `"$schema": "https://docs.vib.tools/schemas/vibtools-docs.schema.json"` and `"schemaVersion": 1`. - Choose `"docsType"`: - `"users"` -> publishes strictly to **`https://docs.vib.tools`** (`portalType: "users"`). - `"developer"` -> publishes strictly to **`https://developer.vibtools.io`** (`portalType: "developer"`). - `"both"` -> publishes to **both portals** (use `"targets": { "users": { ... }, "developer": { ... } }` when the repository splits end-user docs and developer docs into separate directories like `docs/users` and `docs/dev`). - Add optional brand icon at `.vibtools/logo.svg` or `.vibtools/logo.png` (under `2 MB`, static SVG only) and reference it via `"logoPath": ".vibtools/logo.svg"`. 2. **Prepare the `docs/` directory (or per-target `docsPath`):** - Every configured `docsPath` **must** contain a root `index.md` (or `README.md`, which the sync engine automatically normalizes to `index.md`). - Include clean YAML frontmatter (`title`, `description`, `version`, optional `order`, `draft`) at the top of `index.md`, or rely on Smart Markdown extraction (`# H1` title + first summary paragraph). - Never keep duplicate `index.md` and `README.md` with conflicting content in the same folder (`index.md` wins and `README.md` is discarded). - Any governance `MANIFEST.md` files inside `docs/` are automatically stripped during sync so they never become public documentation pages (spell it `MANIFEST.md`, never `MINIFEST.md`). 3. **Follow the 2-Organization Convention:** - **`https://github.com/vibtoolshq/`**: Public, free, and open-source project repositories. Add `.vibtools/docs.config.json` directly inside the code repository alongside `docs/`. Most repos here use `"docsType": "developer"` (or `"docsType": "both"` with `targets.users` and `targets.developer` when a project like `LicenX` serves both `docs.vib.tools` and `developer.vibtools.io`). - **`https://github.com/vibdocs/`**: Public **docs-only** mirror repositories for private/commercial projects. Create a dedicated public repository per product in `github.com/vibdocs` containing **only** `.vibtools/` and `docs/` (zero private application source code), typically targeting `https://docs.vib.tools` (`"docsType": "users"` or `"both"`). Read the full field-by-field contract and copy-paste templates in [`.vibtools/` Configuration](vibtools-config.md). --- ## 2. Prerequisites for the Implemented Engine - Node.js `>=22.23.4` (pinned to official `22.23.5` in `.node-version` and `.nvmrc`) and npm. - Git with sparse-checkout support (Git 2.25 or newer). - Network access to the configured source repositories; credentials (`GIT_TOKEN` / `secretKey`) only when private repositories require them. Public repositories under `https://github.com/vibtoolshq` and `https://github.com/vibdocs` require zero credentials. --- ## 3. Local Workflow 1. Install dependencies using `npm install` (or `npm ci` from `package-lock.json` in CI). 2. Set `GIT_TOKEN` in the process environment or deployment secret store only when private HTTPS repositories require it. Never commit credentials or put them in public build variables. 3. Run `npm run sync` to synchronize docs and regenerate `src/generated/manifest.json`. 4. Run `npm run dev` to sync automatically, then start Astro's development server on `0.0.0.0:3000`. 5. Run `npm run build` to sync, build Astro, and run Pagefind. Run `npm run verify` to execute the full post-build verifier (`scripts/verify-build.mjs`). `npm run preview` previews an existing Astro build on `0.0.0.0:3000`. The `predev` and `prebuild` lifecycle hooks run the sync script automatically. When syncing the engine's own `vib-docs-engine` record without remote Git credentials, `scripts/sync-docs.mjs` falls back to the in-repository `docs/` directory. `localPath` can also temporarily target a local folder (for example `./docs`) for an isolated sync test; keep it out of production config. Generated content and manifests are ignored build inputs and must not be hand-edited. Press `Ctrl+K` (or `Cmd+K` on macOS) anywhere to open search. On a product page, search starts scoped to that product; switch to “All Docs” for portal-wide results. Hub searches are global. Static AI indexes are available at `/llms.txt`, `/llms-full.txt`, `//llms.txt`, and per-page `//.md`. The `.vibtools/` JSON Schema is served at `/schemas/vibtools-docs.schema.json`. `robots.txt` allows crawlers and points to `/sitemap-index.xml`. Unknown paths use the compact static 404 page. --- ## 4. Configuration Overview - `config/site.config.json` controls portal title, subtitle, canonical domain, brand identity, default accent, `portalType` (`"users"`, `"developer"`, or `"all"`), and navigation. - `config/projects.json` accepts bare Git repository URLs (`"https://github.com/vibtoolshq/..."` or `"https://github.com/vibdocs/..."`) for repos that include `.vibtools/docs.config.json` (or `.vibtools/config.docs.json`), or override objects with explicit fields and private-repo `secretKey` references. - `.vibtools/docs.config.json` (alias `.vibtools/config.docs.json`) lets any repository declare its own `$schema`, `schemaVersion`, `docsType`, dual `targets.users` / `targets.developer`, `docsPath`, `logoPath`, `slug`, `category`, `title`, `description`, `version`, `accentColor`, `branch`, and CTA metadata in one place. - Categories are derived dynamically from resolved products. Adding a category does not require code changes. Synchronized files under `src/content/docs/`, generated data under `src/generated/`, and synchronized logos under `public/logos/` are build artifacts and are ignored by Git except for `.gitkeep` files. Do not edit generated files by hand. --- ## 5. Deployment Configure the host to build from the portal's own deployment repository. A documentation source repository webhook should trigger the host's protected build hook; the build fetches `.vibtools/` and only the matching documentation directories with 2-step Git sparse checkout, then publishes a complete static output. For Cloudflare Pages, set the build command to `npm run build`, the output directory to `dist`, and use a protected Pages build hook. For a self-hosted VPS, build the Docker image and have Nginx serve only the resulting static files. See [`.vibtools/` Configuration](vibtools-config.md) for the complete `.vibtools/` and `docs/` specification, [Adding Projects](adding-projects.md) for CLI and webhook steps, [Go-Live Deployment](deployment.md) for dual-portal hosting, and [Portal User Guide](portal-user-guide.md) for reader navigation. # `.vibtools/` & `docs/` Repository Specification (Developer & AI Agent Reference) This document is the canonical specification for setting up `.vibtools/` and `docs/` inside any product repository so **Vib Docs Engine** can automatically sync, validate, categorize, and publish its documentation to **`https://docs.vib.tools`** (User Documentation Portal) and/or **`https://developer.vibtools.io`** (Developer Documentation Portal). > **For AI Coding Agents:** Everything required to configure a new or existing repository is specified on this page. You can also fetch the raw Markdown at `/vib-docs-engine/vibtools-config.md`, the full engine bundle at `/vib-docs-engine/llms.txt`, or the machine-readable JSON Schema at `/schemas/vibtools-docs.schema.json`. --- ## 1. Two-Organization Architecture (`vibtoolshq` vs `vibdocs`) Vib Tools separates public open-source code repositories from private commercial product documentation across two GitHub organizations: | GitHub Organization | Repository Type | What Lives in the Repo | Typical `docsType` / Target Portal | | :--- | :--- | :--- | :--- | | **`https://github.com/vibtoolshq`** | Public / Free / Open-Source projects (`LicenX`, `SocketCore`, `KronOTP`, `VPS-MCP`, `UpdatePilot`, `ReadBox`, etc.) | Full open-source project source code + `.vibtools/` + `docs/` | `"developer"` (`developer.vibtools.io`), or `"both"` with `targets.users` + `targets.developer` if also published on `docs.vib.tools` | | **`https://github.com/vibdocs`** | Dedicated Public **Docs-Only** repositories for private/commercial projects | **Only** `.vibtools/` + `docs/` (and optional `README.md`). Zero private application source code. | `"users"` (`docs.vib.tools`), or `"both"` if the public docs-only repo includes both end-user and public API/SDK guides | Why this matters when configuring a repo: - Because both `https://github.com/vibtoolshq/*` and `https://github.com/vibdocs/*` repositories are **public**, `config/projects.json` in the documentation portal only needs the bare repository URL string (`"https://github.com/vibtoolshq/.git"` or `"https://github.com/vibdocs/.git"`). No `GIT_TOKEN` or `secretKey` is required for public repositories. - Even on full source repositories under `github.com/vibtoolshq`, `scripts/sync-docs.mjs` performs a **2-step Git sparse checkout** that downloads only `.vibtools/` first and then only the resolved `docsPath` + `logoPath`. Application source code is never checked out during documentation builds. --- ## 2. Directory Layout & File Naming Rules ### Standard Single-Audience Layout (`docs/`) Use this layout when the repository targets a single portal (`"docsType": "users"` or `"docsType": "developer"`) or shares the exact same `docs/` folder on both portals: ```text your-product-repo/ ├── .vibtools/ │ ├── docs.config.json # Canonical config file (or config.docs.json — NEVER both) │ └── logo.svg # Optional product logo (.svg, .png, .webp, .avif <= 2 MB) └── docs/ ├── index.md # REQUIRED root landing page (or README.md auto-promoted to index.md) ├── 01-getting-started.md # Ordered top-level guide (numeric prefix stripped from URL & label) ├── 02-configuration.md ├── guides/ # Subfolder becomes a collapsible sidebar group │ ├── index.md # Optional subfolder overview (its frontmatter title names the sidebar group) │ ├── installation.md │ └── troubleshooting.md └── assets/ # Optional images referenced via relative Markdown paths └── workflow.png ``` ### Dual-Audience Split Layout (`docs/users/` + `docs/dev/`) Use this layout when a single repository (for example `https://github.com/vibtoolshq/LicenX`) serves **end-user guides** to `https://docs.vib.tools` and **developer/API docs** to `https://developer.vibtools.io` from separate subdirectories: ```text your-product-repo/ ├── .vibtools/ │ ├── docs.config.json # Uses "docsType": "both" with "targets": { "users": {...}, "developer": {...} } │ └── logo.svg └── docs/ ├── users/ # Checked out ONLY by docs.vib.tools (portalType: "users") │ ├── index.md # REQUIRED root landing page for end-user docs │ └── 01-quickstart.md └── dev/ # Checked out ONLY by developer.vibtools.io (portalType: "developer") ├── index.md # REQUIRED root landing page for developer docs └── 01-architecture.md ``` ### Strict File Rules for `.vibtools/` 1. **Canonical filename:** `.vibtools/docs.config.json` 2. **Supported alias:** `.vibtools/config.docs.json` 3. **Conflict guard (Fatal Build Error):** Commit **either** `docs.config.json` **or** `config.docs.json` inside `.vibtools/`. If both files exist simultaneously, `scripts/sync-docs.mjs` and `scripts/verify-build.mjs` reject the repository with an explicit conflict error. 4. **JSON validity:** Must be strict, valid JSON (UTF-8, no trailing commas, no `//` comments). --- ## 3. Complete `.vibtools/docs.config.json` Field Reference Every field is validated by `parseVibtoolsRepoConfig` in `src/utils/vibtoolsConfig.ts` and matched against `/schemas/vibtools-docs.schema.json`: | Field | Type | Scope | Validation Constraint | Default / Fallback Behavior | | :--- | :--- | :--- | :--- | :--- | | `$schema` | `string` | Root only | Non-empty URI string | Optional. Set to `"https://docs.vib.tools/schemas/vibtools-docs.schema.json"` (or `"https://developer.vibtools.io/schemas/vibtools-docs.schema.json"`). | | `schemaVersion` | `1` (integer) | Root only | Must equal exact integer `1` | Optional (`1`). Any other value fails validation. | | `docsType` | `"users" \| "developer" \| "both"` | Root only | Exact enum string | Defaults to `"both"` (or inferred from `targets` keys if only one target key is defined). | | `slug` | `string` | Root & Target | `^[a-z0-9]+(?:-[a-z0-9]+)*$` (lowercase alphanumeric + single hyphens) | Derived automatically from the repository name in `repoUrl` (e.g., `LicenX.git` -> `"licenx"`). | | `title` | `string` | Root & Target | Non-empty trimmed string | Used for Hub card and topbar title when `index.md` frontmatter lacks `title`. | | `category` | `string` | Root & Target | Non-empty trimmed string | Hub category filter tab. Defaults to `"Developer Docs"` when `docsType === "developer"`, otherwise `"Documentation"`. | | `description` | `string` | Root & Target | Non-empty trimmed string | Used for Hub card summary and `` when `index.md` lacks `description`. | | `version` | `string \| number` | Root & Target | Non-empty string or finite number | Normalized to string. Displayed in Hub & Topbar version badge (leading `v`/`V` is normalized automatically so `"0.1.0"` and `"v0.1.0"` both render as `v0.1.0`). | | `accentColor` | `string` | Root & Target | `^#(?:[\da-fA-F]{3}\|[\da-fA-F]{4}\|[\da-fA-F]{6}\|[\da-fA-F]{8})$` | Product brand accent color (e.g., `"#7C3AED"`). Falls back to `site.defaultAccent` from `config/site.config.json`. | | `docsPath` | `string` | Root & Target | Relative POSIX directory path inside repo. Must **not** start with `/`, contain `\`, contain `..`, or equal `.` | Defaults to `"docs"`. Examples: `"docs"`, `"docs/users"`, `"docs/dev"`, `"packages/sdk/docs"`. | | `logoPath` | `string` | Root & Target | Relative POSIX file path inside repo. Must **not** start with `/`, contain `\`, contain `..`, or equal `.` | Optional (e.g. `".vibtools/logo.svg"` or `".vibtools/logo.png"`). Checked before automatic logo discovery. | | `branch` | `string` | Root & Target | Non-empty Git branch name. Must **not** contain whitespace, `\`, or `..` | Defaults to `"main"`. If a target overrides `branch`, `scripts/sync-docs.mjs` fetches and switches sparse checkout to that branch before checking out `docsPath`. | | `ctaLabel` | `string` | Root & Target | Non-empty trimmed string | Topbar external action button label (defaults to `"Open"` when `ctaUrl` is defined without `ctaLabel`). Ignored if `ctaUrl` is omitted. | | `ctaUrl` | `string` | Root & Target | Valid absolute `http://` or `https://` URL | Topbar external button destination (e.g., `"https://github.com/vibtoolshq/LicenX"` or `"https://vib.tools/licenx"`). | | `targets` | `object` | Root only | Object containing `"users"` and/or `"developer"` target override objects (`minProperties: 1`, `additionalProperties: false`) | Optional per-portal overrides. Any field set inside `targets.users` or `targets.developer` overrides the root field on that portal. | --- ## 4. Portal Routing & Metadata Precedence Rules ### How `portalType` Matches `docsType` and `targets` Each portal deployment sets `"portalType"` inside its `config/site.config.json`: 1. **`docs.vib.tools` (`"portalType": "users"`)**: - **Includes** repositories where: - `targets.users` is defined, OR - `docsType` is `"users"` or `"both"` (and `targets` does not restrict exclusively to `developer`). - **Skips** repositories where `docsType` is `"developer"` (and `targets.users` is not defined). Skipped repositories log a clean `Skipped ...` notice and do not fail the build. 2. **`developer.vibtools.io` (`"portalType": "developer"`)**: - **Includes** repositories where: - `targets.developer` is defined, OR - `docsType` is `"developer"` or `"both"` (and `targets` does not restrict exclusively to `users`). - **Skips** repositories where `docsType` is `"users"` (and `targets.developer` is not defined). 3. **Combined / Preview Portal (`"portalType": "all"`)**: - **Includes** all repositories. - If a repository defines both `targets.users` and `targets.developer`, an explicit `"docsType": "developer"` or `"docsType": "users"` on the entry in `config/projects.json` selects that target; otherwise `targets.users` is selected by default. ### Metadata Resolution Order (Highest to Lowest Priority) When resolving `slug`, `docsPath`, `logoPath`, `branch`, `category`, `accentColor`, `ctaLabel`, and `ctaUrl`: 1. **`config/projects.json` explicit override field** (if the portal registry entry is an object instead of a bare URL string) 2. **`.vibtools/` active target** (`targets.users` on user portal, `targets.developer` on developer portal) 3. **`.vibtools/` root fields** 4. **Engine defaults** (`branch: "main"`, `docsPath: "docs"`, `slug` from `repoUrl`, `category: "Documentation"` or `"Developer Docs"`) When resolving display `title`, `description`, and `version` for a product: 1. **Root `index.md` YAML frontmatter** (`title` if not `"Overview"`, `description`, `version`) 2. **Resolved `.vibtools/` / `config/projects.json` metadata** (`title`, `description`, `version`) 3. **Smart Markdown Extraction fallback** (`extractMarkdownMetadata` in `src/utils/vibtoolsConfig.ts`): - **Title:** First `# H1` heading in `index.md`, automatically stripping noisy suffixes like `— User Documentation`, `- Developer Docs`, or `| Documentation`. - **Description:** First clean prose paragraph (skipping badges, tables, blockquotes, HTML tags, and boilerplate headings), stripped of inline Markdown syntax and truncated cleanly at a word boundary around `160` characters. - **Version:** First `Version: X.Y.Z`, `Release: vX.Y.Z`, or standalone `vX.Y.Z` semantic version badge found in the opening lines. --- ## 5. `docs/` Authoring Rules & Markdown/MDX Contract Every AI agent and developer authoring files inside `docsPath` (`docs/`, `docs/users/`, `docs/dev/`) must follow these rules so `scripts/sync-docs.mjs`, `src/utils/sidebar.ts`, and Astro Content Collections compile without errors: ### 5.1 Mandatory Root `index.md` (or `README.md`) - Every configured `docsPath` **must** have a root `index.md`, `index.mdx`, `README.md`, or `README.mdx`. - If a directory contains `README.md` and no `index.md`, `scripts/sync-docs.mjs` automatically renames `README.md` -> `index.md`. - If a directory contains **both** `index.md` and `README.md`, `index.md` is kept and `README.md` is deleted to prevent duplicate route collisions. - In the left sidebar, the root `index.md` is always rendered first with the label **`Overview`**, while the page's `` and `<h1>` use the frontmatter `title` (or `.vibtools` product title). ### 5.2 Supported Frontmatter Fields (`.md` / `.mdx`) All frontmatter fields are optional in `src/content.config.ts`, except `draft` must be a boolean if present: ```yaml --- title: "Configuration Guide" description: "Configure environment variables, webhooks, and runtime options." version: "1.2.0" order: 2 category: "Core Engine" draft: false --- ``` | Frontmatter Key | Type | Effect | | :--- | :--- | :--- | | `title` | `string` | Page `<h1>`, HTML `<title>`, OpenGraph title, and sidebar link label (root `index.md` keeps `"Overview"` as its sidebar link label). | | `description` | `string` | Meta description, OpenGraph description, and `/llms.txt` page summary. | | `version` | `string` | Product version read from the root `index.md` (e.g. `"1.2.0"`). | | `order` | `number` | Explicit sidebar sort priority within its folder (lower numbers appear first; pages with `order` sort before pages without `order`). | | `category` | `string` | Optional metadata tag. | | `draft` | `boolean` | When `draft: true`, `scripts/sync-docs.mjs` completely removes the file during sync so it is never published, routed, or indexed. **Must be an unquoted YAML boolean (`true` or `false`), never a string `"true"`.** | ### 5.3 File & Folder Ordering, URL Slugs, and Subfolder Groups - **Numeric filename prefixes:** You can prefix filenames or folders with `NN-` or `NN_` (e.g., `01-quickstart.md`, `02-api-reference.md`). - `src/utils/sidebar.ts` uses the numeric prefix for sorting (`01` before `02`), and **strips** the prefix from both the generated URL route (`/product/quickstart/`) and the humanized sidebar title (`Quickstart`). - **Subfolders (`docs/guides/...`):** - Every subfolder containing Markdown files becomes a collapsible sidebar section. - To customize a subfolder's sidebar group title, add an `index.md` inside that subfolder with a frontmatter `title` (for example `title: "Advanced Guides"`). Otherwise, the folder name is humanized (`02-api-guides` -> `Api Guides`). - **Route collision guard:** Two files in the same folder that normalize to the same slug (for example `01-setup.md` and `02-setup.md`) will fail the build with a duplicate route collision error. Keep normalized slugs unique per directory. ### 5.4 Governance Files (`MANIFEST.md`) Inside `docs/` - `scripts/sync-docs.mjs` automatically strips any file named `MANIFEST.md` (case-insensitive) from synced documentation trees so repository inventory files never pollute public documentation sidebars. - **Warning:** Always spell manifest files exactly `MANIFEST.md`. A misspelled filename like `MINIFEST.md` will **not** be stripped and will be published as a public documentation page. ### 5.5 Internal Links & Relative Images - **Internal Markdown links:** You may link between pages using either relative Markdown filenames (`[Adding Projects](adding-projects.md)` or `[Setup](./01-setup.md#install)`) or root-relative routes (`[Adding Projects](/vib-docs-engine/adding-projects/)`). The `rewriteInternalMarkdownLinks` Remark plugin in `astro.config.mjs` automatically rewrites relative `.md`/`.mdx` links into clean normalized Astro routes while preserving `#hash` anchors and `?query` parameters. - **Images & relative assets:** Place diagrams or screenshots inside `docs/assets/` (or any subfolder of `docsPath`) and reference them with relative Markdown image syntax (`![Architecture](./assets/diagram.png)`). `scripts/verify-build.mjs` verifies every internal `href` and `img[src]` in `dist/` and fails the build if any link or image is broken. ### 5.6 Built-In MDX Components (`.mdx` files only) When a file uses the `.mdx` extension, you can import the engine's built-in interactive components: ```mdx import Callout from "../../../components/mdx/Callout.astro"; import CodeTabs from "../../../components/mdx/CodeTabs.astro"; <Callout type="tip" title="Zero-Config Sync"> Bare repository URLs in `config/projects.json` automatically read `.vibtools/docs.config.json`. </Callout> <CodeTabs labels={["npm", "pnpm"]}> ```sh npm run sync ``` ```sh pnpm run sync ``` </CodeTabs> ``` - `Callout`: `type` supports `"info"` (default), `"tip"`, `"warning"`, or `"danger"`, plus optional `title`. - `CodeTabs`: `labels` accepts an array of tab names matching the child code blocks. --- ## 6. Logo Discovery & Security Validation Rules When `scripts/sync-docs.mjs` resolves a product logo, it checks candidate paths in this exact order: 1. Explicit `logoPath` (from `config/projects.json` override -> `.vibtools/` active target -> `.vibtools/` root) 2. `.vibtools/logo.svg`, `.vibtools/logo.png`, `.vibtools/logo.webp`, `.vibtools/logo.avif`, `.vibtools/icon.svg`, `.vibtools/icon.png` 3. `<docsPath>/logo.*`, `<docsPath>/icon.*`, `<docsPath>/assets/logo.*`, `<docsPath>/images/logo.*` Every logo candidate must pass these security checks: - Must resolve inside the repository root (`assertWithin`) with zero symlinks (`fs.lstat`). - Maximum file size: **`2 MB`** (`2,097,152` bytes). - `.png` files must start with the valid 8-byte PNG signature (`89 50 4E 47 0D 0A 1A 0A`). - `.svg` files must be static XML/SVG and are rejected if they contain `<script>`, `<foreignObject>`, inline `on*=` event handlers, `javascript:`/`data:text/html` URIs, or external `http://`/`https://` references. - If no logo exists (or if a candidate fails validation), the engine logs a warning and renders a deterministic 2-letter product monogram badge using `accentColor`. --- ## 7. Production Copy-Paste Templates ### Template A — Public Docs-Only Repo in `github.com/vibdocs` (`docs.vib.tools`) Use this in `https://github.com/vibdocs/<product>` for private/commercial apps whose user documentation is published on `https://docs.vib.tools`: ```json { "$schema": "https://docs.vib.tools/schemas/vibtools-docs.schema.json", "schemaVersion": 1, "docsType": "users", "slug": "calgrid", "title": "CalGrid", "category": "Desktop Apps", "description": "Batch Google Calendar scheduling and deliverability workflows.", "version": "1.0.2", "accentColor": "#2563EB", "docsPath": "docs", "logoPath": ".vibtools/logo.png", "branch": "main", "ctaLabel": "Get CalGrid", "ctaUrl": "https://vib.tools/calgrid" } ``` ### Template B — Open-Source Repo in `github.com/vibtoolshq` (`developer.vibtools.io`) Use this in `https://github.com/vibtoolshq/<repo>` for open-source tools, SDKs, or servers published on `https://developer.vibtools.io`: ```json { "$schema": "https://developer.vibtools.io/schemas/vibtools-docs.schema.json", "schemaVersion": 1, "docsType": "developer", "slug": "socketcore", "title": "SocketCore", "category": "Core Infrastructure", "description": "High-throughput WebSocket and event transport core for Vib Tools services.", "version": "1.0.0", "accentColor": "#0EA5E9", "docsPath": "docs", "logoPath": ".vibtools/logo.svg", "branch": "main", "ctaLabel": "GitHub", "ctaUrl": "https://github.com/vibtoolshq/SocketCore" } ``` ### Template C — Dual-Portal Open-Source Repo in `github.com/vibtoolshq` (Both Portals) Use this when a repository under `https://github.com/vibtoolshq/<repo>` (such as `LicenX`) maintains separate end-user docs (`docs/users`) for `https://docs.vib.tools` and developer docs (`docs/dev`) for `https://developer.vibtools.io`: ```json { "$schema": "https://docs.vib.tools/schemas/vibtools-docs.schema.json", "schemaVersion": 1, "docsType": "both", "slug": "licenx", "title": "LicenX", "version": "1.0.0", "logoPath": ".vibtools/logo.svg", "branch": "main", "targets": { "users": { "slug": "licenx", "title": "LicenX", "category": "License Management", "description": "End-user dashboard guide, license activation flows, and billing setup for LicenX.", "accentColor": "#7C3AED", "docsPath": "docs/users", "ctaLabel": "Open LicenX", "ctaUrl": "https://vib.tools/licenx" }, "developer": { "slug": "licenx", "title": "LicenX Developer Guide", "category": "SDKs & APIs", "description": "Self-hosted deployment, webhook verification, and SDK integration reference for LicenX.", "accentColor": "#0EA5E9", "docsPath": "docs/dev", "ctaLabel": "GitHub", "ctaUrl": "https://github.com/vibtoolshq/LicenX" } } } ``` ### Portal `config/projects.json` Registration Once `.vibtools/docs.config.json` is committed in the product repository, register the repo in the portal's `config/projects.json` using just its Git URL: ```json [ "https://github.com/vibtoolshq/LicenX.git", "https://github.com/vibtoolshq/SocketCore.git", "https://github.com/vibdocs/calgrid.git" ] ``` Or add it via CLI: ```sh npm run add-project -- --url https://github.com/vibtoolshq/LicenX.git ``` --- ## 8. Canonical JSON Schema (Draft 2020-12) This schema is hosted live at `/schemas/vibtools-docs.schema.json` on both `https://docs.vib.tools/schemas/vibtools-docs.schema.json` and `https://developer.vibtools.io/schemas/vibtools-docs.schema.json`: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://docs.vib.tools/schemas/vibtools-docs.schema.json", "title": "VibToolsDocsConfig", "description": "Repository-level .vibtools/docs.config.json (or .vibtools/config.docs.json) contract for Vib Docs Engine single-portal and dual-portal documentation sync.", "type": "object", "additionalProperties": false, "properties": { "$schema": { "type": "string", "minLength": 1, "description": "Optional JSON Schema reference URL (for example https://docs.vib.tools/schemas/vibtools-docs.schema.json)." }, "schemaVersion": { "const": 1, "description": "Schema format version marker. Must be 1 when provided." }, "docsType": { "type": "string", "enum": ["users", "developer", "both"], "default": "both", "description": "Target portal audience: 'users' (docs.vib.tools), 'developer' (developer.vibtools.io), or 'both'." }, "slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "description": "Lowercase URL-safe product route slug (e.g. 'licenx', 'socket-core'). Defaults to the normalized repository name." }, "title": { "type": "string", "minLength": 1, "description": "Display name of the product shown on Hub cards, breadcrumbs, and topbar." }, "category": { "type": "string", "minLength": 1, "description": "Hub category tab label (e.g. 'Core Engine', 'SDKs & CLI', 'Desktop Apps')." }, "description": { "type": "string", "minLength": 1, "description": "Concise product summary for Hub cards, SEO meta tags, and llms.txt indexes." }, "version": { "type": ["string", "number"], "description": "Product release or docs version badge (e.g. '1.2.0')." }, "accentColor": { "type": "string", "pattern": "^#(?:[\\da-fA-F]{3}|[\\da-fA-F]{4}|[\\da-fA-F]{6}|[\\da-fA-F]{8})$", "description": "CSS hex accent color (#RGB, #RGBA, #RRGGBB, or #RRGGBBAA)." }, "docsPath": { "type": "string", "minLength": 1, "pattern": "^(?!/)(?!\\.$)(?!.*\\\\)(?!.*(?:^|/)\\.\\.(?:/|$)).+$", "default": "docs", "description": "Relative POSIX directory path to Markdown/MDX documentation inside the repository (e.g. 'docs', 'docs/users', 'docs/dev')." }, "logoPath": { "type": "string", "minLength": 1, "pattern": "^(?!/)(?!\\.$)(?!.*\\\\)(?!.*(?:^|/)\\.\\.(?:/|$)).+$", "description": "Relative POSIX file path to the product logo (.svg, .png, .webp, .avif under 2 MB, e.g. '.vibtools/logo.svg')." }, "branch": { "type": "string", "minLength": 1, "pattern": "^(?!.*\\s)(?!.*\\\\)(?!.*\\.\\.).+$", "default": "main", "description": "Git branch to sparse-clone during documentation sync." }, "ctaLabel": { "type": "string", "minLength": 1, "description": "Topbar external CTA button label (defaults to 'Open' when ctaUrl is set)." }, "ctaUrl": { "type": "string", "format": "uri", "pattern": "^https?://", "description": "Absolute HTTP/HTTPS destination URL for the topbar CTA button." }, "targets": { "type": "object", "minProperties": 1, "additionalProperties": false, "description": "Optional per-portal overrides when a single repository serves both docs.vib.tools ('users') and developer.vibtools.io ('developer').", "properties": { "users": { "$ref": "#/$defs/target" }, "developer": { "$ref": "#/$defs/target" } } } }, "$defs": { "target": { "type": "object", "additionalProperties": false, "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "title": { "type": "string", "minLength": 1 }, "category": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "version": { "type": ["string", "number"] }, "accentColor": { "type": "string", "pattern": "^#(?:[\\da-fA-F]{3}|[\\da-fA-F]{4}|[\\da-fA-F]{6}|[\\da-fA-F]{8})$" }, "docsPath": { "type": "string", "minLength": 1, "pattern": "^(?!/)(?!\\.$)(?!.*\\\\)(?!.*(?:^|/)\\.\\.(?:/|$)).+$" }, "logoPath": { "type": "string", "minLength": 1, "pattern": "^(?!/)(?!\\.$)(?!.*\\\\)(?!.*(?:^|/)\\.\\.(?:/|$)).+$" }, "branch": { "type": "string", "minLength": 1, "pattern": "^(?!.*\\s)(?!.*\\\\)(?!.*\\.\\.).+$" }, "ctaLabel": { "type": "string", "minLength": 1 }, "ctaUrl": { "type": "string", "format": "uri", "pattern": "^https?://" } } } } } ``` --- ## 9. AI Agent Self-Verification Checklist (10 Points) Before finishing `.vibtools/` and `docs/` setup in any product repository, verify all 10 items: 1. **Single Config File:** Only `.vibtools/docs.config.json` exists (not both `docs.config.json` and `config.docs.json`). 2. **Valid JSON & Schema:** `.vibtools/docs.config.json` parses with `JSON.parse()`, includes `"$schema": "https://docs.vib.tools/schemas/vibtools-docs.schema.json"` and `"schemaVersion": 1`, and contains zero unknown keys. 3. **Correct `docsType` & `targets`:** `"docsType"` is `"users"`, `"developer"`, or `"both"`. If the repository splits `docs/users` and `docs/dev`, `"targets"` defines both `"users"` and `"developer"` with their respective `"docsPath"`. 4. **Valid `slug` & `accentColor`:** `"slug"` is lowercase kebab-case (`^[a-z0-9]+(?:-[a-z0-9]+)*$`) and `"accentColor"` is a valid CSS hex string (`#RRGGBB`). 5. **Safe Relative `docsPath` & `logoPath`:** Neither path starts with `/`, contains `\`, contains `..`, or equals `.`. 6. **Root `index.md` Exists:** Every configured `docsPath` directory contains a root `index.md` (or `README.md`) with clear title, description, and body content. 7. **Valid YAML Frontmatter:** Every `.md`/`.mdx` file with frontmatter has valid YAML delimiters (`---`), and any `draft` field is a boolean (`true`/`false`), not a string. 8. **No Stray Typo Manifests:** Any directory manifest inside `docs/` is named `MANIFEST.md` (which is auto-stripped), never misspelled as `MINIFEST.md`. 9. **Working Relative Links & Assets:** Every internal Markdown link (`[Guide](guide.md)`) and image (`![Img](./assets/img.png)`) points to an existing file inside `docsPath`. 10. **Logo Compliance:** If `logoPath` is set, the file exists at that exact path, is under `2 MB`, and (if `.svg`) contains zero `<script>`, `<foreignObject>`, event handlers, or external URLs. <!-- https://docs.vib.tools/vib-docs-engine/adding-projects/ --> # Adding Projects A product is added through configuration and a documentation repository. The intended workflow requires no application source changes. The recommended approach places a self-contained `.vibtools/docs.config.json` (or `.vibtools/config.docs.json`) inside the product repository so the portal only needs a single repository URL in `config/projects.json`. Legacy per-portal objects in `config/projects.json` remain fully supported as overrides or fallbacks. --- ## 0. Organization Strategy (`vibtoolshq` vs `vibdocs`) Before adding a project, confirm which GitHub organization hosts its documentation: - **`https://github.com/vibtoolshq/<repo>` (Open-Source & Free Projects):** - The repository contains the open-source code, `.vibtools/docs.config.json`, and `docs/` (or `docs/users/` + `docs/dev/`). - Most projects here target `https://developer.vibtools.io` (`"docsType": "developer"`), while dual-audience projects (such as `LicenX`) use `"docsType": "both"` with `targets.users` and `targets.developer` so both portals can pull from the same repo URL. - **`https://github.com/vibdocs/<repo>` (Docs-Only Repositories for Private Projects):** - When a product's application source code lives in a private repository, create a dedicated public **docs-only** repository at `https://github.com/vibdocs/<product>` containing only `.vibtools/` and `docs/`. - This keeps private source code completely isolated while allowing Cloudflare Pages or Docker builds to sync public documentation without private Git tokens. --- ## 1. Prepare the source repository (`.vibtools/` recommended) Add a `.vibtools/docs.config.json` file in the repository root alongside your documentation folder (`docs/`, `docs/users/`, or `docs/dev/`): ```json { "$schema": "https://docs.vib.tools/schemas/vibtools-docs.schema.json", "schemaVersion": 1, "docsType": "users", "slug": "product-name", "title": "Product Name", "category": "Desktop Apps", "description": "A concise description of this product.", "version": "1.2.0", "accentColor": "#22C55E", "docsPath": "docs", "logoPath": ".vibtools/logo.svg", "branch": "main", "ctaLabel": "Open Product", "ctaUrl": "https://vib.tools/product-name" } ``` See the full schema (`/schemas/vibtools-docs.schema.json`), `targets.users` / `targets.developer` dual-portal setup, `docs/` authoring rules, and logo rules in [`.vibtools/` Configuration](vibtools-config.md). ### Markdown `index.md` & Smart Metadata Fallback Every `docsPath` directory needs a root `index.md` (or `README.md`, which is automatically normalized to `index.md`). Explicit YAML frontmatter is recommended when you want exact control: ```md --- title: Product Name description: A concise description of this product. version: "1.2.0" --- ``` If `index.md` does not contain YAML frontmatter, `scripts/sync-docs.mjs` falls back through `.vibtools/` configuration, `config/projects.json` overrides, and **Smart Markdown extraction** (reading the first `# H1` heading, first clean summary paragraph, and `vX.Y.Z` / `Version: X.Y.Z` markers automatically). Optionally place your product logo at `.vibtools/logo.svg` (or `.png`), point `"logoPath"` at any validated relative file under `2 MB`, or place `logo.svg` / `logo.png` inside `docsPath`. Static SVGs are preferred (script/event/external-reference SVGs are rejected); when no logo is found, the UI generates a monogram. --- ## 2. Register the project in `config/projects.json` ### Zero-config `.vibtools/` URL entry (Recommended) When the source repository contains `.vibtools/docs.config.json` (or `.vibtools/config.docs.json`), add its credential-free Git URL string to `config/projects.json`: ```json [ "https://github.com/vibtoolshq/LicenX.git", "https://github.com/vibtoolshq/SocketCore.git", "https://github.com/vibdocs/calgrid.git" ] ``` Because `scripts/sync-docs.mjs` filters each repository's `.vibtools/` configuration against the active portal's `portalType` (`"users"` on `docs.vib.tools`, `"developer"` on `developer.vibtools.io`), you can even share a common list of repository URLs across both portals and each portal will automatically build only its matching targets. ### Quick CLI registration Add a repository URL in one command: ```sh npm run add-project -- --url https://github.com/vibtoolshq/LicenX.git ``` Pass optional override flags (`--slug`, `--category`, `--branch`, `--accent`, `--docs-path`, `--docs-type`, `--secret-key`, `--git-username`, `--cta-label`, `--cta-url`) only when a portal needs to override `.vibtools/` or provide private-repo auth. Running `npm run add-project` interactively also offers **[1] `.vibtools/` Auto** and **[2] Manual / Custom overrides**. Duplicate repository URLs are blocked unless a distinct `--slug` override is supplied. ### Manual override / legacy object format If a repository does not include `.vibtools/` yet (or if a specific portal needs to override values in `.vibtools/`), store an object in `config/projects.json`: ```json { "slug": "product-name", "category": "Developer Tools", "accentColor": "#22C55E", "repoUrl": "https://github.com/vibtoolshq/product-name.git", "secretKey": "$GIT_TOKEN", "branch": "main", "docsPath": "docs", "docsType": "developer", "ctaLabel": "View repository", "ctaUrl": "https://github.com/vibtoolshq/product-name", "title": "Product Name", "description": "Optional fallback if index.md and .vibtools lack a description.", "version": "1.2.0" } ``` Use a unique, URL-safe slug. Category filters are derived dynamically from resolved project records. Repository URLs may use HTTPS or SSH Git transports for GitHub, GitLab, Gitea, or Forgejo, and must never contain embedded credentials. --- ## 3. Configure public vs. private repository access - **Public repositories (`https://github.com/vibtoolshq/*` and `https://github.com/vibdocs/*`):** require no `secretKey` or `GIT_TOKEN`. Leave `secretKey` omitted and `scripts/sync-docs.mjs` performs a 2-step sparse checkout directly without credentials. - **Private repositories:** set `secretKey` on the project in `config/projects.json` (an environment variable reference such as `"$GIT_TOKEN"` or `"GIT_TOKEN"`, plus optional `gitUsername` if your Git host requires a non-default username; GitLab defaults to `oauth2` and GitHub/Gitea/Forgejo default to `x-access-token`). `scripts/sync-docs.mjs` automatically strips `secretKey`, `gitToken`, `gitTokenEnv`, and `gitUsername` before writing `src/generated/manifest.json` and redacts them from error output. --- ## 4. Configure rebuild webhooks Configure the source host to trigger the portal's protected build hook on pushes to the configured branch when files under `.vibtools/` or the documentation path change. - **Cloudflare Pages:** create a Pages build hook for the appropriate deployment (or point the repository webhook at `/api/webhook`) and protect the hook URL / `WEBHOOK_SECRET` as secrets. - **Docker/Nginx VPS:** use CI or a small protected webhook receiver to validate the provider's signature and start the build pipeline. Build to a staging directory and switch the served output only after sync, Astro, Pagefind, and `npm run verify` succeed. --- ## 5. Verify sync and the portal Run `npm test`, `npm run sync`, then `npm run build` and `npm run verify` (`node scripts/verify-build.mjs`). Confirm `.vibtools/` validation passes, the product appears on the matching portal Hub (`portalType` vs `docsType`), metadata/logo are resolved cleanly, and Pagefind indexes the article body. On a product page, `Ctrl+K` searches that product by default; switch to “All Docs” for portal-wide results. Check `/llms.txt`, `/llms-full.txt`, `/<slug>/llms.txt`, `/<slug>/<page>.md`, `/schemas/vibtools-docs.schema.json`, `/robots.txt`, `/sitemap-index.xml`, and `/404`. Use `npm run preview` to inspect the built static portal locally. For VPS testing with private repositories, build with `docker buildx build --secret id=git_token,env=GIT_TOKEN -t vib-docs-engine .` and run `docker run --rm -p 8080:80 vib-docs-engine`. --- ## 6. Select a portal preset The engine includes paired starter configs with `"portalType"` configured: - `config/presets/user-portal/` (`portalType: "users"`) for `docs.vib.tools`. - `config/presets/dev-portal/` (`portalType: "developer"`) for `developer.vibtools.io`. Use `npm run export-portal -- --portal <user|dev> --out <dir>` or copy both `site.config.json` and `projects.json` from the same preset directory into `config/`. Replace starter `YOUR_ORG` URLs with real `https://github.com/vibdocs/*` or `https://github.com/vibtoolshq/*` repositories before deploying. --- ## 7. Automate rebuilds from product repositories For GitHub (`vibtoolshq` and `vibdocs` repositories), copy `templates/github-notify-docs.yml` into the product repository at `.github/workflows/notify-docs.yml` (which watches both `docs/**` and `.vibtools/**`) and set the `DOCS_DEPLOY_HOOK_URL` secret to the target portal's build hook. For GitLab, Gitea/Forgejo, or a VPS receiver, use `templates/webhook-trigger.sh` and store `DOCS_DEPLOY_HOOK_URL` in protected CI secrets. <!-- https://docs.vib.tools/vib-docs-engine/deployment/ --> # Go-Live Deployment Runbook This runbook exports the single engine into independent user and developer portal repositories, verifies the static build, and connects product repositories to protected deployment hooks. Each portal owns its own config, Git credentials, project registry, and webhook URL. ## 1. Split into two portals Run these commands from the engine repository root. The output directories must not already exist: ```sh npm run export-portal -- --portal user --out ../docs-vib-tools npm run export-portal -- --portal dev --out ../developer-vibtools-io ``` The exporter copies the engine source while excluding dependencies, build output, generated documentation, generated logos, development notes, `.aistudio`, `public/assets/aistudio`, `bun.lock`, and the presets directory (and omits engine `.vibtools/` when exporting `--portal user`). It installs the matching preset files as each export's active `config/site.config.json` (`"portalType": "users"` for `docs.vib.tools` and `"portalType": "developer"` for `developer.vibtools.io`) and `config/projects.json`, updates `wrangler.toml` (`name = "docs-vib-tools"` vs `name = "developer-vibtools-io"`) and `public/site.webmanifest` branding/theme color, and preserves the `.gitkeep` files in generated folders. Because `scripts/sync-docs.mjs` matches each portal's `portalType` against each repository's `.vibtools/docs.config.json` (or `config.docs.json`) `docsType` and `targets` block, a shared repository URL can live in one or both portal registries while checking out only the matching audience's `docsPath`. See [`.vibtools/` Configuration](vibtools-config.md). Before building in production (`CF_PAGES=1` or `STRICT_SYNC=1`), replace all `YOUR_ORG` repository URLs in the user and developer presets with real documentation repositories (or add new `.vibtools/` repositories with `npm run add-project -- --url <repoUrl>`). Production CI builds reject unreplaced `YOUR_ORG` starter placeholders automatically. Review each CTA, category, branch, and `docsPath`. Then initialize and push each exported directory to its own deployment repository: ```sh cd ../docs-vib-tools git init npm install npm run build ``` Repeat for `../developer-vibtools-io`. Never copy generated content or credentials from one portal to the other. ## 2. Deploy with Cloudflare Pages & Functions Create a separate Pages project for each exported Git repository. The repository includes `wrangler.toml`, `.node-version`, `.nvmrc`, `package-lock.json`, `public/_headers`, `public/_redirects`, `public/_routes.json`, and `functions/api/` out of the box: - Build command: `npm run build` (or `npm run cf:build`) - Build output directory: `dist` - Node.js version: pinned automatically to `22.23.5` via `.node-version` and `.nvmrc` (an official Node.js 22 release satisfying Astro 7's `>=22.23.4` requirement and `engines.node >=22.23.4` in `package.json`). - Private repository credentials: - Single shared org/account token: add `GIT_TOKEN` as a protected Pages environment secret. Add `GIT_USERNAME` only if that Git host needs a non-default username. - Multiple independent private repositories: create distinct Pages environment secrets (e.g., `GIT_TOKEN_APP1`, `GIT_TOKEN_APP2`) and reference them per project via `"secretKey": "$GIT_TOKEN_APP1"` in `config/projects.json`. - Static Edge & Functions routing: - `public/_headers`: configures immutable caching for `/_astro/*`, revalidation for `/pagefind/*`, `Content-Type` + cache headers for `/llms.txt`, `/llms-full.txt`, `/*/llms.txt`, `/*.md`, `/site.webmanifest`, and `/robots.txt`, plus security headers. Internal `public/MANIFEST.md`, `public/README.md`, and any `public/assets/aistudio/` workspace files are automatically pruned from `dist/` at build completion. - `public/_redirects`: holds relative-path redirect rules (Cloudflare Pages `_redirects` does not support custom-domain-to-domain redirects). - `public/_routes.json`: restricts Cloudflare Pages Functions invocation strictly to `/api/*` so all documentation pages serve directly from the static CDN edge. - Built-in Pages Functions (`functions/api/`): - `GET /api/health` & `HEAD /api/health`: returns JSON health and runtime readiness status (`200` on `GET`/`HEAD`, `405` on other methods). - `POST /api/webhook`: optional authenticated webhook relay. Set `CF_DEPLOY_HOOK_URL` (the portal's HTTPS Cloudflare Pages Deploy Hook URL) and `WEBHOOK_SECRET` in Pages environment variables. `POST /api/webhook` fails closed with HTTP `501` when `WEBHOOK_SECRET` is missing unless `ALLOW_UNAUTHENTICATED_WEBHOOK="true"` is explicitly configured for development. Supports GitHub (`X-Hub-Signature-256`), Gitea/Forgejo (`X-Gitea-Signature`, `X-Forgejo-Signature`) HMAC-SHA256 signatures, `X-Gitlab-Token`, `X-Webhook-Secret`, and `Authorization: Bearer <secret>`, ignores initial `ping` events with HTTP `200`, and parses both JSON and `application/x-www-form-urlencoded` payloads for `ALLOWED_BRANCHES` (e.g., `main,docs`). - Attach `docs.vib.tools` to the user portal and `developer.vibtools.io` to the developer portal. - For the legacy `docs.vibtools.io` hostname, add a Cloudflare Zone Redirect Rule in the dashboard: match `docs.vibtools.io/*`, redirect to `https://docs.vib.tools/$1`, status `301`. Create a separate protected Pages build hook for each portal. Product repository webhooks must call only the portal whose registry contains that product. ## 3. Deploy to a VPS with Docker or Coolify The repository's multi-stage `Dockerfile` installs `git` and `openssh-client` in `node:22-alpine` for sparse-checkout builds and copies only `dist/` into `nginx:alpine`. `nginx.conf` mirrors `public/_headers` with gzip, global security headers (`X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy`), immutable 1-year caching for `/_astro/*`, 1-hour `must-revalidate` caching for `/pagefind/*`, `text/markdown; charset=utf-8` / `text/plain; charset=utf-8` responses for `.md` and `llms.txt`, and the static 404 route. For private docs repositories, provide a BuildKit secret rather than committing a token or putting it in the final image: ```sh docker buildx build --secret id=git_token,env=GIT_TOKEN -t vib-docs-engine:latest . docker run --rm -p 8080:80 vib-docs-engine:latest ``` In Coolify, configure the Git repository, Dockerfile build, port `80`, portal domain, and `GIT_TOKEN` as a build secret/environment secret. Use separate services and secrets for the two portals. Configure a protected webhook or CI trigger to rebuild the right service. The webhook receiver must verify signatures, rate-limit requests, and publish only a successfully built image; Nginx serves static files and never fetches docs at request time. ## 4. Connect product repositories For a GitHub product repository, copy `templates/github-notify-docs.yml` to `.github/workflows/notify-docs.yml`. Add the repository Actions secret `DOCS_DEPLOY_HOOK_URL` with the protected build-hook URL for the correct portal. The workflow listens for pushes to `main` that modify `docs/**` or `.vibtools/**` and sends a POST request to the hook. For GitLab, Gitea/Forgejo, or a VPS receiver, use `templates/webhook-trigger.sh` as the curl request. Store `DOCS_DEPLOY_HOOK_URL` as a protected CI/webhook secret. Configure source-host signature verification and path/event filters where available; do not expose hook URLs in logs or source code. ## Final launch checks Before DNS cutover, run `npm test`, `npm run lint`, and `npm run verify` in each portal repository. Confirm the selected preset and real repository URLs, private-repo access, static routes, Pagefind index, sitemap, robots, global and per-product `llms.txt`, per-page `.md` exports, and 404 output. Test one product docs push and confirm only its intended portal rebuilds. Preview a local build with `npm run preview` before publishing changes. <!-- https://docs.vib.tools/vib-docs-engine/portal-user-guide/ --> # Portal User Guide This guide describes the behavior implemented by the current static portal. Product pages and available controls are generated from the portal's build-time manifest. ## Hub Open the portal root to browse product cards. Each card opens that product's documentation. Category filter tabs appear only when the configured catalog has more than one unique category; otherwise the filter bar is omitted. When shown, select a category to filter the cards or choose `All` to reset. Product cards display the configured/generated title, description, category, version when present, and either the synchronized logo or a monogram. ## Search Press `Ctrl+K` (or `Cmd+K` on macOS), or use the search button in the header. Search code and index are downloaded only when the modal first opens. On a product page, search starts with `Current Product Only`; choose `All Docs` to search across the portal. On the Hub, the search is global. Select a result to open its page. Close the modal with `Escape` or by clicking the backdrop. In development before a production index exists, the modal explains that search is generated by `npm run build`. ## Documentation pages The product header links back to the Hub, switches between configured products, opens search, follows the product CTA when configured, and toggles the light/dark theme. Use the left sidebar for nested pages; on narrow screens its menu button opens a drawer that closes with Escape, the close control, or a navigation link. The right `On This Page` list links to H2/H3 headings and follows the current section while scrolling. At the end of an article, `Edit this page on Git` opens the source editor and Previous/Next links follow the manifest page order. The 404 page links back to the Hub and can open search. Product names, categories, links, logos, and CTA destinations vary by portal configuration.