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 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:

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:

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.