Skip to content
ASTra

Page images and PDF

Reading and editing a .docx needs nothing but Node.js. Drawing a page as an image, or exporting a PDF, needs a program that lays the page out. This page says which program ASTra uses, how to choose one, and what a render shows.

What you need

JobWindowsLinux and macOS
PDF export (export --format pdf)Word 2010 or later if installed, otherwise LibreOfficeLibreOffice
Page images (visual, inspect --visual, visual_inspect)The same program for the PDF, then the renderer built into Windows 10 and later, with Poppler as the fallbackLibreOffice, then Poppler

WSL is a Linux process: it always uses LibreOffice and Poppler, even when Windows has Word. If nothing usable is found, the command stops with E_DEPENDENCY and says what to install.

Choosing the programs

Two programs sit between a document and a page image, and each has its own switch.

StepSwitchChoices
Document to PDF--renderer, variable ASTRA_RENDERER, MCP rendererauto, word, libreoffice
PDF to image--pdf-to-image, variable ASTRA_PDF_TO_IMAGE, MCP pdfToImageauto, windows, poppler
  • auto is the default. For the PDF it means Word on Windows when Word is installed, LibreOffice if Word fails, and LibreOffice alone when Word is absent. On Linux and macOS it means LibreOffice. For the image step it means the built-in Windows renderer first and Poppler second on Windows, and Poppler elsewhere.
  • A program you name is never replaced. --renderer word on a machine without Word stops with E_DEPENDENCY. It does not quietly use LibreOffice.
  • A value given for the call beats the environment variable. An invalid variable is an error, not ignored.
  • When auto falls back, the result says so: renderer.fallbackFrom and renderer.fallbackReason (and the same for rasterizer) in --json, and a note: line on stderr. The MCP tools return the same in their result.
  • export takes --renderer for PDF only. --pdf-to-image applies to page images only.
shell
npx -y @attentionform/astra visual report.docx --page 1 --out page1.png
npx -y @attentionform/astra visual report.docx --page 1 --out review.png --show-markup
npx -y @attentionform/astra export report.docx --format pdf -o report.pdf
npx -y @attentionform/astra visual report.docx --page 1 --out word.png --renderer word        # Windows only
npx -y @attentionform/astra visual report.docx --page 1 --out lo.png --renderer libreoffice

Word on Windows

ASTra starts its own hidden Word through PowerShell, opens a copy of your file read-only, saves a PDF and closes Word. It never ends Word by force, so a Word that hangs on a document stays open until you end it. ASTra only ever closes the Word it started: it checks that the instance is its own and refuses one that looks used, and under auto it then uses LibreOffice. Two ASTra renders at once do not stop each other. If you run other programs that automate Word on the same machine, use --renderer libreoffice. See Security and privacy for the details.

Word and LibreOffice lay a page out differently, so page breaks and spacing can differ between --renderer word and --renderer libreoffice. Treat Word as the reference for how the file looks in Word.

The Windows page-image renderer draws the PDF crop box where Poppler draws the media box, so a PDF with a crop box differs by that margin. Sizes match Poppler within one pixel for ordinary pages.

Network references

A document can point at an image, template, linked document or field source on a network address. A renderer that follows it contacts that address. ASTra therefore changes those references on the copy it renders and leaves your file alone, so by default nothing is contacted. Pass --allow-network-references (MCP allowNetworkReferences) only when you asked for content from those addresses. The scan and its limits are in Security and privacy.

The render copy also drops the document's updateFields setting. With it, Word asks "update the fields in this document?" and a hidden Word cannot answer, so the render would stall.

Tracked changes and comments

By default a render shows no comments. Word draws the content as if changes were accepted; LibreOffice draws tracked changes with their marks, deleted text included. --show-markup (MCP showMarkup) asks for the review view:

  • Word: tracked changes inline and comments in balloons. ASTra sets the review view on its own hidden Word and restores the settings it changed before it closes the document.
  • LibreOffice: comments in the margin. This needs LibreOffice 7.6.7 or later; an older or unreadable version stops with E_DEPENDENCY, because older versions ignore the option.
  • Pages can be scaled and page breaks can change in the review view, so page numbers can differ from a render without markup.
  • A very long comment can be cut short, in both programs. The result carries a warning when that can happen.
  • The output shows reviewer names, deleted text and comments. Check it before you share it.

On the command line, --show-markup works with visual, inspect --visual and export --format pdf. The MCP visual_inspect tool needs withVisual, and export_document needs format: "pdf".

Known limits

  • A comment anchored inside a header, footer or footnote is not drawn by Word, and LibreOffice cannot open such a file at all.
  • Word's behaviour was recorded on one Word build. Check an important render by eye.
  • A document that carries macro parts is refused unless you pass --allow-macros (keep them) or --strip-macros (remove them). The two together are a usage error.