HTML, PDF, and conversion pipelines

Pick the destination format#

The plugin exposes HTML, PDF, DOCX, Markdown, and reStructuredText export actions. HTML preserves web-oriented structures; PDF produces a paginated artifact; text/document conversions may represent layout and extension content differently.

Start from the intended entry document with its includes, attributes, images, and root settings resolved. Exporting one chapter alone can lose attributes supplied by the book header.

Configure the required tools#

HTML and PDF use their configured rendering pipelines. DOCX, Markdown, and reStructuredText conversions require the relevant external conversion tooling, including Pandoc where configured. Check the executable path and its version before treating a process-launch failure as malformed AsciiDoc.

PDF output also depends on the configured PDF engine, fonts, and resources. Preview success establishes that one renderer worked; it does not validate another engine’s installation.

Use a compact verification document#

Include a heading, a link, a table, an image, and a source block in a small test document. Add the same diagram/extension constructs used by the real manual. Export that document first to distinguish a tool setup problem from one expensive or unsupported part of a large book.

Check the output directory and timestamp after export. A stale file with the expected name is not evidence of a successful new build.

Review the artifact#

Open the output and verify heading hierarchy, internal links, tables, image paths, non-ASCII text, source formatting, and page breaks where applicable. For converted Markdown/RST, inspect the source as well as its rendering before committing it.

Retain the original AsciiDoc source and build configuration. Generated artifacts should be reproducible from those inputs; editing only the exported HTML or converted document makes the next export discard the change.