[{"data":1,"prerenderedAt":66},["Reactive",2],{"blog-post-markdown-callouts-admonitions-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":37,"related":39},"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","workflows","Matt Rathbone","markdown callouts, github alerts, obsidian callouts, mkdocs admonitions, docusaurus admonitions, markdown warning box across platforms",8,"\u003Cp>Type \u003Ccode>> [!NOTE]\u003C/code> 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 old-school static blog, and you get an ordinary blockquote with the literal text \u003Ccode>[!NOTE]\u003C/code> sitting inside it. This trips people up constantly, because GitHub's alert syntax is popular enough — and looks native enough — that it's easy to assume it's part of Markdown itself. It isn't. It's a GitHub- and GitLab-specific extension, and it's just one of at least three unrelated callout syntaxes in active use depending on which platform or static site generator you're targeting.\u003C/p>\n\u003Cp>This guide covers what each syntax actually looks like, which platforms understand it natively, which need a plugin or config change, and — the part most syntax tutorials skip — what happens when you paste one platform's syntax into a renderer that doesn't understand it. If you want the full syntax reference and platform-by-platform examples first, our \u003Ca href=\"/blog/markdown-admonitions-callouts-complete-guide\">complete guide to admonitions and callouts\u003C/a> and our narrower \u003Ca href=\"/blog/add-a-warning-box-alert-in-markdown\">guide to warning boxes and alerts\u003C/a> cover that ground; this post assumes you already know the basic syntax and focuses on where it actually renders. And if you just want to generate correctly-formatted callout syntax for your specific target platform without memorizing four different formats, our new \u003Ca href=\"/tools/markdown-callouts\">Markdown Callout Generator\u003C/a> does that.\u003C/p>\n\u003Ch2 id=\"github-and-gitlab-alerts-native-but-not-commonmark\">GitHub and GitLab Alerts: Native, But Not CommonMark\u003C/h2>\n\u003Cp>GitHub's alert syntax — a blockquote whose first line is one of five fixed keywords in brackets — is the one most people encounter first:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">\u003Cspan class=\"hljs-quote\">> [!NOTE]\u003C/span>\n\u003Cspan class=\"hljs-quote\">> Useful information that users should know, even when skimming.\u003C/span>\n\n\u003Cspan class=\"hljs-quote\">> [!TIP]\u003C/span>\n\u003Cspan class=\"hljs-quote\">> Helpful advice for doing things better or more easily.\u003C/span>\n\n\u003Cspan class=\"hljs-quote\">> [!IMPORTANT]\u003C/span>\n\u003Cspan class=\"hljs-quote\">> Key information users need to know to achieve their goal.\u003C/span>\n\n\u003Cspan class=\"hljs-quote\">> [!WARNING]\u003C/span>\n\u003Cspan class=\"hljs-quote\">> Urgent info that needs immediate attention to avoid problems.\u003C/span>\n\n\u003Cspan class=\"hljs-quote\">> [!CAUTION]\u003C/span>\n\u003Cspan class=\"hljs-quote\">> Advises about risks or negative outcomes of certain actions.\u003C/span>\n\u003C/code>\u003C/pre>\u003Cp>Those exact five types — no more, no fewer — are the only ones GitHub's renderer recognizes. Typing \u003Ccode>> [!DANGER]\u003C/code> or \u003Ccode>> [!INFO]\u003C/code> doesn't error, it just falls back to being an ordinary blockquote with literal bracket text, because those aren't in GitHub's fixed vocabulary. GitLab adopted the identical syntax and the same five types, so anything written for one generally displays correctly on the other.\u003C/p>\n\u003Cp>The important gotcha: this is a renderer-level feature, not a Markdown-spec feature. It works in READMEs, issues, PRs, wikis, and discussions on github.com and gitlab.com specifically, because those two platforms' own Markdown renderers added special-case handling for the \u003Ccode>[!KEYWORD]\u003C/code> pattern inside a blockquote. Take that same text to a plain CommonMark or GFM-spec-only renderer, a Jekyll/kramdown site with no custom handling, an email client, or a PDF exporter, and you get a plain blockquote containing the literal string \u003Ccode>[!NOTE]\u003C/code> — no styling, no icon, no color. It's still readable, just not what you intended.\u003C/p>\n\u003Ch2 id=\"obsidian-callouts-a-similar-look-a-different-larger-vocabulary\">Obsidian Callouts: A Similar Look, a Different (Larger) Vocabulary\u003C/h2>\n\u003Cp>Obsidian's callout syntax is close enough to GitHub's to cause real confusion, but it's a separate implementation with its own, much larger type vocabulary and an extra feature GitHub's alerts don't have at all:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">\u003Cspan class=\"hljs-quote\">> [!note] Project Setup\u003C/span>\n\u003Cspan class=\"hljs-quote\">> Follow these steps to configure your environment.\u003C/span>\n\n\u003Cspan class=\"hljs-quote\">> [!warning] Version Compatibility\u003C/span>\n\u003Cspan class=\"hljs-quote\">> This plugin requires Obsidian 0.15.0 or higher.\u003C/span>\n\n\u003Cspan class=\"hljs-quote\">> [!tip]- Collapsible Tip\u003C/span>\n\u003Cspan class=\"hljs-quote\">> The minus sign after the type makes this foldable, closed by default.\u003C/span>\n\u003Cspan class=\"hljs-quote\">> A plus sign instead makes it foldable, but open by default.\u003C/span>\n\u003C/code>\u003C/pre>\u003Cp>Obsidian recognizes over a dozen built-in types (\u003Ccode>note\u003C/code>, \u003Ccode>abstract\u003C/code>/\u003Ccode>summary\u003C/code>, \u003Ccode>info\u003C/code>, \u003Ccode>todo\u003C/code>, \u003Ccode>tip\u003C/code>/\u003Ccode>hint\u003C/code>, \u003Ccode>success\u003C/code>/\u003Ccode>check\u003C/code>, \u003Ccode>question\u003C/code>, \u003Ccode>warning\u003C/code>/\u003Ccode>caution\u003C/code>, \u003Ccode>failure\u003C/code>/\u003Ccode>fail\u003C/code>, \u003Ccode>danger\u003C/code>/\u003Ccode>error\u003C/code>, \u003Ccode>bug\u003C/code>, \u003Ccode>example\u003C/code>, \u003Ccode>quote\u003C/code>), several of which are simply aliases for each other, plus a fold indicator (\u003Ccode>-\u003C/code>/\u003Ccode>+\u003C/code> right after the closing bracket) that GitHub's syntax has no equivalent for at all. Obsidian is also case-insensitive on the type keyword and lets you supply a custom title after it — \u003Ccode>[!warning] Version Compatibility\u003C/code> — where GitHub's alerts always use the fixed keyword itself as the visible title with no override.\u003C/p>\n\u003Cp>Because the outer shape (\u003Ccode>> [!type]\u003C/code>) looks so similar to GitHub's, it's easy to assume the two are interchangeable. They're not: paste \u003Ccode>[!tip]-\u003C/code> into GitHub and you get a plain blockquote reading "[!tip]- Collapsible Tip" with no folding behavior, because GitHub's renderer only pattern-matches its own five fixed keywords and has no concept of the fold suffix. Paste \u003Ccode>[!IMPORTANT]\u003C/code> into Obsidian and it renders as a plain, unstyled callout box with no icon, because \u003Ccode>important\u003C/code> isn't one of Obsidian's built-in types (Obsidian falls back to a generic default box rather than an ordinary blockquote, but it's still not the styled result you'd get on GitHub).\u003C/p>\n\u003Ch2 id=\"mkdocs-a-real-extension-config-required-indentation-sensitive\">MkDocs: A Real Extension, Config Required, Indentation-Sensitive\u003C/h2>\n\u003Cp>MkDocs (via Python-Markdown's \u003Ccode>admonition\u003C/code> extension, or the more capable \u003Ccode>pymdownx.details\u003C/code> for foldable versions) uses a completely different syntax shape — no blockquote \u003Ccode>>\u003C/code> at all:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">!!! note "Configuration Requirements"\n\u003Cspan class=\"hljs-code\">    This feature requires Python 3.8+ and the following dependencies.\n\u003C/span>\n??? tip "Click to expand"\n\u003Cspan class=\"hljs-code\">    Using `???` instead of `!!!` makes the block collapsible, closed by default.\n    `???+` makes it collapsible but open by default.\u003C/span>\n\u003C/code>\u003C/pre>\u003Cp>Three things make this meaningfully different from the blockquote-based syntaxes above. First, it does nothing at all unless you've explicitly enabled it — add \u003Ccode>admonition\u003C/code> (and \u003Ccode>pymdownx.details\u003C/code> if you want the foldable \u003Ccode>???\u003C/code> variant) under \u003Ccode>markdown_extensions:\u003C/code> in \u003Ccode>mkdocs.yml\u003C/code>. Without that config line, \u003Ccode>!!! note\u003C/code> renders as a literal paragraph starting with three exclamation marks; there's no fallback styling of any kind. Second, the content that belongs inside the block must be indented four spaces under the \u003Ccode>!!!\u003C/code>/\u003Ccode>???\u003C/code> line — get the indentation wrong and Python-Markdown simply doesn't associate that paragraph with the admonition, silently dropping it back to being a regular, un-boxed paragraph directly below an empty admonition. Third, the type vocabulary is open-ended rather than fixed: \u003Ccode>!!! note\u003C/code>, \u003Ccode>!!! danger\u003C/code>, \u003Ccode>!!! example\u003C/code>, or any custom type name you've styled via CSS all work, since the extension doesn't validate against a fixed keyword list the way GitHub's alerts do.\u003C/p>\n\u003Cp>None of GitHub's, GitLab's, or Obsidian's blockquote-based syntax does anything special in MkDocs — a pasted \u003Ccode>> [!NOTE]\u003C/code> block just renders as a plain, unstyled blockquote with visible bracket text, exactly like taking GitHub syntax to any other non-GitHub renderer.\u003C/p>\n\u003Ch2 id=\"docusaurus-a-third-shape-entirely--fenced-directives\">Docusaurus: A Third Shape Entirely — Fenced Directives\u003C/h2>\n\u003Cp>Docusaurus (and MDX-based tooling more broadly) uses yet another format, based on triple-colon fenced directives rather than either blockquotes or indented blocks:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">:::note\nUseful information that users should know.\n:::\n\n:::tip[Optional Custom Title]\nHelpful advice, with an optional title in square brackets.\n:::\n\n:::danger\nHighlights dangerous actions or negative outcomes.\n:::\n\u003C/code>\u003C/pre>\u003Cp>Docusaurus supports five built-in types (\u003Ccode>note\u003C/code>, \u003Ccode>tip\u003C/code>, \u003Ccode>info\u003C/code>, \u003Ccode>warning\u003C/code>, \u003Ccode>danger\u003C/code>) and works out of the box with no plugin config, since the directive syntax is built into Docusaurus's MDX processing pipeline directly. The syntax shape — a fence of three colons opening and closing the block, with the type name immediately after the opening fence — has nothing in common with GitHub's blockquote convention or MkDocs's indented-content convention, so none of those interoperate with this one either. Paste \u003Ccode>:::note\u003C/code> content into GitHub or a plain CommonMark renderer and you get exactly what it looks like: a paragraph starting and ending with three literal colons, no box, no styling.\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>Platform\u003C/th>\n\u003Cth>Syntax shape\u003C/th>\n\u003Cth>Native or needs config\u003C/th>\n\u003Cth>Fold/collapse support\u003C/th>\n\u003C/tr>\n\u003C/thead>\n\u003Ctbody>\u003Ctr>\n\u003Ctd>\u003Cstrong>GitHub\u003C/strong>\u003C/td>\n\u003Ctd>\u003Ccode>> [!TYPE]\u003C/code> blockquote, 5 fixed types\u003C/td>\n\u003Ctd>Native, no config\u003C/td>\n\u003Ctd>No\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>GitLab\u003C/strong>\u003C/td>\n\u003Ctd>\u003Ccode>> [!TYPE]\u003C/code> blockquote, same 5 types as GitHub\u003C/td>\n\u003Ctd>Native, no config\u003C/td>\n\u003Ctd>No\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Obsidian\u003C/strong>\u003C/td>\n\u003Ctd>\u003Ccode>> [!type]\u003C/code> blockquote, 12+ types, custom titles\u003C/td>\n\u003Ctd>Native, no config\u003C/td>\n\u003Ctd>Yes — \u003Ccode>[!type]-\u003C/code> / \u003Ccode>[!type]+\u003C/code>\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>MkDocs (Material or base theme)\u003C/strong>\u003C/td>\n\u003Ctd>\u003Ccode>!!! type "Title"\u003C/code>, 4-space indented content\u003C/td>\n\u003Ctd>Needs \u003Ccode>admonition\u003C/code> extension enabled in \u003Ccode>mkdocs.yml\u003C/code>\u003C/td>\n\u003Ctd>Yes, with \u003Ccode>pymdownx.details\u003C/code> — \u003Ccode>???\u003C/code>/\u003Ccode>???+\u003C/code>\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Docusaurus\u003C/strong>\u003C/td>\n\u003Ctd>\u003Ccode>:::type\u003C/code> ... \u003Ccode>:::\u003C/code> fenced directive\u003C/td>\n\u003Ctd>Native (built into MDX pipeline)\u003C/td>\n\u003Ctd>No (use a separate \u003Ccode><details>\u003C/code> for that)\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Sphinx / reStructuredText\u003C/strong>\u003C/td>\n\u003Ctd>\u003Ccode>.. type::\u003C/code> directive (not Markdown at all)\u003C/td>\n\u003Ctd>Native to RST\u003C/td>\n\u003Ctd>No\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Plain CommonMark / unconfigured static sites\u003C/strong>\u003C/td>\n\u003Ctd>N/A\u003C/td>\n\u003Ctd>None of the above render specially — all fall back to a plain blockquote or paragraph with literal syntax visible\u003C/td>\n\u003Ctd>N/A\u003C/td>\n\u003C/tr>\n\u003C/tbody>\u003C/table>\u003C/div>\n\u003Ch2 id=\"what-doesnt-cross-render-concretely\">What Doesn't Cross-Render, Concretely\u003C/h2>\n\u003Cp>The pattern across every combination above is the same: \u003Cstrong>each platform's callout syntax is invisible to every other platform's renderer\u003C/strong>, and none of them error — they all degrade to plain, unstyled Markdown with the literal syntax characters left visible in the text. Concretely:\u003C/p>\n\u003Cul>\n\u003Cli>GitHub-alert syntax (\u003Ccode>> [!NOTE]\u003C/code>) pasted into a MkDocs site does \u003Cstrong>not\u003C/strong> become a styled admonition — MkDocs's \u003Ccode>admonition\u003C/code> extension has no idea what a \u003Ccode>[!NOTE]\u003C/code> blockquote is, so it renders as an ordinary blockquote with visible bracket text.\u003C/li>\n\u003Cli>MkDocs syntax (\u003Ccode>!!! note\u003C/code>) pasted into GitHub does \u003Cstrong>not\u003C/strong> become a callout — GitHub's renderer only pattern-matches its own five bracketed keywords inside blockquotes, and \u003Ccode>!!! note\u003C/code> isn't even inside a blockquote to begin with, so it just renders as a plain paragraph starting with \u003Ccode>!!!\u003C/code>.\u003C/li>\n\u003Cli>Docusaurus's \u003Ccode>:::note\u003C/code> fences pasted anywhere else — GitHub, Obsidian, MkDocs, plain Jekyll — render as plain text with visible colons, since the triple-colon-fence convention is specific to Docusaurus's MDX processing.\u003C/li>\n\u003Cli>Obsidian's extended type vocabulary (\u003Ccode>[!bug]\u003C/code>, \u003Ccode>[!question]\u003C/code>, \u003Ccode>[!abstract]\u003C/code>) pasted into GitHub renders as an unstyled blockquote, since those types fall outside GitHub's fixed five.\u003C/li>\n\u003C/ul>\n\u003Cp>If you're writing documentation that has to look right on more than one of these platforms — a README that also gets built into a MkDocs or Docusaurus site, for instance — plain HTML \u003Ccode><div class="admonition">\u003C/code> markup (styled with your own CSS) is still the only genuinely universal fallback, at the cost of losing GitHub's and Obsidian's zero-config native styling. There's no single syntax that renders correctly everywhere; you're choosing per target platform, not writing once.\u003C/p>\n\u003Ch2 id=\"related-reading\">Related Reading\u003C/h2>\n\u003Cul>\n\u003Cli>\u003Ca href=\"/blog/markdown-admonitions-callouts-complete-guide\">Markdown Admonitions and Callouts: Complete Guide\u003C/a> — the fuller syntax reference and platform examples this post assumes as background\u003C/li>\n\u003Cli>\u003Ca href=\"/blog/add-a-warning-box-alert-in-markdown\">How to Create a Warning Box Alert in Markdown\u003C/a> — the narrower blockquote-vs-HTML warning box case specifically\u003C/li>\n\u003Cli>\u003Ca href=\"/blog/markdown-platform-compatibility-guide\">Markdown Across Platforms: What Actually Works in GitHub, Notion, Obsidian, and Confluence\u003C/a> — the broader platform-compatibility picture beyond callouts\u003C/li>\n\u003Cli>\u003Ca href=\"/blog/why-your-markdown-isnt-rendering\">Why Your Markdown Isn't Rendering: A Troubleshooting Guide\u003C/a> — if a callout you pasted somewhere shows up as a plain blockquote instead of a styled box\u003C/li>\n\u003C/ul>\n\u003Cp>And if you'd rather generate the correct syntax for your target platform than memorize four different formats, try the \u003Ca href=\"/tools/markdown-callouts\">Markdown Callout Generator\u003C/a>.\u003C/p>\n",[15,19,22,25,28,31,34],{"id":16,"text":17,"level":18},"github-and-gitlab-alerts-native-but-not-commonmark","GitHub and GitLab Alerts: Native, But Not CommonMark",2,{"id":20,"text":21,"level":18},"obsidian-callouts-a-similar-look-a-different-larger-vocabulary","Obsidian Callouts: A Similar Look, a Different (Larger) Vocabulary",{"id":23,"text":24,"level":18},"mkdocs-a-real-extension-config-required-indentation-sensitive","MkDocs: A Real Extension, Config Required, Indentation-Sensitive",{"id":26,"text":27,"level":18},"docusaurus-a-third-shape-entirely--fenced-directives","Docusaurus: A Third Shape Entirely — Fenced Directives",{"id":29,"text":30,"level":18},"quick-reference","Quick Reference",{"id":32,"text":33,"level":18},"what-doesnt-cross-render-concretely","What Doesn't Cross-Render, Concretely",{"id":35,"text":36,"level":18},"related-reading","Related Reading",[38],"markdown-callouts",[40,50,59],{"slug":41,"title":42,"description":43,"excerpt":44,"date":45,"category":46,"author":47,"keywords":48,"readingMinutes":49},"markdown-admonitions-callouts-complete-guide","Markdown Admonitions and Callouts: Complete Guide for Enhanced Documentation","Master admonitions, callouts, and alert boxes in Markdown for creating engaging documentation with warnings, tips, notes, and information blocks across different platforms.","Admonitions and callouts are essential components of modern technical documentation, transforming plain text into visually engaging, structured content that guides readers through complex…","2025-08-25","Tutorial","Matthew Rathbone","markdown admonitions, markdown callouts, markdown alerts, markdown warning boxes, markdown note boxes, documentation blocks, markdown tips",14,{"slug":51,"title":52,"description":53,"excerpt":54,"date":55,"category":56,"author":47,"keywords":57,"readingMinutes":58},"markdown-footnotes-across-platforms","Markdown Footnotes Across Platforms: Where They Actually Render","GitHub, GitLab, Obsidian, and this very blog render [^1] footnotes natively — Notion, Slack, Jira, and Confluence don't support them at all. A platform-by-platform reference for where footnote syntax actually works.","Footnote syntax — a reference marker like [^1] in the body text, paired with a definition [^1]: The actual note. elsewhere in the document — looks the same everywhere you write it. Whether it…","2026-09-25","Reference","markdown footnotes across platforms, github footnotes, gitlab footnotes, notion footnotes, obsidian footnotes support",5,{"slug":60,"title":61,"description":62,"excerpt":63,"date":64,"category":9,"author":10,"keywords":65,"readingMinutes":12},"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","markdown image size, markdown image alignment, resize image markdown, center image markdown, obsidian image size, notion image markdown, markdown image html platforms",1792184947046]