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.

Before the first build

Set <GenerateDocumentationFile>true</GenerateDocumentationFile> or the project has no API pages.
Run dotnet build before dotnet livedocs, and again after code changes.
docs/index.md is the home page. init asks whether to use docs/README.md when no index exists.
init sets siteName from the single root solution name, falling back to the repo folder; edit it in .livedocs/config.json to choose another title.
Link pages by their source Markdown filenames. Set sourceUrlPattern and sourceBranch (or legacy GitHub repoUrl) to send links outside the docs root to repository files and folders; without a source URL, the build warns. Use backticks for a plain path.
Leading numbers in Markdown filenames are removed from generated page URLs.

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.

Links between documentation pages use their source Markdown paths, including the real filename capitalization and any leading number. Generated page URLs lowercase names and drop ordering numbers.

Repository setup

Command	Result	Assumes
`livedocs init`	Create starter configuration, history, docs, and ignore entries. Ask whether an existing `docs/README.md` should be the home page when no index exists.	A writable working directory. Never overwrites existing files.
`livedocs init --discover-projects`	Discover `.fsproj` files, record them in configuration, and print the XML documentation setting when it is disabled.	`.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; report each compiler error with its line and column.	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/`; report all broken local page links before failing. Warns for projects without XML documentation and an unedited starter home page, and reuses the prior output only while docs, configuration, project inputs, assemblies, and XML docs are unchanged.	Projects built. The tool includes the native Pagefind indexer.
`livedocs watch [projects...]`	Verify, rebuild, and serve the site after changes to docs, project inputs, assemblies, or XML docs.	Projects built; 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, missing XML documentation, and blog authoring warnings.
`--drafts`	With `build` or `watch`, include blog posts marked `draft: true`.
`--verbosity <level>`	Set output detail: `warnings` (default), `info`, or `debug`.
`--interactive <bool>`	Enable or disable animated, stage-aware progress (default: `true`); redirected output uses plain progress automatically.
`--banner <bool>`	Show or hide the LiveDocs banner (default: `true`).
`--timings`	With `test`, `capture`, `audit`, `build`, `build-history`, or `history-check`, write `.livedocs/timings.json` with phase and per-example durations and print a summary.
`--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. Build selects plain progress automatically when standard output is redirected. 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

Append deterministic to fsharp run or fsharp transcript to reuse a passing result across invocations. It asserts the example reads no clock, network, filesystem, environment, or process; FsLiveDocs does not verify the assertion, and a changed input invalidates the entry.

Shortcodes and references

Syntax	Result
`{{< snippet id="Name" >}}`	Transclude a marked F# source region.
`{{< example id="Name" >}}`	Transclude an XML documentation example.
`{{< posts tag="..." category="..." limit="..." layout="..." show="..." >}}`	List blog posts; see Publish a blog.
`{{< series-nav >}}`	List the parts of the current post's series.
`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.