By Jetformat
HTML capture readiness is a page state indicating that the data and visible content needed for a PDF have finished preparing. A selector can expose that state to the renderer; a fixed delay alone cannot prove that a report request completed successfully.
Keep local assets with the page
Use a directory input when a report depends on local stylesheets, images, or fonts. Passing an isolated HTML file while leaving its assets elsewhere makes a successful capture less useful.
jetformat html to-pdf ./report-site -o report.pdf --page-size A4
For a deployed URL, supply an explicit output path. Verify that the renderer can reach the page and all required resources. A browser on your laptop reaching a private URL does not prove that a separately hosted renderer has the same network access.
Define readiness in the page
jetformat html to-pdf ./report-site -o report.pdf --wait-ready '.dashboard-ready' --wait-visible 'svg.chart' --wait 2s
Choose selectors that correspond to completed report data and visible chart content. A selector that exists before a network request completes is a weak readiness signal. The fixed delay is supplemental; it should not be the only explanation for why capture is reliable.
Separate connection and rendering failures
The service address comes from --server, JETFORMAT_HTML_SERVER, or its default. A connection failure is different from a blank chart, missing font, or print stylesheet that hides content. Establish connectivity first, then inspect the captured result.
Run pdf info to check page count and render a representative page to inspect fonts, chart labels, and page breaks. Office conversion and local PDF operations do not depend on this HTML endpoint.
See HTML-to-PDF setup and the HTML task guide.
Choose the signal that matches the content
| Signal | What it checks | Weak choice |
|---|---|---|
--wait-ready |
Selector exists | A wrapper present before data loads |
--wait-visible |
Selected element is visible | An empty chart frame |
--wait |
Additional elapsed time | The only condition for a variable-duration request |
| Output inspection | Content captured in the PDF | Checking only whether a file exists |
The page should expose its ready marker after the required report content has been committed. If a data request fails, do not set the same ready state used for a complete report. Otherwise, a blank error state can satisfy the selector and still produce a technically successful capture.
Verify readiness with a controlled test
- Confirm the renderer endpoint is reachable from the CLI environment.
- Load a representative report and identify which state means the data is complete.
- Choose selectors that reflect that state and the important visible content.
- Run capture with an explicit timeout and a new output path.
- Inspect text, chart labels, and pagination in the PDF, including the case where report data is unavailable.
A --wait 2s delay is 2 seconds; an example --timeout 30s allows 30 seconds. These are selected test settings, not measured renderer timings or guarantees. Start by fixing the readiness condition when capture is early instead of repeatedly increasing the wait.
Diagnose print-only differences
The screen and printed page can use different CSS. MDN’s printing guide describes print media rules and page controls. If content is present on screen but absent in the PDF, inspect those rules as well as resource access. Font availability and page breaks are separate checks from asynchronous readiness.
For an illustrative 4-page PDF, conversion uses 4 credits; 2 preview pages add 2 credits. Repeated successful captures are additional operations, so keep diagnostic runs small and representative.