Inspect and export

Commands on this page are written as manuscrio …, the npm command with your own directories. Running the container directly takes the same options with paths inside it; the command reference lists them once for both.

Start every new Site Build with inspect. Its report is the contract between discovery and export: it shows what Manuscrio found and gives you the exact IDs accepted by the selection options below. Every field is described in the inspect report reference.

Why a Site Build becomes more than one PDF

Two different things decide how many PDFs you get, and it helps to keep them apart.

Editions are a correctness boundary. An edition is one plugin, locale, and version of the documentation. Manuscrio never merges two of them, whatever their size: English and German are not one manual, and neither are v2 and v3. You choose which editions to export, never whether to combine them.

Scope is the size decision, inside one edition. A large edition makes an unwieldy PDF, and --scope is how you cut it into deliverables that a reader can actually use. The pinned Docusaurus benchmark shows the same content at each scope:

Scope	PDFs	Pages
edition	1	537
section	2	371 and 180
sidebar-root	several	22 for Getting Started

Four reasons to narrow it, beyond the page count itself:

• Delivery. A single very large manual is slow to open, awkward to navigate, and heavy to attach or host. The benchmark’s largest one-manual export ran to 1,582 pages and 162 MB.
• Run time and memory. Each manual renders in a browser. Narrower scopes give the runner smaller, parallelisable units rather than one long render.
• Failure isolation. A single unreachable image fails the manual that contains it. At a narrower scope the other manuals still export — see when an export fails.
• Navigation depth. Edition scope spends one heading level on the section, so everything below it shifts down and the deepest headings fall past --max-chapter-level, losing their numbers and their contents entries. Section and sidebar-root scope give those levels back.

Nothing forces the choice. A small site is entirely reasonable as one PDF per edition, which is why that is the default.

Choose a manual scope

Scope	Result	Use it when
edition	One PDF for each selected documentation edition. This is the default.	The edition is small enough to read as one manual.
section	One PDF for each documentation-bearing navbar section.	The site’s navbar already names the deliverables a reader thinks in.
sidebar-root	One PDF for each top-level sidebar root.	You want the finest split, or an edition the broader scopes refuse.

manuscrio export ./build --scope section

An edition that has no navbar sections is still exported at edition scope, where its sidebar roots become the manual’s top-level chapters. Section scope refuses it, naming the scopes that work, because there is nothing to enumerate. Starlight and MkDocs have no section level at all, so --scope section is a Docusaurus-only option in practice.

Separately, an edition that does have sections but also has a sidebar belonging to none of them is refused at both edition and section scope, and exports at --scope sidebar-root. When an export fails explains why.

Select editions

All discovered editions are selected by default, but each remains a separate PDF boundary. An edition is one plugin, locale, and version of the documentation, so a Docusaurus site with three locales and two versions offers six of them. Starlight and MkDocs have no plugin or version concept, so those parts of the ID are constant and only locales multiply editions there.

Use repeatable --edition options as an allowlist:

manuscrio export ./build \
  --edition default:en:current \
  --edition default:de:current

Or exclude known, intentionally unsupported editions from the default set:

manuscrio export ./build \
  --exclude-edition docs-tests:en:current

Unknown IDs and conflicting filters fail instead of being ignored. --all-editions states the default selection explicitly, which is useful when a pipeline builds its arguments dynamically and you want the all-editions case to be visible rather than implied.

Select planned manuals

After inspect, repeat --manual <id> to render only specific planned manuals inside the selected editions and scope. Use the manualId values from the report, not the PDF file names.

Manual IDs and output file names

IDs and file names are derived differently, and only one of them is stable.

IDs are structural. An edition ID is plugin:locale:version. A section manual is <edition>/section/<section-id> and a sidebar-root manual is <edition>/root/<owner-id>/<root-id>.

For Docusaurus these follow the site’s own routes, with one exception: a sidebar root that is a label with no page of its own has no route to name it, so its ID is derived from its title, and retitling it changes the ID. For Starlight and MkDocs, sidebar roots are numbered by position (set-0-1, root-2), so inserting an entry above one changes its ID. Either way, a pinned --manual argument can stop matching after an edit to the navigation.

File names are the manual title, always. Getting Started becomes Getting Started.pdf, so the file name contains spaces and changes whenever an editor retitles the manual. When two manuals in one run share a title, both file names gain their ID as a suffix to keep them distinct.

Two consequences for a pipeline that publishes PDFs as artifacts:

• quote or glob-escape the output paths, because the names contain spaces; and
• treat the file names as human-facing labels rather than as a stable contract. Select by --manual <id>, and rename the result yourself if a downstream system needs a fixed name.

Without --output-dir, PDFs are written to a manuscrio-output directory beside the Site Build. Running the container directly, that option is not optional; container invocation explains why.

Rendering controls

• --concurrency <n> sets parallel renders. The default is 4; reduce it for memory-constrained runners.
• --max-chapter-level <n> controls the numbered contents and PDF-outline depth. Accepts 1 to 6; the default is 3. Headings deeper than this still appear in the manual, without a number and without a contents entry.
• --no-fail-on-clipped reports clipping without failing. Keep the default fail-closed behavior for release builds, and see when an export fails.
• --framework <name> overrides automatic framework detection when diagnosing an unusual build. Accepts docusaurus, starlight, or mkdocs; see supported frameworks.

Run manuscrio export --help for the options supported by your installed release.