Standard Markdown’s image syntax — ![alt](url) — has no way to control size or alignment. There’s no width=, no center, nothing. So the moment you need a smaller image, or one centered on the page instead of jammed against the left margin, you reach for a workaround: wrap it in an <img> tag with width/height attributes, or drop it in a <div align="center">. That workaround works beautifully on some platforms and does absolutely nothing on others, because it depends entirely on whether the destination renderer passes raw HTML through untouched — and that’s a much less consistent behavior across the Markdown ecosystem than most people assume.

This guide covers where the HTML-in-Markdown technique actually works, where a platform has its own separate, non-HTML syntax for the same job, and where images need to go through the platform’s own attachment mechanism instead. If you want the full rundown of resizing syntax first, our guide to changing image size in Markdown and our deeper image alignment and positioning guide cover that ground in detail; this post assumes you know the basic techniques and focuses on where each one is actually honored. And if you’d rather generate a correctly-sized, aligned image snippet — with an optional caption or link wrapper — without hand-writing the HTML, our new Markdown Image Formatter does that for you.

The Core Technique: Inline HTML

The workaround every image-sizing tutorial teaches is the same one:

<img src="diagram.png" alt="Architecture diagram" width="500">

<div align="center">
  <img src="diagram.png" alt="Architecture diagram" width="500">
</div>

Whether this renders as a resized, centered image or as a chunk of literal, unrendered text depends entirely on one thing: does the destination treat the Markdown source as “Markdown with inline HTML allowed,” or does it sanitize/strip HTML before or during rendering? That single distinction is the whole story for most of the platforms below.

GitHub and GitLab: Full Support

GitHub and GitLab both parse inline HTML inside Markdown files — READMEs, wiki pages, issues, and pull requests all honor <img width="..."> and alignment wrappers like <div align="center"> or <p align="center">. This is the environment the workaround was basically invented for, and it’s why you see it everywhere in open-source READMEs with a centered logo at the top.

<p align="center">
  <img src="logo.png" alt="Project logo" width="300">
</p>

Both platforms do strip genuinely dangerous content — <script> tags and inline event-handler attributes like onclick don’t survive — but plain presentational attributes on an <img> or a <div align> wrapper pass through untouched in both README files and rendered issue/PR comments.

Notion: Strips HTML, Uses Its Own Block Instead

Notion does not render inline HTML in imported or pasted Markdown — as covered in our Notion companion post, raw HTML blocks are stripped on import, full stop. An <img width="300"> tag doesn’t get sanitized down to a plain image; it just disappears, or at best leaves behind orphaned text.

Instead, Notion has its own native image block: drag an image in, or paste an image URL on its own line, and Notion creates an image block with a drag handle on the corner for resizing and an alignment control (left/center/full-width) in the block’s own toolbar. This is a completely different mechanism from Markdown syntax — there’s no text-based way to specify the size in the source document, because sizing happens as a manual, post-import editing step inside Notion’s own UI.

Slack: Strips HTML, No Sizing Control At All

Slack’s mrkdwn format strips raw HTML entirely, matching what our Markdown to Slack companion post already documents for the format generally — there’s no HTML passthrough to lean on here either. But unlike Notion, Slack doesn’t have an equivalent native resize/align control for images sent as part of a message’s text at all. A Markdown image reference in mrkdwn doesn’t render inline as an image — it’s ignored as text.

To actually get an image to display in Slack, you need a separate image block in Block Kit (the API for building rich Slack messages), which takes an image_url and alt_text — no width, height, or alignment parameter exists on that block type. If you’re pasting into the message composer by hand rather than going through the API, you attach the image file directly to the message instead of referencing it in text. Either way, there’s no sizing or alignment control at all through Slack’s own message formatting — full stop.

Obsidian: Its Own Embed Syntax, Not HTML

Obsidian takes a third approach entirely: it has its own embed syntax, separate from both standard Markdown images and inline HTML, and it does support sizing directly in plain text:

![[diagram.png]]
![[diagram.png|300]]
![[diagram.png|300x150]]

The double-bracket embed (the same wiki-link syntax Obsidian uses for linking between notes) accepts a pipe-separated width in pixels, or a widthxheight pair for both dimensions. This is a real, working, plain-text mechanism — no HTML required — but it’s Obsidian-specific: those pipe-delimited numbers mean nothing to any other Markdown renderer, and a file using ![[diagram.png|300]] synced or copied out to GitHub or a static site generator will show up as a broken, literal wiki-link rather than a sized image.

