Commands
check, extract, build, and serve use ./diplodocus.yaml unless given --config PATH. Extraction writes .diplodocus/documentation.sqlite beside that configuration; extract --output PATH changes the snapshot destination. generate requires --input PATH. generate, build, and serve write to ./site unless given --output PATH. Relative command-line paths resolve from the working directory.
For example, extract once and generate from the completed snapshot:
diplodocus extract --output documentation.sqlite
diplodocus generate --input documentation.sqlite --output site
The snapshot includes structured documentation, provenance, and local assets. Generation validates its records and output before publication. A copied snapshot can be generated without the original source files or language runtimes. See portable snapshots for compatibility and refresh behavior.
Use extract --watch to prepare snapshots continuously for another frontend. It extracts once, then watches declared sources, configuration, and referenced assets, including sibling package checkouts. Saves are debounced, and extractions run one at a time. Each successful publication writes and flushes one JSON line to stdout:
Diagnostics go to stderr. An initial failure exits without emitting an event. Later failures retain the previous snapshot and keep watching for corrections. Consumers should use publication events rather than observing temporary database files. If a consumer needs several passes over a snapshot, copy it before processing so a subsequent publication cannot change its input between passes. Stopping the watcher waits for active example execution to clean up. The VitePress example connects these events to an existing frontend's development server.
serve listens on 127.0.0.1:8000 by default. Use --host and --port to change the address, and --live-reload to refresh open pages after a successful rebuild. A failed rebuild prints diagnostics and keeps serving the last successful site. Warnings permit a successful exit; errors cause a nonzero exit status. Output destinations cannot replace declared inputs. The diagnostics guide explains reported codes and failed builds.
Start with the small example or see its workspace configuration.
Usage: diplodocus <COMMAND>
diplodocus build
Build a static documentation site
Usage: diplodocus build [OPTIONS]
Options
--config <PATH>Path to the workspace configuration file
Default value:
./diplodocus.yaml--output <PATH>Directory in which to write the generated site
Default value:
./site
diplodocus check
Check documentation without writing a site
Usage: diplodocus check [OPTIONS]
Options
--config <PATH>Path to the workspace configuration file
Default value:
./diplodocus.yaml
diplodocus extract
Extract a portable SQLite documentation snapshot
Usage: diplodocus extract [OPTIONS]
Options
--config <PATH>Path to the workspace configuration file
Default value:
./diplodocus.yaml--output <PATH>Snapshot destination (defaults to .diplodocus/documentation.sqlite beside the configuration)
--watchRe-extract changed inputs and emit a JSON line after each published snapshot
diplodocus generate
Generate a site using only a completed snapshot
Usage: diplodocus generate [OPTIONS] --input <PATH>
Options
--allow-componentsEmit executable browser bundles retained in this trusted snapshot
--input <PATH>Completed SQLite documentation snapshot
--output <PATH>Directory in which to write the generated site
Default value:
./site--format <FORMAT>Output complete site pages or embeddable HTML and Markdown fragments
Default value:
sitePossible values:
site,fragments--url-map <PATH>Public document and asset URL map (requires --format fragments)
diplodocus serve
Build and serve a site, rebuilding when declared inputs change
Usage: diplodocus serve [OPTIONS]
Options
--config <PATH>Path to the workspace configuration file
Default value:
./diplodocus.yaml--output <PATH>Directory in which to write the generated site
Default value:
./site--host <ADDRESS>Address on which to serve the generated site
Default value:
127.0.0.1--port <PORT>Port on which to serve the generated site
Default value:
8000--live-reloadRefresh open browser pages after successful rebuilds