Skip to content

AGENTS

This repository contains docs-kit, a generic documentation site generator CLI.

Development Expectations

  • Keep docs-kit generic.
  • Never add project-specific assumptions.
  • Prefer convention over configuration.
  • Build thin wrappers around mature tooling.
  • Favor composable modules over large classes.
  • Keep CLI output human-friendly.
  • Make errors clearly explain what failed and how to fix it.
  • Preserve backwards compatibility where practical.
  • Keep generated documentation sourced from canonical Markdown files.
  • Avoid duplicating documentation content into docs-kit-owned formats.

Architecture

docs-kit should orchestrate documentation tooling rather than replace it. MkDocs is responsible for rendering, theming, search, and development serving. docs-kit is responsible for configuration loading, Markdown discovery, workspace preparation, generated MkDocs configuration, and future publishing workflows.

Keep modules focused:

  • config.ts owns the public configuration shape and loading.
  • discover.ts owns source discovery.
  • normalize.ts owns generated workspace preparation.
  • build.ts owns static site generation.
  • publish.ts owns filesystem release publication, activation, rollback, and retention.
  • serve.ts owns local development serving.
  • cli.ts owns command parsing and user-facing command wiring.

CLI Behavior

CLI commands should be calm, direct, and useful. Successful commands should say what happened and where output was written. Failed commands should name the failed dependency or configuration issue and provide the next corrective step when practical.

Publishing Boundaries

Filesystem publishing should remain generic. docs-kit may create immutable release directories, validate generated static files, atomically update a current symlink, roll back to existing releases, and apply release retention under a configured deployment root.

One installation-wide deployment root may contain multiple project paths. A publish must clone the active release into a new complete snapshot, replace only the subtree selected by basePath, and preserve unrelated sibling paths. Publish and rollback must hold the deployment lock while mutating release state.

Do not add nginx configuration, nginx reloads, TLS automation, Certbot calls, DNS changes, sudo, ownership changes, project-specific deployment assumptions, or GitHub integration to the publishing path.