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
| Job | Windows | Linux and macOS |
|---|---|---|
PDF export (export --format pdf) | Word 2010 or later if installed, otherwise LibreOffice | LibreOffice |
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 fallback | LibreOffice, 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.
| Step | Switch | Choices |
|---|---|---|
| Document to PDF | --renderer, variable ASTRA_RENDERER, MCP renderer | auto, word, libreoffice |
| PDF to image | --pdf-to-image, variable ASTRA_PDF_TO_IMAGE, MCP pdfToImage | auto, windows, poppler |
autois 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 wordon a machine without Word stops withE_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
autofalls back, the result says so:renderer.fallbackFromandrenderer.fallbackReason(and the same forrasterizer) in--json, and anote:line on stderr. The MCP tools return the same in their result. exporttakes--rendererfor PDF only.--pdf-to-imageapplies to page images only.
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 libreofficeWord 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.