.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
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.jsonorconfig.docs.jsoninside.vibtools/. Keeping both files simultaneously causesscripts/sync-docs.mjsandscripts/verify-build.mjsto 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 (mainby default). OncedocsType/targetsmatch the portal’sportalType(users,developer, orall), if the resolved target defines a differentbranch,scripts/sync-docs.mjsfetches and switches to that branch before sparse-checking out only the resolveddocsPath(and customlogoPathparent folder, if outsidedocsPath). 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/hastargets.users,docsType: "users", ordocsType: "both"(or legacy repos without.vibtools/unlessdocsType: "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/hastargets.developer,docsType: "developer", ordocsType: "both". User-only repositories are skipped."all"(default combined engine config): Includes all entries; if a repository defines bothtargets.usersandtargets.developer, setting an override"docsType": "developer"or"docsType": "users"on that entry inconfig/projects.jsonselects that matching target cleanly (otherwisetargets.usersis preferred). If a repository defines only one key undertargets, that target is selected automatically.
Resolution priority
- Portal registry override: Fields explicitly set on an object inside
config/projects.jsonalways take highest precedence. .vibtools/active target:targets.usersortargets.developermatching the portal’sportalType..vibtools/root fields: Shared root properties indocs.config.json/config.docs.json.- Markdown frontmatter & Smart Markdown extraction: For
title,description, andversionat render time,scripts/sync-docs.mjsresolvesindex.mdYAML frontmatter ->.vibtools//projects.jsonmetadata -> Smart Markdown extraction (first# H1heading stripped of trailing— User Documentation/— Docssuffixes, first clean prose paragraph capped cleanly to~160chars, and semanticvX.Y.Z/Version: X.Y.Zdetection).
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:
- Explicit
logoPath(fromprojects.json->.vibtools/target ->.vibtools/root) .vibtools/logo.svg,.vibtools/logo.png,.vibtools/icon.svg,.vibtools/icon.png<docsPath>/logo.*,<docsPath>/icon.*,<docsPath>/assets/*,<docsPath>/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. .pngfiles must carry valid 8-byte PNG headers..svgfiles must reject<script>,<foreignObject>, inlineon*=attributes, and externalhref/xlink:href/srcURIs.- Invalid or missing custom logos log a warning and fall back cleanly to standard discovery or a UI monogram instead of breaking the docs build.
5. Copy-paste templates
Example A — Single portal (End-user app on docs.vib.tools)
{ "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", "ctaLabel": "Get CalGrid", "ctaUrl": "https://vib.tools/calgrid"}Example B — Developer tool / SDK (Developer portal on developer.vibtools.io)
{ "schemaVersion": 1, "docsType": "developer", "slug": "vib-docs-engine", "title": "Vib Docs Engine", "category": "Core Engine", "description": "A static multi-product documentation engine.", "version": "0.1.0", "accentColor": "#7C3AED", "docsPath": "docs", "logoPath": ".vibtools/logo.png", "branch": "main", "ctaLabel": "View repository", "ctaUrl": "https://github.com/JILLU-Games/vib-docs-engine"}Example C — Dual-portal repository (One repo serving both domains)
{ "schemaVersion": 1, "docsType": "both", "title": "Invio", "version": "2.4.0", "logoPath": ".vibtools/logo.svg", "targets": { "users": { "slug": "invio", "category": "Desktop Apps", "description": "Desktop guides and workspace setup for Invio.", "accentColor": "#7C3AED", "docsPath": "docs/users", "ctaLabel": "Download", "ctaUrl": "https://vib.tools/invio" }, "developer": { "slug": "invio-sdk", "title": "Invio SDK", "category": "SDKs & Engines", "description": "Plugin API, CLI hooks, and webhook integration reference.", "accentColor": "#0EA5E9", "docsPath": "docs/developer", "ctaLabel": "GitHub", "ctaUrl": "https://github.com/vibdocs/invio-docs" } }}Minimal config/projects.json registration
When the product repo includes .vibtools/docs.config.json (or .vibtools/config.docs.json), config/projects.json needs only the repository URL string:
[ "https://github.com/vibdocs/calgrid.git", "https://github.com/vibdocs/invio-docs.git", { "repoUrl": "https://github.com/my-org/private-sdk.git", "secretKey": "$GIT_TOKEN_PRIVATE_SDK" }]Or register via CLI in one command:
npm run add-project -- --url https://github.com/vibdocs/calgrid.git6. JSON Schema reference (Draft 2020-12)
Editors supporting $schema or local schema validation can reference the canonical contract enforced by parseVibtoolsRepoConfig in src/utils/vibtoolsConfig.ts:
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "VibToolsDocsConfig", "type": "object", "properties": { "schemaVersion": { "const": 1 }, "docsType": { "enum": ["users", "developer", "both"] }, "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 }, "logoPath": { "type": "string", "minLength": 1 }, "branch": { "type": "string", "minLength": 1 }, "ctaLabel": { "type": "string", "minLength": 1 }, "ctaUrl": { "type": "string", "format": "uri" }, "targets": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "users": { "$ref": "#/$defs/target" }, "developer": { "$ref": "#/$defs/target" } } } }, "$defs": { "target": { "type": "object", "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 }, "logoPath": { "type": "string", "minLength": 1 }, "branch": { "type": "string", "minLength": 1 }, "ctaLabel": { "type": "string", "minLength": 1 }, "ctaUrl": { "type": "string", "format": "uri" } } } }}