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
- Install dependencies using
npm install(ornpm cifrom the lockfile in CI). - Set
GIT_TOKENin the process environment or deployment secret store when private HTTPS repositories require it. SetGIT_USERNAMEonly when the Git host requires a different token username. Never commit credentials or put them in public build variables. - Run
npm run syncto synchronize docs and regeneratesrc/generated/manifest.json. - Run
npm run devto sync automatically, then start Astro’s development server on0.0.0.0:3000. - Run
npm run buildto sync, build Astro, and run Pagefind.npm run previewpreviews an existing Astro build on0.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 /<product-slug>/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.jsoncontrols portal title, subtitle, canonical domain, brand identity, default accent,portalType("users","developer", or"all"), and navigation.config/projects.jsonaccepts 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-reposecretKeyreferences..vibtools/docs.config.json(alias.vibtools/config.docs.json) lets any repository declare its owndocsType, dualtargets.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 for the complete docs.config.json / config.docs.json schema, Adding Projects for CLI and webhook steps, Go-Live Deployment for dual-portal hosting, and project/ for architecture contracts.