Three seams, three failure modes

Seam Typical failure What to check
Code Long lines run past the page, or wrap at the wrong column Does the block wrap or scale to the text width
Figures Captions detach, images overflow the text block Does the figure keep its caption and size to the page
Navigation Headings skip a level, bookmarks collapse Are heading levels consistent and bookmarked

None of these show up in a Markdown preview, because a preview has no page.

Code blocks

Most technical Markdown contains at least one line that is longer than the text block. There are two honest strategies:

  • Wrap the line at the printable width, keeping the source unchanged;
  • Scale the block down until it fits, which keeps the shape but shrinks the type.

Either is defensible. What is not defensible is clipping: a line that silently loses its last twenty characters is worse than a wrapped one. Language labels and line numbers are usually opt-in, because a printed page rarely needs them twice.

Figures and captions

A figure is only as useful as its caption, and a caption is only findable if it is text rather than part of the image. If you cannot search for the caption in the exported PDF, it was rasterised along with the picture.

In dense pages the other problem is placement: an image that is taller than the remaining space has to move, and the paragraph that introduced it must not end up on the previous page alone.

What a preflight pass can catch

Before export, a static check can report:

  • missing image files and missing alt text;
  • heading levels that jump (an h4 after an h2);
  • links and anchors that do not resolve;
  • documents that are too large for the configured limits.

It cannot tell you whether the diagram makes sense, and it does not modify the Markdown. Preflight is a checklist, not an editor.

Handwritten docs and repository docs

A technical page written in the studio is self-contained: you paste the Markdown and attach the assets. A page that lives in a repository is a tree — importing it keeps relative paths and includes, but the document is only as current as the ref you imported.

That difference decides the workflow: iterate in the studio, publish from a pinned tag.

A short checklist

  1. Find the longest code line and export it. It should wrap or scale, never clip.
  2. Search for a figure caption in the PDF. If it is missing, the caption is part of the image.
  3. Open the bookmark panel. Heading levels you skipped will show up as gaps.
  4. Run preflight once and read the warnings instead of dismissing them.

Try it

The technical documentation workflow covers code, figures and publication checks. If the docs live in a repository, use Git import (included in Pro and in the Thesis Pack); otherwise open the Markdown studio and export the default document first.

For formulas and diagrams mixed into the same pages, use the same editor and review the PDF feature set.

What we do not claim

Preflight is a static check over the source and assets; it does not prove the document is correct. Very wide code blocks and oversized figures still have limits, and the honest answer there is a landscape page or an appendix.