Run your first export

Manuscrio reads a completed Site Build from a read-only mount and writes PDFs to a separate output directory.

Before you begin

Build your documentation site using its normal production command, and mount the directory it produced — the generated HTML and assets, not the project source.

Framework	Build directory
Docusaurus	`build/`
Starlight	`dist/`
MkDocs (Material theme)	`site/`

The examples below use build/; substitute your own. Manuscrio detects which framework produced the build, so no argument names it. See supported frameworks.

Two ways to run it

Manuscrio renders inside a container image. There are two ways to drive that image, and they run the same engine, take the same commands and options, and produce the same PDFs.

	Needs	Use it for
The `manuscrio` command	Node 20.19 or later, plus Docker or Podman	Local work and evaluation. It supplies the mounts and flags for you, and you name your own directories.
The container directly	Docker or Podman	CI, and anywhere without Node. Nothing is inferred, and every path is written out.

Every option is the same either way; the command reference lists them once for both. The npm package name and the image reference are settled at release — use the ones supplied with your release wherever the examples write manuscrio.

With the `manuscrio` command

npx manuscrio inspect ./build
npx manuscrio export ./build

The paths are yours. The command mounts the Site Build read-only, creates and mounts the output directory, mounts any --logo or --license you name, and runs the image as you so the PDFs come back belonging to you.

With no --output-dir, PDFs are written to manuscrio-output beside the Site Build. Name your own when you want them somewhere else:

npx manuscrio export ./build --scope section --output-dir ./manuals

To install it once rather than fetching it per run:

npm install -g manuscrio
manuscrio export ./build

The command is a thin wrapper: it never renders anything itself, and an option it does not recognise is passed to the engine untouched. It reads MANUSCRIO_RUNTIME to choose between Docker and Podman, and MANUSCRIO_IMAGE to pin a different image — both in the command reference.

With the container directly

Create an output directory

mkdir -p manuscrio-output

Create it yourself rather than letting Docker create it, so that it belongs to you.

Inspect the build

docker run --rm --init \
  --user "$(id -u):$(id -g)" \
  -v "$PWD/build:/input:ro" \
  manuscrio inspect /input

inspect prints JSON describing the detected framework, editions, documentation sections where the framework has them, sidebar roots, planned manuals, and any discovery diagnostics. Keep the edition or manual IDs it reports if you want to export only part of the site. Every field is listed in the inspect report reference.

Export PDFs

docker run --rm --init --ipc=host \
  --user "$(id -u):$(id -g)" \
  -v "$PWD/build:/input:ro" \
  -v "$PWD/manuscrio-output:/output" \
  manuscrio export /input --output-dir /output

By default, Manuscrio exports every discovered edition as a distinct PDF and renders up to four manuals in parallel.

The export command adds --ipc=host, which inspect does not need: the export starts a browser, and discovery does not. Container invocation explains this and the other flags, including why --user matters once a licence is involved.

Which one these pages use

The rest of this documentation writes its commands as manuscrio …, meaning the npm command with your own directories:

manuscrio export ./build --scope section

Two pages spell out the full docker run instead, because that is their subject: container invocation, which explains every flag and mount, and Run in CI, where writing it out is the right thing to do rather than adding Node to a build image.

Translating between the two is only ever the paths. The command reference puts them side by side.

Review the result

Open the PDFs in manuscrio-output/ and check the cover, contents table, bookmarks, internal links, code, images, and tables. Serious clipped-content findings fail the export by default instead of silently producing an incomplete manual; when an export fails explains what those reports mean.

Next, learn how to choose editions and manual scopes.