Technical Docs Fail at the Seams
A technical document is not hard because it is long. It is hard because prose, code, figures and navigation each break in a different place.
Auf dieser Seite
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
alttext; - heading levels that jump (an
h4after anh2); - 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
- Find the longest code line and export it. It should wrap or scale, never clip.
- Search for a figure caption in the PDF. If it is missing, the caption is part of the image.
- Open the bookmark panel. Heading levels you skipped will show up as gaps.
- 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.
Dieselbe Rendering-Engine ist einen Klick entfernt. Öffne einen leeren Editor, füge dein Markdown ein und exportiere, wenn es fertig ist.