Command reference

Run commands from the repository root. Project arguments are optional: FsLiveDocs uses explicit arguments first, the union of top-level projects and every docsSets[].projects entry in .livedocs/config.json second, and automatic discovery last.

Every command assumes it runs at the repository root with .livedocs/ present (init creates it). Every command that reads the API — audit, test, generate-tests, build, watch, capture, extract — additionally assumes the documented projects already compiled in this SDK; run dotnet build first. The per-command Assumes column lists what each one needs beyond that.

Repository setup

Command	Result	Assumes
livedocs init	Create starter configuration, history, docs, and ignore entries.	A writable working directory. Never overwrites existing files.
livedocs init --discover-projects	Discover .fsproj files and record them in configuration.	.fsproj files exist below the root; benchmarks, probes, and apps may need removing from the list afterward.
livedocs generate-ci [--provider github]	Generate a GitHub Actions workflow that verifies docs and publishes releases (provider steps spelled out).	GitHub repository, Pages set to "GitHub Actions", default branch main, release tags v<semver>. Won't overwrite an existing livedocs.yml. Other hosts: follow the recipe in Verify documentation in CI.

Authoring and verification

Command	Result	Assumes
livedocs audit [projects...]	Check modes, coverage, and compilation for every F# block.	Projects built. Does not execute examples.
livedocs test [projects...]	Audit, then compile every unit and run each run block and transcript.	Projects built. Executable examples have the same file, network, process, and clock access as the shell.
livedocs generate-tests [projects...]	Write tests/FsLiveDocs.SnapshotTests/ with one xUnit case per discovered example.	Projects built. Regenerate after adding, removing, or renaming an example or fence.
livedocs build [projects...]	Verify and render the current site to output/.	Projects built; Node.js on PATH (npx pagefind builds the search index).
livedocs watch [projects...]	Verify, rebuild, and serve the site after changes.	Projects built; Node.js on PATH; a free TCP port (default 0.0.0.0:5000); on Linux, enough inotify watches.

Releases and history

Command	Result	Assumes
livedocs capture [projects...] --version <v> --output <zip>	Verify and create an immutable capsule.	Projects built; complete example coverage (no uncovered blocks); --version given.
livedocs capture ... --dry-run	Validate capture and report expected sizes.	As capture; writes nothing.
livedocs inspect <zip>	Verify and describe a capsule.	The zip is a capsule produced by capture.
livedocs history-check [--capsule <zip> --version <v>]	Render + verify the committed history, optionally splicing a local candidate in.	Every capsule the index references is reachable. Writes nothing; no host access. --capsule and --version come together.
livedocs history-add --version <v> --url <https> --sha256-file <f>	Record a hosted capsule in the index.	HTTPS URL; the checksum (--sha256/--sha256-file, or history.urlPattern supplies --url); <v> at or above the compatibility floor and not already present.
livedocs history-add --version <v> --capsule <zip>	Record a local capsule (offline history builds).	The capsule file exists; checksum computed if not given.
livedocs history-sync <owner/repo> --output <index>	One-way: discover published capsules and merge them into the index.	GitHub: non-draft Releases with assets <repo>-<version>-livedocs.zip and a sha256: digest, api.github.com reachable, GH_TOKEN for private/rate-limited repos. Or --from "<command>" / history.discover printing version url sha256 lines. Only adds versions at or above the compatibility floor; never modifies releases.
livedocs build-history <index> --retry 3	Render every indexed release from its capsule alone.	Every capsule URL in the index is reachable; --retry bounds transient download failures. Never compiles the historical source.
livedocs verify-output <index> --output output	Verify entry points, switcher order, and generated local links.	build-history (or build) already wrote output/ for the same index.
livedocs extract [projects...]	Write legacy loose API and semantic artifacts.	Projects built. Superseded by capsules; use only for external tooling that reads the loose files.

Common options

Option	Use
--version <v>	Set the captured or rendered product version; the release version for history-add/history-check.
--output <path>	Set an artifact or index output path.
--url <https> / --sha256 <hex> / --sha256-file <path>	Identify a hosted capsule for history-add.
--from "<command>"	history-sync discovery command for non-GitHub hosts.
--provider <name>	generate-ci target host (default github).
--theme <name>	Select the initial site theme.
--warn-as-error	Fail on API documentation quality warnings.
--verbosity <level>	Set output detail: warnings (default), info, or debug.
--interactive <bool>	Enable or disable animated, stage-aware progress (default: true).
--banner <bool>	Show or hide the LiveDocs banner (default: true).
--host <address>	Set the preview bind address.
--port <number>	Set the preview port.
--ignore <names>	Add watcher directory names to ignore.

At the default warnings level, LiveDocs groups API issues by source file and issue kind, links to configured GitHub source, and prints a concise summary. info adds normal progress messages. debug expands every issue with its compiler message and remedy, and also lists every audited block and watcher directory. Use --interactive false for stable line-oriented logs. Verbosity, interactivity, and the banner are independent. In CI, pass --interactive false --banner false to every invocation — see Verify documentation in CI.

Fence modes

Mode	Compilation	Execution	Display
fsharp	Page unit	No	Yes
fsharp prepare	Page unit	No	Shared setup
fsharp isolated	Separate unit	No	Yes
fsharp run	Page unit	Yes	Yes
fsharp transcript	Transcript runner	Yes	Yes
fsharp no-check reason="..."	No	No	Syntax only

Shortcodes and references

Syntax	Result
{{< snippet id="Name" >}}	Transclude a marked F# source region.
{{< example id="Name" >}}	Transclude an XML documentation example.
xref:T:Namespace.Type	Link to a documented entity.
xref:M:Namespace.Module.member	Link to a documented member.

Documentation sets

Field	Default / meaning
id	Required stable lower-case slug.
title	Title-cased id.
source	docs; overlapping roots use the most-specific owner.
path	Site root for the default set; otherwise id.
projects	Projects used for verification and the set's exposed API surface.
default	Required on exactly one configured set.
sidebar / api	true; false omits that surface.
fSharpPrelude	Top-level fSharpPrelude, if present.