Alignment is a separate story and less standardized: Obsidian’s core embed syntax has no built-in center/left/right keyword the way its |300 width modifier exists. Centering an embedded image typically means either a CSS snippet targeting .markdown-rendered img in Obsidian’s own appearance settings, or a community plugin (several exist specifically for this). Standard <img>-tag HTML does also work inside Obsidian’s own renderer if you’d rather use the same technique as GitHub — Obsidian doesn’t strip inline HTML — but it’s not the idiomatic Obsidian way, and text written that way is really written for the HTML-friendly platforms, with Obsidian just happening to also render it.

Jekyll (Kramdown), MkDocs, and Docusaurus: Confirmed, Not Assumed

Since this blog itself runs on Jekyll with kramdown, we can confirm this one rather than guess: kramdown passes inline HTML through by default — that’s exactly how the raw <img>/<div> snippets elsewhere on this site’s own posts render correctly — so the standard HTML-sizing workaround works here without any special configuration.

MkDocs, built on Python-Markdown, also allows raw HTML through by default — Python-Markdown’s core design treats HTML blocks as pass-through content unless you’ve deliberately enabled an extension that sanitizes it, which isn’t part of a stock MkDocs or MkDocs Material setup. So the same <img width="..."> technique works there too.

Docusaurus is the one genuine exception worth calling out, because it’s not just “Markdown” under the hood — it compiles content through MDX, which parses HTML-like syntax as JSX rather than passing it through as literal HTML text. A plain <img width="300"> tag generally still works, since it’s valid JSX syntax too, but MDX is considerably stricter about HTML syntax than kramdown or Python-Markdown are: unclosed tags, HTML comments, and certain attribute-quoting patterns that browsers happily tolerate can cause an outright MDX compile error rather than being ignored or downgraded gracefully. If you’re moving a directory of existing image-heavy Markdown into a Docusaurus site, this is worth testing rather than assuming a clean HTML-passthrough experience.

Confluence and Jira: Neither HTML Nor a Text Syntax

Confluence is the platform where the HTML workaround fails most completely. Our Confluence companion post already documents that pasting Markdown mixed with HTML gets the HTML stripped or escaped during the paste-conversion step — an <img width="300"> tag doesn’t survive being pasted as part of a Markdown block at all. Confluence does auto-convert a plain ![alt](url) image reference into an embedded image on paste, but from there, resizing and alignment are done as a manual step in Confluence’s own rich-text editor after the image lands on the page — click the image, drag a resize handle or pick an alignment option from its floating toolbar. There’s no Markdown-adjacent text syntax for it at all, HTML or otherwise.

Jira is similar but starts from a different syntax entirely. Jira wiki markup’s own image notation is !attachment.png!, with modifiers like !attachment.png|thumbnail! — not Markdown syntax, and not HTML, as our Jira wiki markup companion post documents for the format generally. Sizing beyond the handful of built-in modifiers isn’t available through wiki markup text at all. In the modern Jira Cloud rich-text editor (outside classic wiki-markup-based projects), the equivalent workflow is the same as Confluence: the image has to actually be attached to the issue, then resized by dragging a handle in the editor — there’s no way to type your way to a specific pixel width.

Quick Reference

Platform Sizing mechanism HTML passthrough?
GitHub / GitLab <img width> / <div align> Yes
Notion Native image block, drag-resize + alignment toolbar No — HTML stripped
Slack None via text; separate Block Kit image block (no size param) No — HTML stripped
Obsidian ![[file.png\|300]] embed syntax (own convention) Yes (but not idiomatic)
Jekyll (kramdown) <img width> / <div align> Yes
MkDocs (Python-Markdown) <img width> / <div align> Yes
Docusaurus (MDX) <img width> — parsed as JSX, stricter syntax rules Mostly, with caveats
Confluence Manual resize via editor after paste/attach No — stripped on paste
Jira !file.png\|thumbnail! modifiers, or manual resize (Cloud editor) No

What This Means in Practice

If you’re writing documentation that lives primarily on GitHub, GitLab, a Jekyll site, or MkDocs, the <img width> / <div align="center"> technique is safe to rely on — it’s the same technique across all four, and it’s the one most existing tutorials (including our own) teach as the default answer. Docusaurus generally tolerates it too, just test your specific images rather than assuming.

The moment content needs to also live in Notion, Slack, Confluence, or Jira, that same HTML gets silently discarded or simply never applies, and there’s no universal substitute — each of those four has picked a genuinely different mechanism (a native resizable block, a separate API block type with no size control, a post-paste manual editor step, or Jira’s own attachment modifiers). If your workflow moves the same source Markdown across several of these platforms, plan on images being one of the places you can’t avoid a platform-specific manual step, rather than something you can format once in the source file and have travel cleanly everywhere. For the general version of this problem — what else breaks when Markdown crosses platforms — see our platform compatibility guide and our troubleshooting guide for Markdown that isn’t rendering.