---
title: "commentware-documents"
description: "The template library's commands, and the options each takes. Experimental."
---

> Documentation Index
> Fetch the complete documentation index at: https://commentware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# commentware-documents

`commentware-documents` builds a project's template index, serves its
templates for preview, and installs the Chrome PDFs are printed with. It is
installed with the library, so a project runs it with
`npx commentware-documents`. The library is experimental, so a command or an
option may change or be removed in any release, with no notice first, and the
help and a starting preview both say so.

Each command reads [documents.config.ts](/docs/documents/config/) from the
directory it runs in, or from `--root`. A command with no config file is refused
with the names it looked for. `commentware-documents --help`, or `-h`, prints
the commands and options and exits `0`. A command exits `0` when it succeeds and
`1` when it is refused; with no command, or one it does not know, it prints the
same help and exits `1`.

## `build`

**Usage:** `commentware-documents build [--root <dir>]`

Writes two files into the config's `outDir`:

- `templates.ts`, which maps every template's id to an `import()` of its file
  and exports the compiled stylesheet as `stylesheet`;
- `templates.entry.css`, the stylesheet Tailwind compiles: the config's
  `stylesheet`, or Tailwind alone, and one `@source` line per template
  directory.

It compiles no template; the project's own bundler does that when it imports
`templates.ts`. It prints what it wrote:

```text
Wrote .documents/templates.ts: 1 template, 4 KB of CSS.
```

Two templates with one id are refused, and nothing is written.

## `preview`

**Usage:** `commentware-documents preview [--root <dir>] [--port <port>]`

Serves the project's templates at `127.0.0.1`, on port `7043` unless `--port`
names another, until Ctrl-C:

```text
Previewing 1 template at http://127.0.0.1:7043/
Experimental: the template library and these commands may change or go in
any release, with no notice first.
```

The page lists the templates. For the one selected, it shows an editor for its
params, checked against its schema; the page its PDF prints, as it looks on
screen; a table of each sheet, for a template that builds a spreadsheet; and a
download for each output. A change to a template, to a file it imports or to
the stylesheet redraws the page. The page fetches nothing from any address but
its own, so it works with no network. It renders with the same functions
`createRenderer` uses, so a file it downloads is the file the project's code
renders.

**Pages**, in the toolbar, lays the page out as printed pages, meant to match
the pages of the PDF, each the size and with the margins the template names. It
is off until you select it, and the preview remembers the choice in that
browser. The printed pages hold the template's own elements, laid out by
Paged.js, which the preview serves from the project's install, so a comment
pins to their text.
Paged.js and Chrome's printing break pages independently, so an awkward layout
can break differently here than in the PDF, and the PDF is the one that is
right.

`--port` takes a whole number from `0` to `65535`, and `0` asks the system for
any free port. Anything else is refused. The preview listens on `127.0.0.1`
only, so another machine cannot reach it.

## `install-browser`

**Usage:** `commentware-documents install-browser`

Downloads the Chrome for Testing build the library prints PDFs with, into
Playwright's folder in your home directory, and ends with
`Chrome for Testing is installed.` It is the installer of the `playwright-core`
the library itself uses, so the build it downloads is the one the library looks
for, whichever package manager installed it. A project that names its own Chrome
in `browser.executablePath` does not need it. It reads no config, and a failed
download exits `1`.