Keeping long articles readable: code, tables, images, and captions

An article whose paragraphs all wrap correctly is not necessarily easy to read on a phone. A long command can widen the entire page, a table can be squeezed until each cell holds only a few characters, and an image can shrink until its labels are unreadable.

These problems cannot be solved just by reducing the font size. Body text, code, and data tables need different treatment to preserve their information; putting an image next to a caption does not automatically make it clear, either. I care more about whether readers can still do what they came to do when they switch to a narrow screen.

This note records the site’s article layout as observed on October 23, 2026: how it handled these cases and where editorial judgment was still needed.

Decide which content needs its structure preserved

Body text can wrap to fit its container, but indentation in code and row-and-column relationships in a table may be part of what makes the content understandable. Forcing everything to wrap can remove a horizontal scrollbar while hiding a different reading problem.

I start with what the reader needs to do:

Content	What the reader needs to retain	First layout decision
Body text	Sentence order and relationships between paragraphs	Wrap to the available width so reading one line does not require moving the whole page sideways
Inline identifiers or URLs	The name and its relationship to the surrounding sentence	Allow wrapping when necessary so a single long string does not widen the body
Code blocks	Indentation, line boundaries, and content that can be copied	Trim the example first, then decide whether local horizontal scrolling is needed
Data tables	Relationships between headers, rows, and columns	Remove unnecessary columns first, then let the table itself scroll if needed

W3C’s explanation of Reflow also distinguishes ordinary content from blocks that need a two-dimensional layout to be understood. A data table can have its own scrolling container, but this exception does not give adjacent paragraphs permission to overflow horizontally.[1]

A table that scrolls horizontally should not widen the entire article page. Nor should every long piece of code automatically be treated as exempt from reflow.

Trim code to what explains the point before deciding how it should scroll

In that layout, code blocks kept horizontal scrolling local, while inline code allowed long strings to wrap. The relevant rules can be summarized in plain CSS as follows:

.note-body pre {
  max-width: 100%;
  overflow-x: auto;
}

.note-body :not(pre) > code {
  overflow-wrap: anywhere;
}

This excerpt covers only the width and wrapping decisions, not the full typography, spacing, or surface styling. The article’s main column and body container also used min-w-0 to let their contents shrink within the layout. Copying overflow-x: auto alone does not guarantee that every surrounding layout will avoid overflow.

Scrolling is a way to fit content, not evidence that the example is readable. If a whole configuration file is pasted in to explain one decision, readers still have to find the relevant lines among unrelated ones.

I first remove code that does not support the point and explain the conditions that matter nearby. I accept the cost of horizontal scrolling only when readers really need to read a complete line or preserve indentation and the original structure. “Code is long by nature” is not a reason to skip editing.

Keep tables comparable instead of squeezing every cell

Tables let readers compare items using the same fields. If a phone-sized layout turns every cell into a long, narrow column of text, that advantage may be lost.

The site’s tables used display: block, width: fit-content, max-width: 100%, and overflow-x: auto to keep any necessary horizontal movement within the table. This balances preserving the comparison structure with the width available; it does not mean every table should retain the same shape.

When reviewing a draft, I first look for columns that only repeat explanations and cells that have grown into full paragraphs. If the rows do not need to be compared, subsections may work better. If column-by-column comparison is necessary, I keep the relationship between headers and data rather than remove important information just to fit the screen.

It also takes a separate check to find out whether readers can discover horizontally hidden content and whether keyboard users can reach and operate the scrolling area. In the original preview inspected for this article, code blocks had tabindex="0"; tables did not have that attribute. Their operating conditions need separate checks. CSS or a tabindex alone is not enough to claim that keyboard operation has been fully verified.

An image can fit while its information is still unreadable

Article images used max-width: 100% and automatic height so their original width would not push the body wider. But a flowchart with lots of small text may still need to be redrawn, split into several images, or explained in text, even when the whole image fits on screen.

A caption should explain how to interpret the image: its scope, the conditions being compared, or the difference between a schematic and the actual state. Repeating “This is a flowchart” usually adds too little information.

HTML’s figure can treat a self-contained image, chart, or other content as one unit, with figcaption supplying that unit’s title or explanation.[2] The site already had styles for figcaption, but the selector’s existence did not mean every Markdown image had a caption. The output still needs the corresponding content and structure.

The division of work between a caption and alt text also depends on context. If an image adds information not explained by the surrounding text, it still needs an understandable alternative; if that information is already repeated in full in the text, the treatment is different. WAI’s alt decision tree starts with what meaning the image adds in its context, not simply whether it has a visible caption.[3]

Image loading and failure states are a separate responsibility. Here, the concern is whether article readers can understand an image; layout settings are not evidence of better loading behavior or performance.

Review readability with content that is actually hard to lay out

An empty layout or a few short paragraphs will not expose the most common trouble spots in a long article. Choose an article that really contains long identifiers, code blocks, tables that require comparison, and images with small text, then read through the body.

I treat correct output and smooth reading as separate questions. For the former, I can inspect the HTML and check that headings, table headers, and captions are present. For the latter, I still need to use narrow screens, enlarged text, and the intended ways of operating the page to check for clipped information, discoverable scrolling, and whether readers have to keep looking for the relevant explanation.

This note describes layout responsibilities and an editorial review method. It is not a site-wide accessibility certification, and it does not measure reading comfort across all devices. The layout recorded on October 23, 2026 already had local scrolling, image-width rules, and caption styles, but those still need to be judged by reading real articles. If content only just fits after repeatedly shrinking the font, its organization deserves another look.

Sources

[1] https://www.w3.org/WAI/WCAG22/Understanding/reflow.html — W3C — Understanding SC 1.4.10 Reflow [2] https://html.spec.whatwg.org/dev/grouping-content.html — WHATWG — Grouping content: figure and figcaption [3] https://www.w3.org/WAI/tutorials/images/decision-tree — W3C WAI — An alt Decision Tree