[{"data":1,"prerenderedAt":72},["Reactive",2],{"blog-post-markdown-image-sizing-alignment-across-platforms":3},{"slug":4,"title":5,"description":6,"excerpt":7,"date":8,"category":9,"author":10,"keywords":11,"readingMinutes":12,"html":13,"headings":14,"tools":46,"related":48},"markdown-image-sizing-alignment-across-platforms","Markdown Image Sizing and Alignment Across Platforms: What Actually Works","Wrapping an image in a sized, centered \u003Cimg> tag works great in GitHub — but paste that same Markdown into Notion or Slack and the HTML just vanishes. Here's which platforms honor inline HTML for images, which have their own separate syntax, and which need attachments instead.","Standard Markdown's image syntax — — 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…","2026-09-04","workflows","Matt Rathbone","markdown image size, markdown image alignment, resize image markdown, center image markdown, obsidian image size, notion image markdown, markdown image html platforms",8,"\u003Cp>Standard Markdown's image syntax — \u003Ccode>![alt](url)\u003C/code> — has no way to control size or alignment. There's no \u003Ccode>width=\u003C/code>, no \u003Ccode>center\u003C/code>, 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 \u003Ccode><img>\u003C/code> tag with \u003Ccode>width\u003C/code>/\u003Ccode>height\u003C/code> attributes, or drop it in a \u003Ccode><div align="center">\u003C/code>. 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.\u003C/p>\n\u003Cp>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 \u003Ca href=\"/blog/markdown-change-image-size\">guide to changing image size in Markdown\u003C/a> and our deeper \u003Ca href=\"/blog/markdown-image-alignment-positioning-complete-guide\">image alignment and positioning guide\u003C/a> 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 \u003Ca href=\"/tools/markdown-image-formatter\">Markdown Image Formatter\u003C/a> does that for you.\u003C/p>\n\u003Ch2 id=\"the-core-technique-inline-html\">The Core Technique: Inline HTML\u003C/h2>\n\u003Cp>The workaround every image-sizing tutorial teaches is the same one:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-html\">\u003Cspan class=\"hljs-tag\"><\u003Cspan class=\"hljs-name\">img\u003C/span> \u003Cspan class=\"hljs-attr\">src\u003C/span>=\u003Cspan class=\"hljs-string\">"diagram.png"\u003C/span> \u003Cspan class=\"hljs-attr\">alt\u003C/span>=\u003Cspan class=\"hljs-string\">"Architecture diagram"\u003C/span> \u003Cspan class=\"hljs-attr\">width\u003C/span>=\u003Cspan class=\"hljs-string\">"500"\u003C/span>>\u003C/span>\n\n\u003Cspan class=\"hljs-tag\"><\u003Cspan class=\"hljs-name\">div\u003C/span> \u003Cspan class=\"hljs-attr\">align\u003C/span>=\u003Cspan class=\"hljs-string\">"center"\u003C/span>>\u003C/span>\n  \u003Cspan class=\"hljs-tag\"><\u003Cspan class=\"hljs-name\">img\u003C/span> \u003Cspan class=\"hljs-attr\">src\u003C/span>=\u003Cspan class=\"hljs-string\">"diagram.png"\u003C/span> \u003Cspan class=\"hljs-attr\">alt\u003C/span>=\u003Cspan class=\"hljs-string\">"Architecture diagram"\u003C/span> \u003Cspan class=\"hljs-attr\">width\u003C/span>=\u003Cspan class=\"hljs-string\">"500"\u003C/span>>\u003C/span>\n\u003Cspan class=\"hljs-tag\"></\u003Cspan class=\"hljs-name\">div\u003C/span>>\u003C/span>\n\u003C/code>\u003C/pre>\u003Cp>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.\u003C/p>\n\u003Ch2 id=\"github-and-gitlab-full-support\">GitHub and GitLab: Full Support\u003C/h2>\n\u003Cp>GitHub and GitLab both parse inline HTML inside Markdown files — READMEs, wiki pages, issues, and pull requests all honor \u003Ccode><img width="...">\u003C/code> and alignment wrappers like \u003Ccode><div align="center">\u003C/code> or \u003Ccode><p align="center">\u003C/code>. 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.\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-html\">\u003Cspan class=\"hljs-tag\"><\u003Cspan class=\"hljs-name\">p\u003C/span> \u003Cspan class=\"hljs-attr\">align\u003C/span>=\u003Cspan class=\"hljs-string\">"center"\u003C/span>>\u003C/span>\n  \u003Cspan class=\"hljs-tag\"><\u003Cspan class=\"hljs-name\">img\u003C/span> \u003Cspan class=\"hljs-attr\">src\u003C/span>=\u003Cspan class=\"hljs-string\">"logo.png"\u003C/span> \u003Cspan class=\"hljs-attr\">alt\u003C/span>=\u003Cspan class=\"hljs-string\">"Project logo"\u003C/span> \u003Cspan class=\"hljs-attr\">width\u003C/span>=\u003Cspan class=\"hljs-string\">"300"\u003C/span>>\u003C/span>\n\u003Cspan class=\"hljs-tag\"></\u003Cspan class=\"hljs-name\">p\u003C/span>>\u003C/span>\n\u003C/code>\u003C/pre>\u003Cp>Both platforms do strip genuinely dangerous content — \u003Ccode><script>\u003C/code> tags and inline event-handler attributes like \u003Ccode>onclick\u003C/code> don't survive — but plain presentational attributes on an \u003Ccode><img>\u003C/code> or a \u003Ccode><div align>\u003C/code> wrapper pass through untouched in both README files and rendered issue/PR comments.\u003C/p>\n\u003Ch2 id=\"notion-strips-html-uses-its-own-block-instead\">Notion: Strips HTML, Uses Its Own Block Instead\u003C/h2>\n\u003Cp>Notion does not render inline HTML in imported or pasted Markdown — as covered in our \u003Ca href=\"/blog/markdown-for-notion-what-actually-works\">Notion companion post\u003C/a>, raw HTML blocks are stripped on import, full stop. An \u003Ccode><img width="300">\u003C/code> tag doesn't get sanitized down to a plain image; it just disappears, or at best leaves behind orphaned text.\u003C/p>\n\u003Cp>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.\u003C/p>\n\u003Ch2 id=\"slack-strips-html-no-sizing-control-at-all\">Slack: Strips HTML, No Sizing Control At All\u003C/h2>\n\u003Cp>Slack's mrkdwn format strips raw HTML entirely, matching what our \u003Ca href=\"/blog/markdown-to-slack-formatting-guide\">Markdown to Slack companion post\u003C/a> 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.\u003C/p>\n\u003Cp>To actually get an image to display in Slack, you need a separate \u003Ccode>image\u003C/code> block in Block Kit (the API for building rich Slack messages), which takes an \u003Ccode>image_url\u003C/code> and \u003Ccode>alt_text\u003C/code> — 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.\u003C/p>\n\u003Ch2 id=\"obsidian-its-own-embed-syntax-not-html\">Obsidian: Its Own Embed Syntax, Not HTML\u003C/h2>\n\u003Cp>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:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">![[diagram.png]]\n![[diagram.png|300]]\n![[diagram.png|300x150]]\n\u003C/code>\u003C/pre>\u003Cp>The double-bracket embed (the same wiki-link syntax Obsidian uses for linking between notes) accepts a pipe-separated width in pixels, or a \u003Ccode>widthxheight\u003C/code> 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 \u003Ccode>![[diagram.png|300]]\u003C/code> 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.\u003C/p>\n\u003Cp>Alignment is a separate story and less standardized: Obsidian's core embed syntax has no built-in center/left/right keyword the way its \u003Ccode>|300\u003C/code> width modifier exists. Centering an embedded image typically means either a CSS snippet targeting \u003Ccode>.markdown-rendered img\u003C/code> in Obsidian's own appearance settings, or a community plugin (several exist specifically for this). Standard \u003Ccode><img>\u003C/code>-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.\u003C/p>\n\u003Ch2 id=\"jekyll-kramdown-mkdocs-and-docusaurus-confirmed-not-assumed\">Jekyll (Kramdown), MkDocs, and Docusaurus: Confirmed, Not Assumed\u003C/h2>\n\u003Cp>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 \u003Ccode><img>\u003C/code>/\u003Ccode><div>\u003C/code> snippets elsewhere on this site's own posts render correctly — so the standard HTML-sizing workaround works here without any special configuration.\u003C/p>\n\u003Cp>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 \u003Ccode><img width="...">\u003C/code> technique works there too.\u003C/p>\n\u003Cp>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 \u003Ccode><img width="300">\u003C/code> 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.\u003C/p>\n\u003Ch2 id=\"confluence-and-jira-neither-html-nor-a-text-syntax\">Confluence and Jira: Neither HTML Nor a Text Syntax\u003C/h2>\n\u003Cp>Confluence is the platform where the HTML workaround fails most completely. Our \u003Ca href=\"/blog/markdown-in-confluence-what-works\">Confluence companion post\u003C/a> already documents that pasting Markdown mixed with HTML gets the HTML stripped or escaped during the paste-conversion step — an \u003Ccode><img width="300">\u003C/code> tag doesn't survive being pasted as part of a Markdown block at all. Confluence does auto-convert a plain \u003Ccode>![alt](url)\u003C/code> 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.\u003C/p>\n\u003Cp>Jira is similar but starts from a different syntax entirely. Jira wiki markup's own image notation is \u003Ccode>!attachment.png!\u003C/code>, with modifiers like \u003Ccode>!attachment.png|thumbnail!\u003C/code> — not Markdown syntax, and not HTML, as our \u003Ca href=\"/blog/markdown-to-jira-wiki-markup-guide\">Jira wiki markup companion post\u003C/a> 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.\u003C/p>\n\u003Ch2 id=\"quick-reference\">Quick Reference\u003C/h2>\n\u003Cdiv class=\"table-responsive\">\u003Ctable class=\"table\">\n\u003Cthead>\n\u003Ctr>\n\u003Cth align=\"left\">Platform\u003C/th>\n\u003Cth align=\"left\">Sizing mechanism\u003C/th>\n\u003Cth align=\"left\">HTML passthrough?\u003C/th>\n\u003C/tr>\n\u003C/thead>\n\u003Ctbody>\u003Ctr>\n\u003Ctd align=\"left\">GitHub / GitLab\u003C/td>\n\u003Ctd align=\"left\">\u003Ccode><img width>\u003C/code> / \u003Ccode><div align>\u003C/code>\u003C/td>\n\u003Ctd align=\"left\">Yes\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd align=\"left\">Notion\u003C/td>\n\u003Ctd align=\"left\">Native image block, drag-resize + alignment toolbar\u003C/td>\n\u003Ctd align=\"left\">No — HTML stripped\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd align=\"left\">Slack\u003C/td>\n\u003Ctd align=\"left\">None via text; separate Block Kit \u003Ccode>image\u003C/code> block (no size param)\u003C/td>\n\u003Ctd align=\"left\">No — HTML stripped\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd align=\"left\">Obsidian\u003C/td>\n\u003Ctd align=\"left\">\u003Ccode>![[file.png|300]]\u003C/code> embed syntax (own convention)\u003C/td>\n\u003Ctd align=\"left\">Yes (but not idiomatic)\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd align=\"left\">Jekyll (kramdown)\u003C/td>\n\u003Ctd align=\"left\">\u003Ccode><img width>\u003C/code> / \u003Ccode><div align>\u003C/code>\u003C/td>\n\u003Ctd align=\"left\">Yes\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd align=\"left\">MkDocs (Python-Markdown)\u003C/td>\n\u003Ctd align=\"left\">\u003Ccode><img width>\u003C/code> / \u003Ccode><div align>\u003C/code>\u003C/td>\n\u003Ctd align=\"left\">Yes\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd align=\"left\">Docusaurus (MDX)\u003C/td>\n\u003Ctd align=\"left\">\u003Ccode><img width>\u003C/code> — parsed as JSX, stricter syntax rules\u003C/td>\n\u003Ctd align=\"left\">Mostly, with caveats\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd align=\"left\">Confluence\u003C/td>\n\u003Ctd align=\"left\">Manual resize via editor after paste/attach\u003C/td>\n\u003Ctd align=\"left\">No — stripped on paste\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd align=\"left\">Jira\u003C/td>\n\u003Ctd align=\"left\">\u003Ccode>!file.png|thumbnail!\u003C/code> modifiers, or manual resize (Cloud editor)\u003C/td>\n\u003Ctd align=\"left\">No\u003C/td>\n\u003C/tr>\n\u003C/tbody>\u003C/table>\u003C/div>\n\u003Ch2 id=\"what-this-means-in-practice\">What This Means in Practice\u003C/h2>\n\u003Cp>If you're writing documentation that lives primarily on GitHub, GitLab, a Jekyll site, or MkDocs, the \u003Ccode><img width>\u003C/code> / \u003Ccode><div align="center">\u003C/code> 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.\u003C/p>\n\u003Cp>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 \u003Ca href=\"/blog/markdown-platform-compatibility-guide\">platform compatibility guide\u003C/a> and our \u003Ca href=\"/blog/why-your-markdown-isnt-rendering\">troubleshooting guide for Markdown that isn't rendering\u003C/a>.\u003C/p>\n\u003Ch2 id=\"related-reading\">Related Reading\u003C/h2>\n\u003Cul>\n\u003Cli>\u003Ca href=\"/blog/markdown-change-image-size\">How to Change Image Size in Markdown\u003C/a>\u003C/li>\n\u003Cli>\u003Ca href=\"/blog/markdown-image-alignment-positioning-complete-guide\">Markdown Image Alignment and Positioning: Complete Guide\u003C/a>\u003C/li>\n\u003Cli>\u003Ca href=\"/blog/markdown-platform-compatibility-guide\">Markdown Across Platforms: What Actually Works\u003C/a>\u003C/li>\n\u003Cli>\u003Ca href=\"/blog/why-your-markdown-isnt-rendering\">Why Your Markdown Isn't Rendering\u003C/a>\u003C/li>\n\u003Cli>\u003Ca href=\"/tools/markdown-image-formatter\">Markdown Image Formatter tool\u003C/a>\u003C/li>\n\u003C/ul>\n",[15,19,22,25,28,31,34,37,40,43],{"id":16,"text":17,"level":18},"the-core-technique-inline-html","The Core Technique: Inline HTML",2,{"id":20,"text":21,"level":18},"github-and-gitlab-full-support","GitHub and GitLab: Full Support",{"id":23,"text":24,"level":18},"notion-strips-html-uses-its-own-block-instead","Notion: Strips HTML, Uses Its Own Block Instead",{"id":26,"text":27,"level":18},"slack-strips-html-no-sizing-control-at-all","Slack: Strips HTML, No Sizing Control At All",{"id":29,"text":30,"level":18},"obsidian-its-own-embed-syntax-not-html","Obsidian: Its Own Embed Syntax, Not HTML",{"id":32,"text":33,"level":18},"jekyll-kramdown-mkdocs-and-docusaurus-confirmed-not-assumed","Jekyll (Kramdown), MkDocs, and Docusaurus: Confirmed, Not Assumed",{"id":35,"text":36,"level":18},"confluence-and-jira-neither-html-nor-a-text-syntax","Confluence and Jira: Neither HTML Nor a Text Syntax",{"id":38,"text":39,"level":18},"quick-reference","Quick Reference",{"id":41,"text":42,"level":18},"what-this-means-in-practice","What This Means in Practice",{"id":44,"text":45,"level":18},"related-reading","Related Reading",[47],"markdown-image-formatter",[49,56,65],{"slug":50,"title":51,"description":52,"excerpt":53,"date":54,"category":9,"author":10,"keywords":55,"readingMinutes":12},"markdown-math-rendering-across-platforms","Markdown Math Rendering Across Platforms: Where LaTeX Actually Works","The $...$ / $$...$$ LaTeX convention for math in Markdown looks identical everywhere, but whether it renders at all — and which engine renders it — varies enormously across GitHub, GitLab, Obsidian, Notion, Jekyll, Hugo, Confluence, and Slack. Here's what's real.","Wrap a formula in dollar signs — $E = mc^2$ — and on some platforms you get a beautifully typeset equation. On others you get the literal text $E = mc^2$ sitting there unrendered, because the…","2026-08-21","markdown math rendering, latex markdown platforms, katex vs mathjax, github math support, notion math equations, jekyll math plugin, hugo katex, confluence math",{"slug":57,"title":58,"description":59,"excerpt":60,"date":61,"category":62,"author":63,"keywords":64,"readingMinutes":12},"markdown-platform-compatibility-guide","Markdown Across Platforms: What Actually Works in GitHub, Notion, Obsidian, and Confluence","A practical Markdown compatibility guide for GitHub, Notion, Obsidian, Confluence, VS Code, and more. Includes a feature comparison table and platform-specific tips.","Markdown is everywhere — but Markdown is not the same everywhere. If you've ever carefully written a document with footnotes, custom HTML, or a nice callout block, only to paste it into a…","2026-04-30","Guide","Matthew Rathbone","markdown compatibility, markdown platforms, github markdown, notion markdown, obsidian markdown, confluence markdown, markdown comparison, markdown features by platform",{"slug":66,"title":67,"description":68,"excerpt":69,"date":70,"category":9,"author":10,"keywords":71,"readingMinutes":12},"markdown-callouts-admonitions-across-platforms","Markdown Callouts and Admonitions Across Platforms: What Actually Renders","GitHub's > [!NOTE] alert syntax, Obsidian's callouts, and MkDocs's admonition extension all look like variations on a theme — but they're three genuinely different syntaxes that mostly don't cross-render. Here's what works where.","Type > [!NOTE] into a Markdown file and on GitHub you get a styled, icon-prefixed callout box. Paste that exact same text into a plain CommonMark renderer, a Jekyll site with no plugin, or an…","2026-08-28","markdown callouts, github alerts, obsidian callouts, mkdocs admonitions, docusaurus admonitions, markdown warning box across platforms",1792184947052]