Images in Markdown Tables: Size, Badges and Avatars
By MarkdownTables.com editorial teamUpdated
On this page
How do I put an image in a Markdown table?
An image is inline content, just like a link, so it's allowed in a cell. Some older guides say images can't go in Markdown tables; on GitHub and every other GFM renderer they can.
| Tool | Badge |
| ------- | ------------------------------------------------------- |
| Node.js |  |
| Python |  || Tool | Badge |
|---|---|
| Node.js |  |
| Python |  |
In a repository, use paths relative to the Markdown file. GitHub resolves them against the file's folder and branch, so the images keep working in forks and on other branches:
| Screen | Preview |
| -------- | ----------------------------------------- |
| Login |  |
| Settings |  |Always write alt text. It's what screen readers announce and what readers see if the image fails to load. For a purely decorative image next to a name that already says everything, empty alt text (alt="") is correct.
How do I set the image size in a Markdown table?
Neither CommonMark nor GFM has image-size syntax. Each renderer that supports sizing adds its own, and the HTML <img> tag works everywhere that allows raw HTML:
| Platform | Syntax | Notes |
|---|---|---|
| GitHub, VS Code, Jupyter, Docusaurus | <img src="a.png" width="80"> | Pixels or %; style stripped on GitHub |
| GitLab | {width=80} or {width=75%} | height= too; <img> also works |
| Pandoc, Quarto, R Markdown | {width=30%} | Units: px, cm, in, % |
| MkDocs (attr_list) | { width="80" } | Enable attr_list in mkdocs.yml |
| kramdown (Jekyll) | {: width="80"} | Inline attribute list |
| Obsidian | ![[a.png\|80]] or  | Escape the | inside tables |
<img width> at three sizes| Size | Image |
| ----- | ---------------------------------------------------------------- |
| 32 px | <img src="https://github.com/octocat.png" width="32" alt="Octocat, 32 px"> |
| 64 px | <img src="https://github.com/octocat.png" width="64" alt="Octocat, 64 px"> |
| 96 px | <img src="https://github.com/octocat.png" width="96" alt="Octocat, 96 px"> || Size | Image |
|---|---|
| 32 px |  |
| 64 px | |
| 96 px | |
Set only width (or only height) to keep the aspect ratio. A percentage is relative to the cell, which itself sizes to content, so pixels are more predictable.
GitLab, Pandoc and Quarto attribute syntax
These keep the Markdown image syntax and add attributes in braces right after it, with no space:
| Screen | Preview |
| ------ | ----------------------------------------- |
| Login | {width=120} |
| Wide | {width=75%} || Screen | Preview |
| ------ | -------------------------------------------- |
| Login | {width=30%} |kramdown (Jekyll) and MkDocs
| Screen | Preview |
| ------ | ------------------------------------------------ |
| Login | {: width="120"} || Screen | Preview |
| ------ | ------------------------------------------------ |
| Login | { width="120" } |Obsidian
Obsidian puts the size after a pipe, which would split the cell. Inside a table, escape it as \|:
| Screen | Preview |
| ------ | --------------------------- |
| Login | ![[login.png\|120]] |
| Logo |  |Badges in tables (shields.io)
shields.io badges are SVG images, so they go in cells like any image. A static badge URL is https://img.shields.io/badge/LABEL-MESSAGE-COLOR; write a literal dash as --, an underscore as __ and a space as _ or %20.
| Package | Version | License | Status |
| -------- | ------- | ------- | ------ |
| core |  |  |  |
| plugins |  |  |  || Package | Version | License | Status |
|---|---|---|---|
| core |  |  |  |
| plugins |  | |  |
Wrap the image in a link to make the whole badge clickable:
| Package | Docs |
| ------- | ---- |
| core | [](https://example.com/docs) || Package | Docs |
|---|---|
| core |  |
Dynamic badges read live data (package versions, CI status, licenses). Replace OWNER/REPO with your repository; each line goes in its own cell:
Badges carry their own color, which makes them the most readable way to show colored status on GitHub (see text formatting and color). Keep alt text meaningful, such as “status: stable”, because screen readers can't read the text inside the SVG.
Avatars and contributor tables
Every GitHub account has an avatar at https://github.com/USERNAME.png; add ?size=80 to fetch a smaller file. Set the display size with width, and use empty alt text when the username is in the next cell:
| | Maintainer | Area |
| :-: | ---------- | ---- |
| <img src="https://github.com/octocat.png?size=80" width="40" alt=""> | [@octocat](https://github.com/octocat) | Core |
| <img src="https://github.com/github.png?size=80" width="40" alt=""> | [@github](https://github.com/github) | Docs |
For a contributor grid, put the avatars in the header row and the names in the row below, and center the columns. To stack an avatar and a name in one cell instead, join them with <br>:
| <img src="https://github.com/octocat.png?size=120" width="60" alt=""> | <img src="https://github.com/github.png?size=120" width="60" alt=""> |
| :-: | :-: |
| [@octocat](https://github.com/octocat) | [@github](https://github.com/github) |
Alignment, links, alt text and dark mode
- Horizontal alignment. Center or right-align the column with
:---:or---:(see column alignment). Don't usealign="center"on the<img>: on an image,alignmeans float. - Vertical alignment. There is no syntax for it. Rows are as tall as the tallest cell; keep images in a row the same height.
- Column width. A column grows to fit its widest image. Set
widthon images to control it; more tricks in column width. - Links.
[](https://…)makes the image clickable. On GitHub, an image without a link already opens the full file when clicked. - Dark and light variants. GitHub supports
<picture>with aprefers-color-schemesource. Keep the whole element on one line in the cell:
| Logo | Product |
| :--: | ------- |
| <picture><source media="(prefers-color-scheme: dark)" srcset="img/logo-dark.png"><img src="img/logo-light.png" width="64" alt="Acme logo"></picture> | Acme CLI |Image support by platform
| Platform | Markdown image | Set the size | Badges (SVG) |
|---|---|---|---|
GitHub (GFM)width, height and alt are kept; style is stripped. <picture> works. | Yes | Partly: <img width> | Yes |
| GitLab (GLFM) | Yes | Yes: {width=…} or <img width> | Yes |
| ObsidianEscape the pipe in size syntax inside tables. | Yes | Yes: ![[img.png\|120]] | Yes |
| VS Code preview | Yes | Partly: <img width> | Yes |
| Jupyter | Yes | Partly: <img width> | Yes |
| Pandoc / Quarto | Yes | Yes: {width=30%} | Partly: SVG may need conversion for PDF |
MkDocsEnable the attr_list extension. | Yes | Yes: { width="120" } | Yes |
| Jekyll / GitHub Pages (kramdown) | Yes | Yes: {: width="120"} | Yes |
Docusaurus / HugoHugo needs markup.goldmark.renderer.unsafe: true for raw <img>. | Yes | Partly: <img width> | Yes |
✅ supported · ⚠️ partly or with a workaround · ❌ not supported · Last verified October 2026
Common mistakes and fixes
Linking to the GitHub page instead of the image
A /blob/ URL is an HTML page, not an image, so the cell shows a broken image. Use a relative path, or a raw URL (raw.githubusercontent.com or ?raw=true) for images in another repository.
| Screen | Preview |
| ------ | -------------------------------------------------------------- |
| Login |  || Screen | Preview |
| ------ | ------------------------------- |
| Login |  |A pipe in the image URL
A | anywhere in the row starts a new cell, URLs included. Percent-encode it as %7C.
| Metric | Badge |
| ------ | --------------------------------------------------- |
| Score |  || Metric | Badge | Column 3 |
|---|---|---|
| Score |  |
| Metric | Badge |
| ------ | ----------------------------------------------------- |
| Score |  || Metric | Badge |
|---|---|
| Score |  |
Sizing with CSS on GitHub
GitHub drops style, so the image renders at full size. Use the width attribute.
| Logo | Name |
| ---- | ---- |
| <img src="https://github.com/octocat.png" style="width:40px" alt="Octocat"> | Octocat || Logo | Name |
| ---- | ---- |
| <img src="https://github.com/octocat.png" width="40" alt="Octocat"> | Octocat || Logo | Name |
|---|---|
| Octocat |
The table validator flags rows where a stray pipe changed the column count.
When to switch to HTML or drop the table
Pipe tables with <img width> cover most README needs. Write an HTML table when you need images in merged cells, captions under each image, or multiple images stacked with text in one cell. If you're only using a table to put screenshots side by side, consider dropping the table: images in a paragraph already sit next to each other and wrap on small screens, and a layout table confuses screen readers.
For the rest of the cell rules see Markdown table syntax; for status icons without images see checkboxes and status icons.
Frequently asked questions
Can you put an image in a Markdown table?
Yes. Standard image syntax works inside a cell: |  | Acme |. GitHub, GitLab, Obsidian, VS Code and static site generators all render it. The image is inline content, like a link, so it fits the one-line cell rule.
How do I resize an image in a Markdown table?
<img src="logo.png" width="80"> sets the width on GitHub and anywhere raw HTML is allowed. GitLab, Pandoc and Quarto also accept {width=80}, kramdown uses {: width="80"}, and Obsidian uses ![[logo.png\|80]] with the pipe escaped.
Why can’t I resize an image with style on GitHub?
GitHub removes the style attribute from all HTML, so style="width:80px" is ignored. Use the width or height attribute instead: <img src="logo.png" width="80">. Setting only one keeps the aspect ratio.
How do I add badges to a Markdown table?
Use image syntax with a shields.io URL: . The path is label-message-color; write a literal dash as -- and a space as _. Wrap it in a link to make the badge clickable.
How do I center an image in a Markdown table cell?
Center the column with :---: in the delimiter row. There is no vertical-alignment syntax, and the HTML align attribute on <img> floats the image rather than centering it, so don’t use it in cells.
Why is my image not showing in a GitHub table?
Usually the URL points to a GitHub page instead of the file (a /blob/ link), the relative path is wrong for that file’s folder, or a | in the URL split the cell. Use a path relative to the Markdown file and encode pipes as %7C.
Can I show different images in light and dark mode in a table?
Yes, on GitHub: put a <picture> element with a <source media="(prefers-color-scheme: dark)"> and a fallback <img> in the cell, all on one line. Renderers that strip <picture> show only the fallback image.
Build the table in a grid, paste image tags into cells, and copy the Markdown.
Open the table generator