# Vib Docs Engine A static multi-product documentation engine. Version: 0.1.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 # Operating vib-docs-engine `vib-docs-engine` builds static documentation portals for multiple products. Configuration selects the portal identity and product repositories. During a build, the engine fetches only configured documentation directories with Git sparse checkout, validates and normalizes content, generates a manifest/sidebar tree, and then builds Astro static pages and a local Pagefind search index. The engine includes the Astro/Tailwind configuration, Content Collection schema, Git sync/manifest engine, Hub, three-column docs reader, Pagefind search, sitemap, robots, and AI-readable `llms.txt` endpoints. The production build prerenders the configured portal to static files; the browser does not call Git or documentation APIs. ## Prerequisites for the implemented engine - A Node.js release supported by the installed Astro version and npm. - Git with sparse-checkout support (Git 2.25 or newer). - Network access to the configured source repositories; credentials only when private repositories require them. ## Local workflow 1. Install dependencies using `npm install` (or `npm ci` from the lockfile in CI). 2. Set `GIT_TOKEN` in the process environment or deployment secret store when private HTTPS repositories require it. Set `GIT_USERNAME` only when the Git host requires a different token username. 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. `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. The Pagefind index is local and is generated during production builds; dev mode displays a note if no index exists yet. Static AI indexes are available at `/llms.txt` and `//llms.txt`. `robots.txt` allows crawlers and points to `/sitemap-index.xml`. Unknown paths use the compact static 404 page. ## 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://..."`) 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 `docsType`, dual `targets.users` / `targets.developer`, `docsPath`, `logoPath`, `slug`, `category`, `title`, `description`, `version`, `accentColor`, and CTA metadata in one place. - Categories are derived 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. ## 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. The receiver must verify webhook authenticity and avoid exposing a shell command publicly. Build into staging and replace live output only after all build steps succeed. For private repositories, pass `GIT_TOKEN` as a BuildKit secret rather than a committed file or Docker `ENV` value. Example: `docker buildx build --secret id=git_token,env=GIT_TOKEN -t vib-docs-engine .`. The final Nginx image contains only `dist/` and Nginx configuration. Run it with `docker run --rm -p 8080:80 vib-docs-engine` and visit `http://localhost:8080`. See [`.vibtools/` Configuration](vibtools-config.md) for the complete `docs.config.json` / `config.docs.json` schema, [Adding Projects](adding-projects.md) for CLI and webhook steps, [Go-Live Deployment](deployment.md) for dual-portal hosting, and `project/` for architecture contracts. # `.vibtools/` Repository Configuration Place a `.vibtools/` folder in the root of any product repository so **Vib Docs Engine** can discover its documentation path, portal audience, title, description, version, accent color, CTA links, and brand logo from a single repository URL in `config/projects.json`. --- ## 1. Directory layout & filenames ```text your-product-repo/ ├── .vibtools/ │ ├── docs.config.json # Canonical filename (or config.docs.json) │ └── logo.svg # Optional brand icon (.svg / .png) ├── docs/ │ ├── users/ # Optional audience-specific docs directory │ └── developer/ # Optional developer docs directory └── ... ``` - **Canonical config file:** `.vibtools/docs.config.json` - **Supported alias:** `.vibtools/config.docs.json` - **Conflict rule:** Commit **either** `docs.config.json` **or** `config.docs.json` inside `.vibtools/`. Keeping both files simultaneously causes `scripts/sync-docs.mjs` and `scripts/verify-build.mjs` to fail cleanly rather than guess which file is authoritative. - **Two-step Git sparse checkout:** During `npm run sync`, remote repositories first check out only `.vibtools/` on the registry entry's branch (`main` by default). Once `docsType` / `targets` match the portal's `portalType` (`users`, `developer`, or `all`), if the resolved target defines a different `branch`, `scripts/sync-docs.mjs` fetches and switches to that branch before sparse-checking out only the resolved `docsPath` (and custom `logoPath` parent folder, if outside `docsPath`). Application source code is never checked out. --- ## 2. Config file reference (`docs.config.json` / `config.docs.json`) Every field below is verified by `src/utils/vibtoolsConfig.ts` during sync and `npm run verify`: | Field | Type | Applies To | Default / Behavior | | :--- | :--- | :--- | :--- | | `schemaVersion` | `1` | Root | Optional format marker (`1`). Any other value fails validation. | | `docsType` | `"users" \| "developer" \| "both"` | Root | Optional audience filter (`"both"` when omitted). Matched against `config/site.config.json` `portalType` (`"users"`, `"developer"`, or `"all"`). | | `slug` | `string` | Root or Target | Lowercase URL-safe slug (`^[a-z0-9]+(?:-[a-z0-9]+)*$`). Defaults to normalized repository name from `repoUrl` when omitted. | | `title` | `string` | Root or Target | Product card and navigation title fallback when Markdown frontmatter does not specify `title`. | | `category` | `string` | Root or Target | Hub filter category label. Defaults to `"Developer Docs"` for `developer` targets or `"Documentation"` otherwise. | | `description` | `string` | Root or Target | Short summary for Hub card and SEO fallback when frontmatter lacks `description`. | | `version` | `string \| number` | Root or Target | Displayed release/version badge (stored as trimmed string, e.g. `"1.2.0"`). | | `accentColor` | `string` | Root or Target | 3, 4, 6, or 8 digit CSS hex color (e.g. `"#7C3AED"`). Falls back to `site.defaultAccent`. | | `docsPath` | `string` | Root or Target | Relative POSIX directory path inside the repository (no leading `/`, no `\`, no `..`, not `.`). Defaults to `"docs"`. | | `logoPath` | `string` | Root or Target | Relative POSIX file path inside the repository (e.g. `".vibtools/logo.svg"`). Checked first before standard logo auto-discovery. | | `branch` | `string` | Root or Target | Git branch to sparse-clone (`"main"` when omitted; spaces, `\`, and `..` rejected). | | `ctaLabel` | `string` | Root or Target | Button label shown in the top bar (defaults to `"Open"` when `ctaUrl` is set without `ctaLabel`). | | `ctaUrl` | `string` | Root or Target | External HTTP or HTTPS CTA link (`ctaLabel` is ignored unless `ctaUrl` is set). | | `targets` | `{ users?: Target; developer?: Target }` | Root | Optional per-portal overrides so one repository can serve `docs.vib.tools` and `developer.vibtools.io` with different `docsPath`, `slug`, `category`, `title`, `description`, `accentColor`, `logoPath`, `ctaUrl`, or `branch`. Must define at least one of `users` or `developer`. | --- ## 3. Portal filtering & metadata precedence ### Portal matching rules `config/site.config.json` defines `"portalType"`: - `"users"` (e.g., `docs.vib.tools`): Includes entries whose `.vibtools/` has `targets.users`, `docsType: "users"`, or `docsType: "both"` (or legacy repos without `.vibtools/` unless `docsType: "developer"`). Developer-only repositories in a shared list are cleanly skipped (`Skipped ...`), not treated as build errors. - `"developer"` (e.g., `developer.vibtools.io`): Includes entries whose `.vibtools/` has `targets.developer`, `docsType: "developer"`, or `docsType: "both"`. User-only repositories are skipped. - `"all"` (default combined engine config): Includes all entries; if a repository defines both `targets.users` and `targets.developer`, setting an override `"docsType": "developer"` or `"docsType": "users"` on that entry in `config/projects.json` selects that matching target cleanly (otherwise `targets.users` is preferred). If a repository defines only one key under `targets`, that target is selected automatically. ### Resolution priority 1. **Portal registry override:** Fields explicitly set on an object inside `config/projects.json` always take highest precedence. 2. **`.vibtools/` active target:** `targets.users` or `targets.developer` matching the portal's `portalType`. 3. **`.vibtools/` root fields:** Shared root properties in `docs.config.json` / `config.docs.json`. 4. **Markdown frontmatter & Smart Markdown extraction:** For `title`, `description`, and `version` at render time, `scripts/sync-docs.mjs` resolves `index.md` YAML frontmatter -> `.vibtools/` / `projects.json` metadata -> **Smart Markdown extraction** (first `# H1` heading stripped of trailing `— User Documentation` / `— Docs` suffixes, first clean prose paragraph capped cleanly to `~160` chars, and semantic `vX.Y.Z` / `Version: X.Y.Z` detection). This means standard Markdown docs without YAML frontmatter still populate clean titles, summaries, and version badges on the Hub automatically. --- ## 4. Logo discovery & security rules When `scripts/sync-docs.mjs` resolves a product logo, it checks paths in this order: 1. Explicit `logoPath` (from `projects.json` -> `.vibtools/` target -> `.vibtools/` root) 2. `.vibtools/logo.svg`, `.vibtools/logo.png`, `.vibtools/icon.svg`, `.vibtools/icon.png` 3. `/logo.*`, `/icon.*`, `/assets/*`, `/images/*` Security & validation checks enforced on every logo candidate: - Must resolve inside the repository root (`assertWithin`) with zero symlinks (`fs.lstat`). - Maximum file size is `2 MB`. - `.png` files must carry valid 8-byte PNG headers. - `.svg` files must reject `