The syntax is the easy part.  is the whole of it, and it works everywhere.
What goes wrong is upstream of the syntax: the file itself is too small, or the wrong format, or a colour space that shifts when printed. All three look perfectly fine in the preview and only reveal themselves in the exported PDF, which is the worst possible moment to discover them.
The pixel arithmetic
Screens are measured in pixels, paper in inches, and the number joining them is pixels per inch. A screen renders CSS at about 96 per inch. Print wants 300 for photographs and detailed artwork. So an image that fills a 6-inch column needs 1,800 pixels across — not the 576 that filled the same visual space in your browser.
pixels needed = printed width in inches x 300
A4 text column, 25mm margins:
210mm - 50mm = 160mm = 6.3in
6.3 x 300 = ~1,900 pixels wide| Printed at | Minimum pixels wide | Comfortable |
|---|---|---|
| Full A4 column (160mm) | 1,890 | 2,200 |
| Half column (80mm) | 945 | 1,200 |
| A thumbnail or icon (25mm) | 295 | 400 |
| Full bleed A4 (210mm + bleed) | 2,600 | 3,000 |
Screenshots are the usual culprit
A screenshot taken on a standard display is captured at the size it appeared — often 800 or 1,000 pixels for a window that will be printed six inches wide. That is a third of what it needs, and enlarging it in the layout makes the softness worse rather than better.
- Capture on a high-DPI display if you have one. A Retina or 4K screen captures at 2× or more, which gets you most of the way there for free.
- Capture the region, not the screen. A full-screen grab downsized to fit a column throws away the detail you needed and keeps a lot of desktop nobody wants.
- Zoom the application in before capturing rather than scaling the image up afterwards. Text rendered at 200 percent is real detail; text scaled at 200 percent is a blur.
- Never screenshot a screenshot. Each pass through a lossy format degrades the last one, and it is visible by the third generation.
Choosing the format
| What the image is | Format | Why |
|---|---|---|
| Photograph | JPEG, quality 85–90 | Continuous tone compresses well; artefacts hide in detail |
| Screenshot or UI | PNG | Flat areas and sharp text; JPEG smears both |
| Diagram, chart, logo | SVG if the renderer takes it, otherwise PNG at 2× | Vector stays sharp at any size |
| Anything needing transparency | PNG | JPEG has no alpha channel |
| Scanned line art | PNG | JPEG fringes every edge |
The one to be deliberate about is screenshots as JPEG. It is the default on a lot of capture tools, and JPEG's compression is built for photographs — around every letter of a UI label it leaves a halo. At small sizes on screen you will not see it. At 300ppi on paper you will.
Colour, and why a print looks duller
Screens emit light and mix red, green and blue. Presses put ink on paper and mix cyan, magenta, yellow and black. The RGB gamut is larger, so the brightest screen colours — saturated oranges, electric blues, neon greens — simply have no ink equivalent, and a conversion picks the nearest printable colour.
For a PDF that will be read on a screen or run off an office printer, leave everything in RGB and stop thinking about it. For a book going to a printer, this becomes one of the checks in what makes a PDF print-ready. The practical version: avoid building a design on one screaming accent colour, because that is the colour most likely to come back looking flat.
Placement, and the break you cannot see coming
In a paginated document an image has to be somewhere, and "here, in the flow" occasionally collides with the bottom of a page. The two bad outcomes are an image split across the fold, and an image pushed to the next page leaving a hand-sized gap behind it.
The gap is usually correct and only looks like a mistake. An image that cannot fit in the remaining space has to move, and the alternative — floating it somewhere else entirely, as LaTeX does by default — is how figures end up three pages from the sentence that refers to them.
- Keep captions with their image. A caption stranded at the top of the next page is worse than a gap.
- Refer to figures by name, not position. "The diagram below" is a promise pagination can break; "figure 3" is not.
- Put a deliberate break before a large image if it is the start of a section anyway — a hard page break turns an awkward gap into an intentional opening.
- Reserve full-page images for things that earn it. Full-bleed art on a page of its own is a decision; an oversized screenshot is an accident.
Alt text is not optional
The text in the square brackets is what a screen reader announces. In an EPUB that is the only description of the image a blind reader gets, and several stores check for it. It costs a sentence.
The first is invisible to a screen reader. The second is noise. The third is the information the picture was carrying — which is the test: if the image did not load, would this sentence do its job?
A checklist before you export
- Every image is at least 300ppi at the size it will print.
- Photographs are JPEG; screenshots, diagrams and anything with transparency are PNG.
- No image has been scaled up from a smaller original.
- Every image has alt text that says what it shows.
- Nothing important sits within 10mm of a page edge unless it is deliberately full-bleed.
- You have looked at the exported PDF at 100 percent, not at the preview — that is the only view showing you real pixels on a real page.
In bukpress, images sit in the flow and are held on the page they belong to rather than floated away from their text, and the preview repaginates as you write — so the collision at the foot of a page is something you see while you can still do something about it. The sample book shows the finished behaviour on a real page.