Markdown Image Caption: 3 Ways That Actually Render
September 11, 2026 · 8 min read
Markdown Image Caption: 3 Ways to Add Captions
There's no native markdown image caption syntax, so you have three workable options. Use an italic line under the image, an HTML <figure> with <figcaption>, or a single-cell table. This guide shows each one, says where it renders, and clears up the alt text vs title vs caption confusion that trips most people.
Alt Text, Title, and Caption Are Three Different Things
The standard image syntax carries two pieces of text, and neither of them is a caption.
Per the CommonMark spec, the text in square brackets becomes the alt attribute and the quoted string becomes the title attribute. Alt text is read aloud by screen readers and shown when the image fails to load. The title appears as a tooltip on mouse hover in most browsers, and never appears at all on touch devices.
A caption is visible text under the image that every reader sees. Markdown doesn't have one, which is why every method below is a workaround. Keep writing real alt text regardless; the Markdown image guide covers what makes alt text useful.
Three Ways to Add a Markdown Image Caption
Each method below trades portability for control. Start with the first; move down the list only when you need what the next one adds.
Method 1: The italic line under the image
The simplest caption is a short italic paragraph directly below the image.
*Figure 1: Monthly signups, January to June 2026*
That renders the image, then an italic line beneath it. It works in every renderer, because it's ordinary Markdown. It survives copy-paste into Slack, Notion, and email. It's what we use in READMEs.
The trade-off: it's just a paragraph. Screen readers don't associate it with the image, and it won't sit centred under a centred image without extra work. You also can't style it separately from other italic text. For a README or a quick note, none of that matters.
Method 2: HTML figure and figcaption
Where inline HTML is allowed, the semantically correct answer is a <figure> element. MDN's figure documentation describes it as self-contained content with an optional caption, which is exactly what an image plus caption is.
<figure>
<img src="signups.png" alt="Bar chart of monthly signups" width="600" />
<figcaption>Figure 1: Monthly signups, January to June 2026</figcaption>
</figure>
Assistive technology links the caption to the image, and your site CSS can target figcaption to style every caption at once. On GitHub, figure and figcaption are both in the sanitizer's default allowlist, so this renders in READMEs and issues. What GitHub strips is the style attribute and any class, so you can't centre the caption with CSS there.
Two rules keep the block from breaking. Leave a blank line before and after the <figure>, and don't put Markdown inside it. CommonMark treats the contents of an HTML block as raw HTML, so **bold** inside <figcaption> shows the asterisks. Use <strong> instead. Our Markdown vs HTML guide explains when this kind of drop into HTML is worth it.
Method 3: The single-cell table trick
This one isn't on most caption guides, and it's the only pure-Markdown way to get a boxed, centred caption on GitHub. Put the image in the header row and the caption in the one data cell.
|  |
|:--:|
| *Figure 1: Monthly signups, January to June 2026* |
The :--: delimiter centres both cells, so the caption sits directly under the image with a border around the pair. GitHub, GitLab, Obsidian, and any GFM renderer draw it as a table; the Markdown table guide has the alignment syntax if you want it left-aligned instead.
The limitation is visual: you get table borders whether you want them or not, and a renderer that styles tables with zebra stripes will stripe your caption. Use it when centring matters and HTML isn't available.
How Do You Center a Markdown Image Caption?
Centring is the second half of most caption searches, and the answer depends on whether style survives.
On GitHub, the sanitizer keeps the align attribute on <p> and <img> but removes style. So this works.
<p align="center">
<img src="signups.png" alt="Bar chart of monthly signups" width="600" />
<br />
<em>Figure 1: Monthly signups, January to June 2026</em>
</p>
The <br /> keeps the caption on its own line inside the centred paragraph. The single-cell table above is the other GitHub-safe route.
On your own site (Jekyll, Hugo, MkDocs, Docusaurus), use the <figure> form and add figure { text-align: center; } to your stylesheet. Everything on the page gets consistent captions with one rule.
In Obsidian, add a CSS snippet with the same figure rule; the Obsidian cheat sheet covers where snippets live.
Try All Three Captions in the Editor
All three methods are in the demo below with a placeholder image. Compare how the italic line, the figure, and the table look side by side, then delete the ones you don't need.
The Markdown to HTML converter shows the HTML each method produces, which is the quickest way to confirm the figcaption element made it through.
Which Caption Method Works on Each Platform?
| Platform | Italic line | figure and figcaption | Single-cell table | Centre with align |
|---|---|---|---|---|
| GitHub | Yes | Yes (no style) | Yes | Yes |
| Obsidian (reading view) | Yes | Yes, HTML is sanitized but rendered | Yes | Needs a CSS snippet |
| Jekyll (kramdown) | Yes | Yes | Yes | Yes, or CSS |
| Hugo | Yes | Only with unsafe = true, or a render hook | Yes | CSS |
| MkDocs | Yes | Yes | Yes | CSS |
| Pandoc | Yes | Yes | Yes | Output-format dependent |
Two platform notes go beyond the table. Hugo's image render hook can wrap every standalone image in a <figure> and use the image's .Title as the figcaption. That turns the normally invisible title into a real caption without writing HTML in your posts.
Pandoc does something similar out of the box. Its implicit_figures extension renders an image with nonempty alt text, alone in a paragraph, as a figure whose caption is the alt text (Pandoc manual). That's convenient for PDF export, and surprising when your alt text was written for screen readers rather than for print.
One acknowledged gap: Obsidian's help says HTML is rendered but sanitized without listing what's removed, so test a <figure> block in your vault before relying on it across hundreds of notes.
Common Caption Mistakes
Using the title as a caption.  puts the text in a tooltip nobody sees on a phone. Titles are hover text; captions need one of the three methods above.
Leaving alt text empty because the caption says it all. The caption is visible; alt text is what a screen reader announces. They have different jobs, so fill both.
Writing Markdown inside <figcaption>. Emphasis markers and links stay literal inside an HTML block. Use <em> and <a> tags there.
Markdown Image Caption FAQ
A markdown image caption is always a workaround, so pick the one that matches where the file will render. Italic lines travel anywhere, <figure> is right for sites you control, and the single-cell table centres a caption on GitHub without HTML. Paste the demo into the editor to see all three before you commit to one.