Images
An image—what goes into the text stream?
✅ NormativeSettled. The requirement holds as written.📄 Page ruleCan be applied from the page alone.Read §12.1.1 in the RFC ↗
The content of an image MUST be put into the text stream as whatever the image actually is — transcribed text, a table or a diagram. The output MUST NOT contain a file reference or a bracketed placeholder in place of an image.
When it applies
An image is not a thing to point at; it is content that happens to have been rasterised. Whatever a reader would take away from looking at it MUST end up in the output as text, or it is lost — the never drop failure.
Reading the examples. Each one pairs a source page with the output the rule expects. ✅ Sample: the rule applies. ❌ Counter-sample: it looks like it applies and does not, or a rendering got it wrong. A non-conforming output, in red, is shown only for contrast. … marks content left out of an excerpt.
The point, in a small example
Choose the representation from the content inside an image. This page covers classification; Images and Figures covers keeping that content in the surrounding page. These pages are made up to isolate the rule.
Text inside an image is still text
Transcribe all visible text, including the printed typo “Wednsday”. Do not substitute an image link, a summary or a corrected spelling. The top line is a notice label, not a document section.
Source page
Non-conforming output
What the rule rules out.
Expected output
Delivery notice
Arrives Wednsday at 09:30.
Gate B — keep this slip.A pictured table stays a table
The image contains a two-column table. Preserve both rows and the printed headers; a prose summary loses the cell relationships.
Source page
Non-conforming output
What the rule rules out.
A table listing stationery supplies.Expected output
<table>
<tr><th>Item</th><th>Count</th></tr>
<tr><td>Pencils</td><td>12</td></tr>
<tr><td>Pens</td><td>7</td></tr>
</table>A chart image preserves its values
Use the printed values 4 and 8, not estimates from bar heights. Keep the title and month labels in the chart table.
Source page
Non-conforming output
What the rule rules out.
Orders increased from April to May.Expected output
<table data-source="chart">
<caption>Orders</caption>
<tr><th>Month</th><th>Orders</th></tr>
<tr><td>Apr</td><td>4</td></tr>
<tr><td>May</td><td>8</td></tr>
</table>A flow image becomes a diagram
Keep all three printed labels and both directed connections. This simple flow fits Mermaid; other faithful supported diagram languages are valid.
Source page
Non-conforming output
What the rule rules out.
[A three-step process diagram]Expected output
```diagram/mermaid
flowchart LR
A[Receive] --> B[Review]
B --> C[Archive]
```Decorative artwork needs a description
There are no labels or data points to transcribe. Describe the visible artwork in prose without inventing a place, date or artist.
Source page
Non-conforming output
What the rule rules out.
Expected output
An illustration of two overlapping mountains beneath a yellow sun in a pale blue sky. The taller mountain on the left has a white peak.Decide what the image is, then encode that
| The image is really… | The output MUST contain |
|---|---|
| Text rendered as a picture | The text, transcribed verbatim |
| A data display (chart, plot) | A chart table — Cover Every Data Point (§11.1.1) |
| A labelled schematic or conceptual figure | A suitable diagram/<language> block; description only if none can preserve it — Slide Diagrams (§12.2.5) |
| A graph of relationships or a flow | A diagram/<language> fenced block (for example diagram/mermaid or diagram/plantUml) — Diagrams and Flowcharts (§12.2.2) |
| A photo or decorative art | A prose description of what it shows |
The rows are tried in order. Where any text at all is legible inside the image, that text MUST be transcribed: it is content, and describing it instead ("a chart showing quarterly revenue") drops every number on the page.
When the type is not obvious
Some figures resist the table above: maps, chemical structures, electrical schematics, blueprints, printed staves. Each has its own rule — Geographic Maps (§12.2.4), Chemical Molecules (§13.1), Electrical Schematics (§12.2.3), Blueprints (§12.2.1), Music Notation (§13.2), Slide Diagrams (§12.2.5). Where that rule has no settled encoding yet, the fallback is the same: every label and every legible string MUST be preserved, and the output MUST use the encoding that loses no content.
Neighbouring rules, and how they differ
More
Rule id images-images · rule images