Markdown Tools Blog

How to Remove Markdown Formatting from ChatGPT and Claude Output

2026-10-02T00:00:00+00:00

You ask an AI assistant for a summary, paste it into an email or a form field, and the result is littered with ** pairs, ## prefixes and [text](https://...) links. Nothing is broken. The assistant wrote Markdown, the chat window rendered it nicely, and your destination simply doesn't speak Markdown.

This post covers why that happens, three ways to get clean text out, and the cases where you should keep some formatting instead of stripping everything.

Why AI output is full of Markdown

Chat assistants are trained and prompted to format answers with Markdown, because the chat interface renders it: bold for emphasis, # for headings, - for lists, backticks for code. What you see in the window is the rendered result. What you often get on your clipboard depends on how you copy:

A copy button on the message typically copies the underlying Markdown source, asterisks and all. This is exactly what you want when pasting into GitHub or Notion, and exactly what you don't want in an email.
Selecting rendered text with the mouse usually copies rich text (real bold, real bullets). Destinations that accept rich text, such as Google Docs, Word and most email composers, keep the formatting. Destinations that only accept plain text drop the styling and keep whatever characters came along.

Which one you get varies by product and changes over time, so don't rely on either. The reliable fix is to decide what you want the destination to receive and convert on purpose.

Option 1: Ask for plain text up front

The cheapest fix is a one-line instruction: "Reply in plain text only, no Markdown formatting." Most assistants follow it, and it works well for short answers.

It's less dependable when you've already got a long answer you like, when the model drifts back to Markdown several messages into a conversation, or when you're stripping a document you didn't generate yourself (a README, exported notes, a wiki page). It also costs you a re-run for every answer you've already received.

Option 2: Strip it with a converter

Pasting the Markdown into a converter and copying the clean result is the dependable approach, and it works on any Markdown, not just AI output. Our Markdown to Plain Text tool runs entirely in your browser and parses the text as real Markdown instead of deleting characters blindly, which matters in a few cases:

Nested formatting. **bold with _italic_ inside** should become the words, not a half-stripped mess.
Lists. Bullets become • characters (or are removed, if you prefer), numbered items keep their numbers, and nested items stay indented.
Links. By default you get just the link text. Tick "Keep link URLs" and each link becomes text (url), which is usually what you want in an email where the reader can't click.
Tables. Markdown tables can't survive in plain text, so each row becomes a line with tab-separated cells. That pastes straight into a spreadsheet.
Code. Fences and backticks go away; the code text stays (or you can drop code blocks entirely).

Option 3: Do it yourself with a regex (and why it breaks)

A common shortcut is a handful of search-and-replace patterns:

**text**  ->  text
# Title   ->  Title
[a](b)    ->  a

That handles the easy 80%, then fails in predictable ways:

A literal asterisk in prose (5 * 3, a footnote star) gets eaten as if it were emphasis.
Underscores inside identifiers (snake_case_name) get mistaken for italics.
Nested emphasis and links inside list items need ordering tricks that are easy to get wrong.
Code blocks should be exempt from every rule, but a naive pass strips inside them too.

If you only strip occasionally, a parser-based tool saves the debugging. If you're scripting it, use a real Markdown parser and walk its output rather than layering patterns.

When you should not strip everything

Plain text deletes meaning along with the markup. Before stripping, check whether the destination actually has a better option:

Destination	Better approach
Slack	Convert to Slack's own syntax with the Markdown to Slack tool. Bold and links survive. See our Slack formatting guide.
Word or Google Docs	Convert to a real document with Markdown to Word, keeping headings and tables.
Email newsletter	Produce inline-styled HTML with Markdown to Email HTML. See the email HTML guide.
Notion, Jira, Confluence	These have their own import paths; see Notion and Jira.
Plain-text field, SMS, form, CMS that shows raw text	Strip it. This is the right case for the plain text tool.

What gets lost

Be aware of what plain text cannot carry: emphasis (bold and italic are gone by definition), heading hierarchy (a heading becomes an ordinary line, so add your own spacing or capitalization if the structure matters), and anything that needed rendering, such as Mermaid diagrams, math and footnotes. Those pass through as their source text. If your content leans on them, see how footnotes and diagrams behave across platforms.

Quick checklist

Know where the text is going. Rich-text target: copy rendered text. Markdown-aware target: paste the source. Plain-text-only target: strip.
For one-off answers, ask the assistant for plain text first.
For everything else, run it through a parser-based converter and decide on link URLs and bullets.
Skim the output once. Stripped lists and tables are the places most likely to need a manual touch.

Markdown Footnotes Across Platforms: Where They Actually Render

2026-09-25T00:00:00+00:00

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 renders as anything at all is a different question entirely, and the answer splits sharply by platform: some render real, clickable, jump-linked footnotes with zero configuration; others don't understand the syntax at all and will show you the literal brackets and carets. This is a reference for which is which, checked against real output rather than assumed from a spec.

If you haven't used footnote syntax before, our footnotes in Markdown guide covers the basic syntax first. If you're doing heavier academic-style citation work, see our citations and references guide. This post is specifically about the one thing those guides don't fully settle: does your renderer actually turn [^1] into a footnote, or not.

Native support, no configuration needed

GitHub added real footnote rendering in September 2021 — this is worth calling out explicitly, because plenty of older Markdown content (including, until this post, our own footnotes guide) still says GitHub doesn't support them, which was true before that date and isn't anymore. Today, [^1] in an issue, pull request, wiki page, or repository file renders as a real superscript link that jumps to a numbered footnotes section at the bottom, with a back-link to return to your place. It works the same way in Markdown files rendered on GitHub Pages.

GitLab renders footnotes the same way, and has for longer than GitHub — GitLab Flavored Markdown has included footnote support across issues, merge requests, and wiki pages for several major versions now.

Obsidian supports the same reference-and-definition syntax, plus its own shorthand: ^[an inline footnote written right here] creates a footnote without a separate definition elsewhere in the document at all. Both forms render as a small superscript number that shows the note content in a popover on hover or click, without navigating away from your place in the document.

This blog — and any Jekyll site using kramdown, which is Jekyll's default Markdown processor — renders footnotes natively too. We checked this directly against kramdown's actual output rather than assuming it from the spec: [^1] produces a real <sup>-wrapped jump link, and the definition becomes a proper <ol> entry with a reverse-footnote back-link, identical in shape to GitHub's rendering. No plugin, no configuration flag — kramdown just handles it, which is presumably part of why footnote syntax proliferated on GitHub-adjacent sites in the first place.

Needs configuration — off by default

MkDocs, using the standard Python-Markdown processor, does not render footnotes out of the box. You need to explicitly enable the footnotes extension in mkdocs.yml:

markdown_extensions:
  - footnotes

Without it, [^1] and [^1]: text just print as literal characters — there's no error, no warning, just plain text where you expected a footnote. If a MkDocs site you're working on shows raw footnote syntax instead of rendered notes, this is almost always why.

Docusaurus, built on MDX, needs a comparable opt-in. Recent Docusaurus versions ship with GFM support (via remark-gfm) enabled in the default preset, which includes footnote parsing — but if you're on an older config, a custom MDX pipeline, or you've deliberately swapped remark plugins, footnotes can silently stop working the same way they would on MkDocs without its extension. Worth a quick test render before you rely on them in a Docusaurus-based doc site, the same advice this blog's MkDocs vs. Docusaurus vs. GitBook guide already gives for other GFM-adjacent features.

No support at all

Notion doesn't recognize footnote syntax on import or paste — [^1] and its definition just come through as literal text sitting wherever they land, with no connection drawn between them. Our own Notion companion guide covers this as one of the format's known casualties, and it's also why the Markdown to Notion tool takes the deliberate step of inlining footnote text next to its reference before conversion — Notion never runs a footnotes step of its own, so if nobody flattens them first, they're just lost.

Slack has no footnote handling anywhere in its formatting — not in the message composer, not via mrkdwn sent through the API, not in Block Kit. Same story in Jira and Confluence wiki markup: no equivalent syntax exists in either, native or otherwise. The practical workaround in all three, and what each platform's companion guide on this blog recommends, is a plain parenthetical aside inline instead of a real footnote — there's no rendering feature to fall back on.

Microsoft Word and HTML email don't fare any better once you're converting into them from Markdown, for a related but distinct reason: it's not that Word or email clients can't display footnotes (Word obviously has real native footnote support) — it's that the client-side Markdown parsers doing the conversion (used by tools like our own Markdown to Word and Markdown to Email HTML converters) don't implement the footnote extension, so [^1] passes through as literal bracket-and-caret text in the output rather than becoming a real Word footnote or an email-safe substitute.

Quick reference

Platform	Footnotes render?	Notes
GitHub	Yes, natively	Since September 2021
GitLab	Yes, natively	Longer-standing support than GitHub's
Obsidian	Yes, natively	Also supports inline `^[...]` shorthand
Jekyll (kramdown)	Yes, natively	Verified directly against kramdown's own output
MkDocs	Needs config	Enable the `footnotes` extension in `mkdocs.yml`
Docusaurus	Usually, via GFM	Confirm your remark/MDX config includes it
Notion	No	Text passes through unlinked; import tools inline it instead
Slack	No	No equivalent in mrkdwn or Block Kit
Jira / Confluence	No	No wiki-markup equivalent in either
Word / Email HTML	No (via conversion)	The converting parser doesn't expand the syntax

Cleaning up messy footnotes before you publish

None of the above matters much if your footnote numbering has drifted — which happens the moment you add, remove, or reorder a footnote in an existing document, since every reference and definition after that point needs updating in lockstep by hand. Our Footnote Organizer renumbers every footnote sequentially by the order it's first referenced (not the order its definition happens to be written), collects all the definitions at the document's end, and flags anything it can't safely fix on its own — a reference with no matching definition, or a definition nobody ever referenced — rather than silently guessing.

How to Use Footnotes in Markdown — the basic syntax
Markdown Citations and References — academic citation styles and bibliography tools
Markdown Platform Compatibility Guide — the broader picture beyond just footnotes
Why Your Markdown Isn't Rendering — troubleshooting other silent syntax failures

Markdown Comments Across Platforms: Hidden, Stripped, or Still Sitting in Your HTML?

2026-09-18T00:00:00+00:00

If you've read our guide to adding comments in Markdown, you already know the syntax: wrap text in  and it won't show up in the rendered output. That part is simple and it's the same everywhere.

What isn't the same everywhere is what "won't show up" actually means. On some platforms, an HTML comment is truly deleted before the page is ever generated — it never exists in the shipped output at all. On others, it's just told not to display, while the literal text sits right there in the page's HTML source, visible to anyone who right-clicks and chooses "View Page Source." And on a few platforms, the comment doesn't get hidden at all — it gets stripped so aggressively that the whole thing, syntax and content, just vanishes on import.

Those are three genuinely different outcomes, and mixing them up is how internal notes end up leaking, or how a "hidden" TODO turns into a paragraph of literal <!-- characters on a live page. This guide walks through what actually happens, platform by platform.

The distinction that matters: removed vs. hidden

Before the platform tour, it's worth naming the core difference explicitly, because it's the thing most comment tutorials skip.

Removed at build time means the comment's content never makes it into the file that gets served to a browser. If you view the page source, it's simply not there. This is what you want for anything you'd be embarrassed to have a curious visitor stumble across — draft pricing, internal reviewer names, "don't publish this until legal signs off," that kind of thing.

Hidden at render time means the comment's content is in the HTML that gets served — it's just wrapped in , which browsers know not to display. A regular visitor won't see it in the rendered page. Anyone who opens dev tools or view-source will see it immediately, in plain text.

Standard HTML comments () are almost always the second kind, not the first. That's true no matter what Markdown processor you're using, because Markdown itself doesn't do anything special with HTML comments — it passes them through untouched, and it's the browser, not Markdown, that decides not to render them visually. The confusion comes from platforms that layer a build system on top of Markdown, because some of those build systems have their own, separate comment syntax that behaves differently. More on that below.

Platform-by-platform behavior

GitHub — repo files vs. Issues/PRs

In a rendered file (a README, a wiki page, anything under a repo's Markdown rendering), HTML comments are hidden-not-removed: view the raw file (?raw=true or the "Raw" button) and the comment text is right there. This is expected and fine for a public repo, since anyone can already read your whole file's raw source anyway — there's no secret being kept from anyone.

Issues and pull requests behave the same way but get used differently in practice: GitHub's own issue and PR templates use HTML comments as instructional placeholder text (). Once submitted, that instructional text is hidden in the rendered comment, exactly as designed — but it's still sitting in the issue body's raw Markdown, retrievable via the API or an "Edit" click. Don't put anything in a PR template comment you wouldn't want a bot or a scraper reading back to you later.

GitLab

Functionally identical to GitHub for both files and merge request descriptions — HTML comments hide in rendered view, remain fully present in the raw Markdown. GitLab also uses the same instructional-placeholder-comment pattern in its default MR templates.

npm and PyPI package pages

Both npmjs.com and pypi.org render your README.md for the package listing page using largely the same rendering assumptions as GitHub. HTML comments are hidden from the rendered listing but present in the page's HTML source — worth remembering if your README's HTML comments contain anything like internal build notes or unpublished feature flags.

Jekyll (this site's own engine) — and why it's a special case

This is where the removed-vs-hidden distinction stops being theoretical, because Jekyll gives you both options, and they're not interchangeable.

A plain HTML comment in a Jekyll post behaves like everywhere else — hidden from the rendered page, present in the shipped HTML:

<!-- This survives the build and sits in the final HTML, just invisible -->

But Jekyll's Liquid templating layer also has its own comment tag, and it works completely differently:

{% comment %}
This text is deleted during the build. It never appears
anywhere in the generated _site output, not even in the source.
{% endcomment %}

{% comment %}...{% endcomment %} content is stripped by Jekyll itself, before the HTML is ever written to disk. That's the actual "removed at build time" behavior — genuinely useful for author-only notes you don't want in your Git-hosted output at all, as opposed to notes you're fine with a curious reader finding in view-source.

The catch: {% comment %} only works in files Jekyll actually processes through Liquid (posts and pages with front matter). It does nothing useful inside a fenced code block meant to display Liquid syntax as an example — in fact, unescaped {% %} or {{ }} inside a code sample is exactly the class of bug we've written about in our own troubleshooting guide, where Jekyll tries to execute what you meant as illustrative text.

Hugo

Hugo has the same two-tier structure as Jekyll, just with different names. Plain HTML comments behave like everywhere else: hidden, not removed. Hugo templates additionally support Go template comments ({{/* like this */}}) for .html layout files, which are stripped at build time — but that syntax is a layout-file feature, not something you write inside your Markdown content itself. If you're commenting inside a Markdown post body on a Hugo site, you're almost always using the plain HTML form, which means: hidden, not removed.

MkDocs, Docusaurus, and other static-site generators

These follow the same general rule as Jekyll and Hugo's content layer: they pass HTML comments through to the rendered HTML untouched. The comment is hidden visually but present in source. Docusaurus (React/MDX-based) is worth a specific flag: because MDX treats { as the start of a JavaScript expression, curly-brace syntax in prose can trigger build errors in ways plain Jekyll/Hugo content doesn't — a separate gotcha from the comment-visibility question, but one that trips up the same audience.

Confluence

Confluence doesn't render Markdown to HTML the way the platforms above do — it converts to its own storage format, and as our Confluence guide documents, raw HTML gets stripped or escaped on import rather than preserved. In practice, that means an HTML comment pasted into Confluence's /markdown panel usually doesn't survive as a hidden comment at all — it's either dropped entirely or shows up as literal, visible <!-- text, depending on the import path. If you need a genuinely hidden internal note in Confluence, use a real Confluence feature built for it (an inline comment, or the {noformat}/expand macros) rather than relying on Markdown syntax that the platform was never built to honor.

Notion

Notion strips raw HTML entirely on import, and that includes comment syntax — it's not a "hidden but present" situation, it's a "gone" situation, per our Notion compatibility guide. If you need a genuinely invisible internal note inside a Notion page, Notion's own commenting feature (select text, add a comment) is the tool for that job, not an HTML comment carried over from a Markdown file.

Obsidian

Obsidian is the one platform on this list where "hidden vs. removed" barely applies, because there's no build/publish step by default — you're just looking at your own local file. In Reading view, an HTML comment is hidden the same way it would be in a browser. In Source/Live Preview mode, you see it as plain text, since you're literally looking at the file. Nothing is ever removed; it's your file, sitting on your disk, exactly as you typed it, until you delete it yourself.

VS Code Markdown Preview

The simplest case on this list: the built-in preview pane hides HTML comments, the editor pane shows them, because you're editing a plain local file and the preview is just a live render of it — no build step, no publish step, nothing gets removed.

Quick reference

Platform / context	HTML comment behavior
GitHub (files, Issues, PRs)	Hidden in render, present in raw source
GitLab (files, MRs)	Hidden in render, present in raw source
npm / PyPI README	Hidden in render, present in page source
Jekyll — `<!-- -->`	Hidden in render, present in shipped HTML
Jekyll — `{% comment %}`	Removed entirely at build time
Hugo — `<!-- -->` in content	Hidden in render, present in shipped HTML
Hugo — `{{/* */}}` in layouts	Removed entirely at build time
MkDocs / Docusaurus	Hidden in render, present in shipped HTML
Confluence	Usually dropped or shown literally — not reliably hidden
Notion	Stripped entirely on import
Obsidian	Nothing removed — visible in Source mode, hidden in Reading view
VS Code preview	Hidden in preview pane, visible in editor pane

What this means in practice

Two practical takeaways follow directly from the table above.

Never treat an HTML comment as a privacy or security boundary. On the majority of platforms here, "hidden" means "not displayed," not "not present." Anything sensitive — API keys, internal pricing, a note about a security issue you haven't disclosed yet — needs to actually not be in the file at all, or needs to live somewhere with real access control. If you're publishing through Jekyll or Hugo specifically and want a note that genuinely never reaches the output, use the templating engine's own comment tag ({% comment %} or {{/* */}}), not a plain HTML comment.

Don't assume a comment will survive a platform migration. If you're moving content from a Git-based Markdown workflow into Confluence or Notion, any HTML comments you were relying on for editorial notes, TODOs, or draft flags will very likely not make the trip — either they'll vanish silently or, worse, show up as visible clutter. Strip them out (or convert them to that platform's native commenting feature) before you migrate, rather than after someone notices.

You can test any of this yourself before committing to a workflow: paste Markdown containing comments into the Markdown Live Preview Editor and check both the rendered pane and the raw output. It won't simulate a Confluence or Notion import, but it will immediately confirm the base case — hidden in render, present in source — that every platform above starts from before adding its own quirks on top.

How to Add Comments in Markdown — the syntax fundamentals this guide builds on
Why Your Markdown Isn't Rendering — troubleshooting for when template syntax gets executed instead of displayed
Markdown in Confluence: What Actually Works
Markdown for Notion: What Actually Works and What Doesn't
Markdown Across Platforms: The Compatibility Guide

Mermaid Diagrams in Slack, Jira, Confluence, Word, and Email: The Static Export Workaround

2026-09-18T00:00:00+00:00

Our complete guide to diagrams and flowcharts in Markdown covers Mermaid syntax in depth — flowcharts, sequence diagrams, ER diagrams, the works. What it doesn't dwell on is a problem that shows up the moment you try to actually use one of those diagrams somewhere other than a GitHub README: most of the places you'd want to paste a diagram don't render Mermaid at all.

That's not a syntax problem, and no amount of getting the Mermaid code "right" fixes it. It's a rendering-engine problem — Slack, Jira, Confluence, Word, and email clients simply have no Mermaid interpreter anywhere in their pipeline. The fix isn't better Markdown. It's exporting the diagram as a plain image before it leaves your Mermaid source.

Why this keeps catching people off guard

Mermaid fences (```mermaid) look exactly like any other fenced code block, and on the platforms that *do* support it — GitHub, GitLab, Obsidian — that fence quietly becomes a rendered diagram with zero extra steps. It's easy to assume the same thing will happen everywhere else, because nothing about the syntax signals "this only works in three places." It doesn't error. It doesn't warn you. It just shows up as a gray code block of flowchart TD and arrow syntax, exactly as literally typed, and the reader has to reconstruct the diagram in their head from the text.

We ran into this from the other direction first, while documenting our own conversion tools: our Notion conversion guide, Word/DOCX guide, and Email HTML guide all independently document the same fallback: a Mermaid fence gets carried through as an inert code block, with a warning, because there's no other honest thing a converter can do with syntax the destination format can't execute. Slack and Jira have the identical gap for a different reason — there's no conversion step at all, since you're typically composing directly in Slack's message box or Jira's editor, and neither one has ever implemented a Mermaid renderer.

The fix: render it once, export a static image

The workaround is the same regardless of destination: render the Mermaid source into an actual image — SVG or PNG — outside the target platform, then paste or attach that instead of the Mermaid code. Once it's a PNG or SVG, every platform on this list handles it exactly the same way it handles any other image, because at that point it is just an image.

You can do this with the Mermaid CLI (mmdc) if you're comfortable with a Node toolchain and want it scripted into a build step — our diagrams guide covers that command-line path. For a one-off diagram, or if you don't want to install anything, our Markdown Mermaid Diagram Preview tool does the same rendering step in the browser: paste your Mermaid source, see it render live (so you catch syntax errors before you export, not after you've already pasted a broken image somewhere), then use Download SVG or Download PNG to get a static file with nothing installed.

Platform by platform

Slack

Slack has no diagram rendering of any kind — not in the message composer, not via the API, not through Block Kit. A Mermaid fence pasted into a Slack message just shows up as plain text with backticks, per our Markdown to Slack guide, which documents the same "no native rendering, period" behavior for tables and several other Markdown constructs. Export a PNG and drag it into the message instead — Slack handles inline image previews natively, and unlike a wall of Mermaid syntax, a teammate can actually read it without decoding the diagram in their head.

Jira

Neither Jira's classic wiki markup nor its modern Cloud rich-text editor has a Mermaid renderer, as our Markdown to Jira guide notes for wiki-markup conversion generally. Some teams install a marketplace add-on (several exist specifically for embedding live Mermaid/PlantUML diagrams in Jira issues), which is worth it if diagrams are a constant part of your workflow — but for an occasional diagram in a ticket, attaching an exported PNG is faster than getting a marketplace app approved and installed.

Confluence

Confluence's /markdown paste panel strips or escapes raw HTML and doesn't execute embedded scripts, so a Mermaid fence pasted in comes through as a plain code-formatted block, consistent with what our Confluence compatibility guide documents for other unsupported constructs. As with Jira, marketplace add-ons exist for live Mermaid rendering in Confluence pages if you need diagrams to stay editable in place; for a document going out once, attach the exported image and move on.

Word (.docx)

A .docx file has no code-execution layer at all — there's no such thing as a "live" Mermaid diagram inside a Word document, full stop. Our Markdown to Word guide documents that our own markdown-to-docx converter drops Mermaid fences to a plain monospace code block with a warning, for exactly this reason — there's nothing else a converter could do with it. Export the diagram as a PNG first, then either paste it directly into the document or use our Markdown Image Formatter if you want a sized/captioned version before it goes in.

Email (newsletters, transactional templates)

Same root problem as Word, for the same reason: email clients render HTML, not JavaScript, and Mermaid needs JavaScript to do its layout work. Our Markdown to Email HTML guide documents the identical fallback — a Mermaid fence becomes a plain code block with a warning banner. For email specifically, export PNG, not SVG: SVG support in email clients is inconsistent (particularly in Outlook's desktop Word-based rendering engine, already a recurring theme in that guide), while a PNG is universally safe.

SVG vs. PNG: which to export

Reach for SVG when the destination platform accepts vector images and you might need to resize or embed the diagram at multiple sizes — a wiki page, a MkDocs/Docusaurus site that doesn't render Mermaid live, a print-quality document. SVG stays crisp at any zoom level and is a much smaller file for simple diagrams.

Reach for PNG for everything else in the list above — Slack, Jira, Confluence attachments, Word, and especially email — where universal support matters more than infinite scalability, and where you can't be sure the destination will render an <img> pointing at an SVG correctly. Our tool exports PNG at 2x scale specifically so it still looks sharp on a high-DPI display without needing SVG's true vector scaling.

Quick reference

Destination	Native Mermaid rendering?	What to do instead
GitHub, GitLab, Obsidian	Yes, built in	Nothing — paste the fence directly
Slack	No, none	Export PNG, attach/drag into message
Jira	No (marketplace add-ons exist)	Export PNG, attach to issue
Confluence	No (marketplace add-ons exist)	Export PNG, attach to page
Word (.docx)	No, no execution layer at all	Export PNG, insert as image
Email (ESP / HTML template)	No, no execution layer at all	Export PNG (not SVG), inline in template
MkDocs / Docusaurus	Needs a plugin, off by default	Export SVG for a self-hosted static asset, or enable the plugin

Markdown Diagrams and Flowcharts: Complete Guide — full Mermaid/PlantUML syntax reference
Markdown to Slack Formatting Guide
Markdown to Jira Wiki Markup Guide
Markdown in Confluence: What Actually Works
Markdown to Word (DOCX): What Converts Cleanly
Markdown to Email HTML: Newsletters and ESPs
Try it yourself: Markdown Mermaid Diagram Preview

Markdown Word Count and Reading Time: How the Numbers Actually Get Calculated

2026-09-11T00:00:00+00:00

Paste the same Markdown document into two different word-count tools and you'll often get two different numbers — sometimes by a wide margin. Paste it into two different "reading time" estimators and the gap gets even bigger, because now two separate sources of disagreement stack on top of each other: how many words the tool thinks you wrote, and how fast the tool assumes a person reads.

Neither number is "wrong," exactly. They're built on different assumptions, and for Markdown specifically, one of those assumptions — whether the tool strips the markup before counting — matters a lot more than most people expect. This post covers how our own Markdown Word Count & Reading Time tool calculates its numbers, how that compares to what a handful of other well-known platforms do, and the practical implications for anyone publishing Markdown-authored content.

The Part Everyone Skips: What Counts as a "Word" in Markdown Source

A naive word counter just splits the raw text on whitespace and counts the pieces. Applied directly to Markdown source, this produces a number that's subtly wrong in both directions at once:

Markup tokens get counted as words. A heading marker (##), emphasis delimiters (**/_), a link's URL, and the punctuation around an image reference all split into whitespace-separated tokens. A link like [check the docs](https://example.com/very/long/path) naively counts as two "words" — [check and the... — when a reader only sees "check the docs" as three words of prose, and the URL isn't read as words at all.
Some real prose gets undercounted. A sentence broken across multiple soft-wrapped lines inside a blockquote, or text sitting inside a table cell, can get miscounted depending on how the splitter handles the surrounding > or | characters.

The practical effect is that a heavily-linked reference document or a page full of tables and images can show a meaningfully inflated or deflated word count compared to a plain-prose post of the same actual reading length — purely as an artifact of how much Markdown syntax surrounds the words, not because the tool is "buggy." It's just measuring markup density, not prose length.

Our tool strips Markdown syntax first — heading markers, bold/italic delimiters, link brackets and target URLs, image syntax — before it counts anything, so the word count reflects the words a reader would actually see rendered, not the raw character soup of the source file. If you're comparing a word count from our tool against a plain wc -w on the raw .md file, expect them to disagree, and expect the difference to grow with how markup-heavy the document is.

How Our Tool Calculates Reading Time

Once the stripped word count is in hand, reading time is estimated at 238 words per minute — the average adult silent-reading speed for meaningful, non-skimmed text, from a 2019 meta-analysis by Brysbaert et al. that reviewed reading-speed studies going back decades. It's a plain word-count-divided-by-rate calculation with no adjustments for images, code blocks, or content type, rounded up to the next whole minute (a document estimated at 0.4 minutes still shows "1 min read" — nobody wants to see "0 min read").

The full stat panel reports ten numbers total: words, minutes to read, characters (with and without spaces), sentences (approximated from sentence-ending punctuation), paragraphs (blank-line-separated blocks, excluding headings and code blocks), headings, links, images, and fenced code blocks. All ten are computed from a single pass over the stripped and structural-element-tagged text, so they stay consistent with each other — the word count you see is the same one the reading-time estimate is based on.

Why Other Tools Give You a Different Number

If you've ever seen a "3 min read" badge on a blog post and thought it felt off, here's why estimates vary so much between platforms — it's not just a different WPM constant, though that's part of it:

The words-per-minute assumption itself varies widely. Published estimates for silent reading of average material range from roughly 200 to 275+ WPM depending on the study and the type of content being read (technical or unfamiliar material is read slower than casual prose). Plenty of blogging tools and CMS plugins default to a round number like 200 WPM rather than a research-cited figure, simply because it's an easy default to ship and adjust later.

Some platforms add fixed time for images on top of the word count, rather than relying on WPM alone. The best-known example is Medium's publicly documented reading-time algorithm: it adds 12 seconds for the first image in a post, decreasing by one second for each subsequent image down to a floor of 3 seconds per image, on top of a roughly 265-WPM word-based estimate. The reasoning is that a reader's eye pauses on an image for a real, measurable amount of time that a pure word count doesn't capture at all — the more images a post has, the more this pushes the total above what word count alone would suggest. Several open-source reading-time libraries (used by a number of blogging platforms and static-site plugins) borrow this same image-time-plus-word-time approach rather than inventing their own.

Some don't strip markup, or strip it differently. A platform's reading-time calculator that runs on already-rendered HTML text (stripping HTML tags rather than Markdown syntax) will produce a different word count than one that runs on raw Markdown source and strips Markdown syntax — the two aren't measuring quite the same input, even when both claim to be counting "the words in the post."

A few platforms don't estimate reading time at all, and it's added manually by the author, via a separate plugin, or not shown at all — so "no reading time badge" doesn't necessarily mean "short post," just that the platform doesn't calculate one.

None of this makes any single number more "correct" than another — they're all reasonable estimates built on different, defensible assumptions. But it explains why you shouldn't expect two tools to agree, and why a reading-time badge is a rough signal, not a precise measurement.

Quick Reference: What Varies Between Reading-Time Approaches

Factor	What it affects
WPM assumption (commonly 200–275)	The baseline word-count-to-minutes conversion; higher WPM = shorter estimated time for the same word count
Markup-stripping before counting	Whether Markdown/HTML syntax inflates or deflates the "word" count itself, before WPM is even applied
Fixed per-image time (Medium-style algorithms and the libraries that copy the approach)	Adds extra seconds per image on top of the word-based estimate, so image-heavy posts read as longer than their word count alone suggests
Content-type adjustment	Some estimators don't adjust for this at all (ours doesn't); others informally assume technical/code-heavy content is read slower, though this is far less standardized across tools than the WPM constant itself
Whether reading time is shown at all	Some platforms simply don't calculate or display it, which isn't itself a signal about post length

Practical Implications for Writers

None of this is purely academic if you're publishing regularly:

Reading-time badges are directional, not precise. Treat "5 min read" as "this will take you a few minutes," not a literal stopwatch prediction — actual reading speed for any individual reader varies enormously based on familiarity with the topic, whether they're skimming or reading closely, and whether the content is prose or dense technical material.
Word count is still useful as a length gauge, independent of the reading-time conversion — the raw number tells you whether a post is thin (worth expanding) or sprawling (worth tightening), which is a more actionable signal than the derived minutes figure.
If you're comparing counts across tools, check whether markup is stripped. A count taken directly off the raw .md file (e.g., a quick wc -w) will run higher than a count taken after Markdown syntax is stripped, and the gap grows with how link- and formatting-heavy the document is — this is the single most common source of "why don't these two numbers match" confusion.
Structural stats (headings, code blocks, links, images) are often more useful than the word count alone when you're doing an editorial pass — a post with far more headings than paragraphs might be under-developed per section; one with a high image count but few words of surrounding prose might need more explanatory text around each image.

Use Cases

Pre-publish checks: confirm a draft hits a target length before it goes out, without needing to open a separate word processor
README and documentation length audits: spot check whether a README has grown unwieldy, or whether a section is too thin to be useful
Editorial workflows: use the structural stats (headings, paragraphs, code blocks) alongside the word count to catch under-developed sections, not just short posts
Cross-tool sanity checks: if a CMS's built-in word count disagrees with ours, the tables above cover the most likely reasons why, rather than assuming either number is broken

If you're checking a document's length and structure, our Markdown Linter catches heading-hierarchy and formatting issues the word-count stats won't surface on their own, and the Markdown Live Preview Editor lets you see exactly how the stripped, rendered version of your document looks before you publish. If your document is long enough that navigation matters, our Table of Contents Generator builds one automatically from your headings.

Markdown Image Sizing and Alignment Across Platforms: What Actually Works

2026-09-04T00:00:00+00:00

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.

Markdown Callouts and Admonitions Across Platforms: What Actually Renders

2026-08-28T00:00:00+00:00

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 old-school static blog, and you get an ordinary blockquote with the literal text [!NOTE] 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.

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 complete guide to admonitions and callouts and our narrower guide to warning boxes and alerts 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 Markdown Callout Generator does that.

GitHub and GitLab Alerts: Native, But Not CommonMark

GitHub's alert syntax — a blockquote whose first line is one of five fixed keywords in brackets — is the one most people encounter first:

> [!NOTE]
> Useful information that users should know, even when skimming.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

Those exact five types — no more, no fewer — are the only ones GitHub's renderer recognizes. Typing > [!DANGER] or > [!INFO] 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.

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 [!KEYWORD] 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 [!NOTE] — no styling, no icon, no color. It's still readable, just not what you intended.

Obsidian Callouts: A Similar Look, a Different (Larger) Vocabulary

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:

> [!note] Project Setup
> Follow these steps to configure your environment.

> [!warning] Version Compatibility
> This plugin requires Obsidian 0.15.0 or higher.

> [!tip]- Collapsible Tip
> The minus sign after the type makes this foldable, closed by default.
> A plus sign instead makes it foldable, but open by default.

Obsidian recognizes over a dozen built-in types (note, abstract/summary, info, todo, tip/hint, success/check, question, warning/caution, failure/fail, danger/error, bug, example, quote), several of which are simply aliases for each other, plus a fold indicator (-/+ 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 — [!warning] Version Compatibility — where GitHub's alerts always use the fixed keyword itself as the visible title with no override.

Because the outer shape (> [!type]) looks so similar to GitHub's, it's easy to assume the two are interchangeable. They're not: paste [!tip]- 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 [!IMPORTANT] into Obsidian and it renders as a plain, unstyled callout box with no icon, because important 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).

MkDocs: A Real Extension, Config Required, Indentation-Sensitive

MkDocs (via Python-Markdown's admonition extension, or the more capable pymdownx.details for foldable versions) uses a completely different syntax shape — no blockquote > at all:

!!! note "Configuration Requirements"
    This feature requires Python 3.8+ and the following dependencies.

??? tip "Click to expand"
    Using `???` instead of `!!!` makes the block collapsible, closed by default.
    `???+` makes it collapsible but open by default.

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 admonition (and pymdownx.details if you want the foldable ??? variant) under markdown_extensions: in mkdocs.yml. Without that config line, !!! note 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 !!!/??? 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: !!! note, !!! danger, !!! example, 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.

None of GitHub's, GitLab's, or Obsidian's blockquote-based syntax does anything special in MkDocs — a pasted > [!NOTE] block just renders as a plain, unstyled blockquote with visible bracket text, exactly like taking GitHub syntax to any other non-GitHub renderer.

Docusaurus: A Third Shape Entirely — Fenced Directives

Docusaurus (and MDX-based tooling more broadly) uses yet another format, based on triple-colon fenced directives rather than either blockquotes or indented blocks:

:::note
Useful information that users should know.
:::

:::tip[Optional Custom Title]
Helpful advice, with an optional title in square brackets.
:::

:::danger
Highlights dangerous actions or negative outcomes.
:::

Docusaurus supports five built-in types (note, tip, info, warning, danger) 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 :::note 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.

Quick Reference

Platform	Syntax shape	Native or needs config	Fold/collapse support
GitHub	`> [!TYPE]` blockquote, 5 fixed types	Native, no config	No
GitLab	`> [!TYPE]` blockquote, same 5 types as GitHub	Native, no config	No
Obsidian	`> [!type]` blockquote, 12+ types, custom titles	Native, no config	Yes — `[!type]-` / `[!type]+`
MkDocs (Material or base theme)	`!!! type "Title"`, 4-space indented content	Needs `admonition` extension enabled in `mkdocs.yml`	Yes, with `pymdownx.details` — `???`/`???+`
Docusaurus	`:::type` ... `:::` fenced directive	Native (built into MDX pipeline)	No (use a separate `<details>` for that)
Sphinx / reStructuredText	`.. type::` directive (not Markdown at all)	Native to RST	No
Plain CommonMark / unconfigured static sites	N/A	None of the above render specially — all fall back to a plain blockquote or paragraph with literal syntax visible	N/A

What Doesn't Cross-Render, Concretely

The pattern across every combination above is the same: each platform's callout syntax is invisible to every other platform's renderer, and none of them error — they all degrade to plain, unstyled Markdown with the literal syntax characters left visible in the text. Concretely:

GitHub-alert syntax (> [!NOTE]) pasted into a MkDocs site does not become a styled admonition — MkDocs's admonition extension has no idea what a [!NOTE] blockquote is, so it renders as an ordinary blockquote with visible bracket text.
MkDocs syntax (!!! note) pasted into GitHub does not become a callout — GitHub's renderer only pattern-matches its own five bracketed keywords inside blockquotes, and !!! note isn't even inside a blockquote to begin with, so it just renders as a plain paragraph starting with !!!.
Docusaurus's :::note 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.
Obsidian's extended type vocabulary ([!bug], [!question], [!abstract]) pasted into GitHub renders as an unstyled blockquote, since those types fall outside GitHub's fixed five.

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 <div class="admonition"> 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.

Markdown Admonitions and Callouts: Complete Guide — the fuller syntax reference and platform examples this post assumes as background
How to Create a Warning Box Alert in Markdown — the narrower blockquote-vs-HTML warning box case specifically
Markdown Across Platforms: What Actually Works in GitHub, Notion, Obsidian, and Confluence — the broader platform-compatibility picture beyond callouts
Why Your Markdown Isn't Rendering: A Troubleshooting Guide — if a callout you pasted somewhere shows up as a plain blockquote instead of a styled box

And if you'd rather generate the correct syntax for your target platform than memorize four different formats, try the Markdown Callout Generator.

Markdown Math Rendering Across Platforms: Where LaTeX Actually Works

2026-08-21T00:00:00+00:00

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 dollar-sign convention for math was never part of core Markdown, CommonMark, or even GitHub Flavored Markdown's official spec. It's a widely-adopted convention that individual platforms opt into (or don't) on their own timeline, using different rendering engines with subtly different output. If you've ever pasted a formula that worked perfectly in one tool and showed up as raw LaTeX soup in another, this is why.

This guide covers which platforms actually render math natively, which need a plugin or app, which don't support it at all, and the practical differences between the two rendering engines you'll run into everywhere: MathJax and KaTeX. If you want the LaTeX syntax basics themselves rather than platform behavior, our complete guide to math expressions in Markdown covers that ground — and our Markdown Math Preview tool lets you check a formula renders correctly, live in your browser, before you paste it anywhere.

Native Support: GitHub, GitLab, Obsidian

Three platforms render $inline$ and $$block$$ math out of the box, no setup required.

GitHub added native math rendering in 2022, using MathJax. It works in READMEs, issues, pull requests, wiki pages, and Markdown files viewed in the repo browser — anywhere GitHub renders Markdown. Inline math uses $formula$ with no space touching the dollar signs; block math uses $$formula$$ on its own line(s). GitHub's implementation is deliberately conservative: it supports the common LaTeX commands (fractions, exponents, Greek letters, sums, integrals, matrices) but not obscure packages, and it silently falls back to plain text for anything it can't parse rather than showing an error.

GitLab has supported math rendering since GitLab 13.0 (2020), using KaTeX rather than MathJax. Syntax is the same $...$ / $$...$$ convention, and it works in issues, merge requests, wikis, and Markdown files. Because it's KaTeX-based, GitLab's rendering is closer to what our own Markdown Math Preview tool produces than GitHub's MathJax output is — worth knowing if you're maintaining docs that need to look consistent across both platforms.

Obsidian renders math natively in both edit and reading views, using MathJax under the hood (via the KaTeX-compatible subset it bundles). This is genuinely useful for people keeping research notes or technical vaults, since the formula renders live as you type rather than requiring a separate preview step. Obsidian's math also plays well with its block-reference and embed system, so you can reference a specific equation from another note.

Needs a Plugin: Static Site Generators

Static site generators almost universally treat $ as literal text by default. Math support has to be added deliberately.

Jekyll (this blog's own engine, and GitHub Pages' default) has no built-in math support in kramdown. You need a plugin like jekyll-katex, or you can skip the plugin entirely and just load KaTeX's or MathJax's CSS/JS directly in your layout and let its auto-render script scan the page for $...$ after the page loads. The plugin approach pre-renders at build time (faster page loads, works without JavaScript); the client-side script approach is less setup but adds a render flash and a JS dependency.

Hugo has first-class support for this through render hooks in newer versions (Hugo 0.122+), letting you wire up KaTeX or MathJax rendering for passthrough math blocks without a third-party module — Hugo's Goldmark-based Markdown renderer can pass $...$ /$$...$$ through untouched for a script to pick up. Older Hugo setups typically use a shortcode or a theme-provided partial for the same effect. Either way, it's opt-in configuration, not default behavior.

Docusaurus supports math via two remark/rehype plugins — remark-math and rehype-katex — added to your docusaurus.config.js. This is a well-documented, one-time setup, and once it's in place, $...$ /$$...$$ in any .md/.mdx file just works. Because it's explicitly KaTeX-based, output is consistent with GitLab's and with our Markdown Math Preview tool.

MkDocs similarly needs a math extension (pymdownx.arithmatex from the PyMdown Extensions package is the common choice) plus a KaTeX or MathJax script reference in your theme, following the same "opt-in, one-time config" pattern as Hugo and Docusaurus.

Real Feature, Different Trigger: Notion

Notion supports LaTeX math, but not via the $...$ dollar-sign convention as your primary path — it's a block/inline type you insert with the /equation (or /math) slash command, or by typing $$ and pressing space to trigger an inline equation editor. Once inserted, you type LaTeX inside that dedicated equation block, and Notion renders it with its own KaTeX-based engine. If you paste a Markdown file containing raw $...$ text into Notion, it generally will not auto-convert that into a rendered equation the way headings or bold text get auto-converted on paste — you get literal dollar-sign text, and need to manually convert it via the equation block. This trips up anyone assuming Notion behaves like GitHub here; the feature exists, but the entry point is different.

Needs a Marketplace App or Doesn't Support It: Confluence, Jira, Slack

Confluence has no native $...$ math rendering in its standard editor. Cloud users can add a marketplace app (several LaTeX-rendering add-ons exist) that adds a macro for inserting rendered formulas, but that's a dedicated macro/insert flow, not something that recognizes dollar-sign syntax typed inline. If you paste Markdown with LaTeX math into Confluence via the /markdown panel (see our Confluence guide for how that panel behaves generally), the math syntax passes through as literal text.

Jira has no math rendering at all in its wiki markup or in the modern rich-text editor — there's no macro, no plugin ecosystem equivalent to Confluence's for this specific feature. If your team needs formulas in Jira tickets, the common workaround is rendering the equation elsewhere (including with our tool) and pasting it in as an image.

Slack doesn't support math rendering anywhere — not in the message composer, not via the API/Block Kit, not with a workaround short of posting a pre-rendered image. A message containing $E = mc^2$ displays as exactly that literal text. Given mrkdwn's generally limited formatting (see our Markdown to Slack guide for the full picture), this isn't surprising, but it catches people off guard the first time.

MathJax vs. KaTeX: Why the Same Formula Can Look Different

Two rendering engines account for nearly every platform above, and they're not pixel-identical:

MathJax is the older, more complete implementation — broader LaTeX command coverage, including several packages and less-common symbols, at the cost of being noticeably heavier and historically slower (modern versions have closed much of that gap, but it's still the heavier of the two). GitHub and Obsidian use MathJax or a MathJax-derived engine.
KaTeX is faster (it renders synchronously, without MathJax's original asynchronous typesetting pass) and covers the large majority of everyday math notation, but it deliberately supports a smaller command set — some advanced LaTeX packages used in academic papers will throw a parse error in KaTeX that a full MathJax/LaTeX setup would render fine. GitLab, Docusaurus, MkDocs (with the common config), Notion, and our own Markdown Math Preview tool are all KaTeX-based.

In practice this means a formula that renders cleanly on GitHub isn't guaranteed to look byte-for-byte identical on GitLab, and a formula relying on an obscure package might work in one and throw an error in the other. For everyday formulas — fractions, exponents, Greek letters, sums, integrals, standard matrices — you won't notice a difference. For anything exotic, test on your actual target platform rather than assuming.

Quick Reference

Platform	Math support	Engine	How it's triggered
GitHub	Native	MathJax	$...$ / `$$...$$` anywhere Markdown renders
GitLab	Native	KaTeX	$...$ / `$$...$$` anywhere Markdown renders
Obsidian	Native	MathJax-derived	$...$ / `$$...$$`, live in edit and reading views
Notion	Real feature, different entry point	KaTeX	`/equation` block or `$$` + space, not passive $...$ paste
Jekyll / GitHub Pages	Needs plugin or manual script	Your choice (KaTeX or MathJax)	Plugin (e.g. `jekyll-katex`) or client-side auto-render script
Hugo	Needs render hook or theme support	Your choice	Goldmark passthrough + KaTeX/MathJax script
Docusaurus	Needs plugin config	KaTeX	`remark-math` + `rehype-katex`
MkDocs	Needs extension	Your choice	`pymdownx.arithmatex` + theme script
Confluence	Marketplace app only	Varies by app	Dedicated macro/insert, not inline $...$
Jira	Not supported	—	No native option; paste as image
Slack	Not supported	—	No native option; paste as image

Practical Takeaways

If you're writing math-heavy documentation and want it to render without any setup on the reader's end, GitHub, GitLab, or Obsidian are your only truly zero-configuration options. If your docs live on a static site generator, budget time for the one-time plugin setup — it's usually a few lines of config, but it's not automatic, and a Markdown file with unrendered $...$ littered through it looks broken to anyone who stumbles on the raw source before the setup is done. And if your formulas are headed to Confluence, Jira, or Slack, plan on images rather than fighting a platform that was never going to render LaTeX in the first place.

Whichever platform you're targeting, it's worth checking the formula renders the way you expect before you commit it to a README or a ticket — a misplaced brace or an unsupported command shows up as a parse error or, worse, silently wrong output. Our Markdown Math Preview tool renders both inline and block math live as you type, using KaTeX, and shows the exact parser error if something doesn't parse — a fast sanity check before you paste a formula into any of the platforms above.

Math Expressions in Markdown: Complete LaTeX and MathJax Guide — the LaTeX syntax fundamentals this post assumes you already know
Markdown Across Platforms: What Actually Works in GitHub, Notion, Obsidian, and Confluence — the broader platform-compatibility picture beyond just math
Markdown in Confluence: What Actually Works — more detail on the /markdown paste panel referenced above
Markdown to Slack Formatting: What Actually Works — the full picture of mrkdwn's formatting limits

Markdown Task Lists and Checkboxes Across Platforms: What's Actually Interactive

2026-08-07T00:00:00+00:00

Type - [ ] Do the thing into a Markdown file and you'll get a checkbox almost everywhere — GitHub, GitLab, Notion, Obsidian, and most static site generators all recognize the syntax. What's inconsistent is what happens next. On some platforms that checkbox is genuinely clickable, and clicking it edits the real content. On others it renders as a checkbox-shaped image that does absolutely nothing when you click it — it's just a disabled <input> tag with no logic wired up behind it. Confusing the two is an easy mistake to make, especially if your only experience is with the one platform where it happens to work.

This guide covers where checkboxes are real, where they're decoration, and the couple of places task lists silently break outright — plus a mention of our new Markdown Checklist Generator if you just want clean, correctly-nested checklist syntax without hand-typing brackets and indentation. If you're looking for basic task list syntax itself rather than platform behavior, our complete guide to task lists and checkboxes covers that ground.

GitHub: Interactive in Issues and PRs, Static in Files

GitHub is the platform most people picture when they think of "clickable Markdown checkboxes," and it's also the platform with the split behavior that trips people up.

In issue bodies, pull request descriptions, and comments, a - [ ] checkbox renders as a real, clickable <input type="checkbox"> wired directly to the underlying issue/PR text. Click it (if you have write access, or you're the author) and GitHub edits the stored Markdown body for you, flipping [ ] to [x] in place. This is genuinely interactive — the checkbox state and the raw text are the same source of truth, always in sync.

GitHub also does something useful with this automatically: any issue or PR containing a task list gets an "N of M tasks complete" progress count that shows up in the issue list, the sidebar, and anywhere that issue is referenced or linked from another issue. You don't have to configure anything for this — it's computed straight from the checkbox count in the body text.

In regular repository files — a README, a docs page, any .md file rendered on github.com's file browser — the story is different. GitHub still renders the checkbox visually, but it's a disabled input with no click handler behind it, because there's no "body" concept to persistently update; it's just a static file being rendered as HTML. You can look at a checked-off roadmap in a README and it looks exactly like an interactive one, but nothing happens if you click it. This is the single most common source of confusion in this whole topic — people assume README checkboxes work like issue checkboxes because they're visually identical.

GitLab: The Same Split as GitHub

GitLab's behavior mirrors GitHub closely enough that if you understand one, you understand the other. Task lists inside issue descriptions and merge request descriptions are interactive — click a checkbox and GitLab persists the change to the description text, and issue lists show a task-completion count the same way GitHub's does.

Task lists rendered inside wiki pages and regular repository files (README, any Markdown file in the file browser) are static, same as GitHub — visually identical checkboxes, no click behavior. If you're building internal documentation in a GitLab wiki and picturing an interactive checklist your team can tick off together, that's not what you'll get; you'd want an actual issue or a dedicated task-tracking feature instead.

Confluence: A Real Interactive Feature, But It's Not the Markdown Syntax

Confluence has genuinely interactive, assignable task items — but they come from a distinct editor feature, not from typing GFM-style - [ ] syntax. In the Confluence editor, typing [] followed by a space (or using the Insert menu) creates an Action Item: a real interactive checkbox that can be assigned to a person, given a due date, and tracked in Confluence's own Tasks report across the whole space. That's a more capable feature than a plain Markdown checkbox in most other tools.

Where it gets inconsistent is pasting raw Markdown task list syntax into Confluence — through the /markdown slash-command panel we've covered before. Our own testing there found - [x] syntax converts unreliably: sometimes it becomes a real Action Item, sometimes it just renders as literal bracket text, depending on the Confluence version and editor mode. If checkbox interactivity matters, use Confluence's native Action Item feature directly rather than relying on a Markdown paste to produce one.

Jira: Depends Entirely on Which Editor and Project Type

Jira wiki markup — the plain-text format used by Server, Data Center, and classic (non-next-gen) Cloud projects — has no checkbox syntax at all. Typing - [ ] Task into a wiki-markup field just renders as a literal bullet point followed by the literal characters [ ] Task; there's nothing for the renderer to interpret, which is exactly what our own Markdown to Jira converter produces when it hits checkbox syntax, since there's no Jira wiki-markup equivalent to convert it to.

The modern Jira Cloud rich-text editor (used in team-managed/next-gen projects) does have a real interactive Task list block, but you reach it through the editor's Insert menu or its own autoformat shortcut, not by pasting GitHub-style Markdown. If your workflow involves generating Jira content programmatically, it's worth checking which editor your specific project type actually uses before assuming checkbox syntax will do anything.

Notion: Converts to a Real Block, Not Rendered Markdown Text

Notion doesn't really "render Markdown" the way a static site or a GitHub file does — when you type or paste - [ ] syntax, Notion converts it on the spot into one of its own native To-do blocks, which is a first-class, always-interactive, always-clickable element in Notion's block-based document model. There's no static/interactive split here the way there is on GitHub or GitLab, because by the time you see a checkbox in Notion, it's no longer "Markdown" at all — it's a Notion block that happens to have originated from Markdown syntax. We cover Notion's broader import behavior, including where this conversion does and doesn't kick in cleanly, in our Markdown for Notion guide.

Obsidian: Interactive and Writes Back to the File

Obsidian is the one place in this list where "interactive" means something slightly different and arguably more useful: clicking a checkbox in Reading view or Live Preview doesn't just update some in-memory display state, it actually edits the .md file on disk, flipping [ ] to [x] in the raw text. Since Obsidian vaults are just folders of plain Markdown files, that checkbox click is a real file write, not an API call against a hosted document like GitHub's. This makes Obsidian genuinely good for checklist-style notes you expect to interact with over time, and it's part of why the Tasks community plugin is popular — it extends this native checkbox behavior with due dates, recurring tasks, and query-based task views across your whole vault.

Linear: Live Markdown-Shortcut Conversion

Linear's issue description editor supports Markdown-style shortcuts as you type, and task list syntax is one of them — typing - [ ] converts it live into an interactive checklist item within the issue, similar in spirit to Notion's live-conversion behavior. As with Notion, once it's converted it's a native editor element rather than literal text sitting in a Markdown file, so there isn't a "static file" version of this to worry about the way there is with GitHub or GitLab.

Quick Reference

Platform	Where checkboxes are interactive	Where they're static or unsupported
GitHub	Issues, PRs, comments (with auto task-count tracking)	Repository files (READMEs, docs) rendered on github.com
GitLab	Issue descriptions, merge request descriptions	Wiki pages, repository files
Confluence	Native Action Items (typed via `[]` or Insert menu)	Raw Markdown `- [ ]` pasted via the `/markdown` panel — inconsistent
Jira	Cloud team-managed project rich-text editor's Task list block	Jira wiki markup (Server/Data Center/classic Cloud) — no checkbox syntax exists
Notion	Always — converts to a native To-do block on entry	N/A — it's no longer Markdown once converted
Obsidian	Reading view and Live Preview — writes back to the file	N/A — same file either way
Linear	Issue description editor, live Markdown-shortcut conversion	N/A — converts on entry

The Automation Angle: GitHub's Completion Tracking

Worth calling out on its own, since it's easy to miss: GitHub computes checklist completion automatically, with zero configuration. Any issue or PR body with task list syntax gets a live "3 of 7 tasks complete" count wherever that issue is displayed — the issue list, the sidebar of a linked PR, search results. If you reference another issue as a checklist item (- [ ] #123), GitHub can track that as a linked sub-issue and roll its completion into the parent's progress. This is genuinely useful for release checklists and multi-step feature tracking, and it's specific to GitHub — GitLab shows a similar per-issue completion count, but the cross-issue linking behavior isn't identical, so don't assume feature parity if you're moving a workflow between the two.

Where Task Lists Break Outright

Two failure modes show up regardless of platform, because they're rooted in how Markdown parsers work rather than in any single renderer's choices:

Task lists inside table cells don't render as checkboxes. GFM table cells are parsed as inline content, and a task list is a block-level list construct — parsers don't recognize block elements inside a table cell, so - [ ] typed into a pipe-table cell just shows up as literal text, brackets and all, on every platform we've tested. If you need a checklist-style status column in a table, use a plain character (✅/⬜, or a simple "Done"/"Pending" column) instead of task list syntax.

Nested checkbox indentation is stricter than it looks. GFM expects consistent indentation — typically two spaces — for a nested task item to be recognized as a child of the item above it. Get the indentation wrong (three spaces, a stray tab, inconsistent indentation between sibling items) and the parser either treats the "nested" item as a new top-level list item or, on some renderers, breaks the list into two separate lists entirely. On GitHub specifically, this also affects whether a nested item's completion counts toward the parent's tracked progress, so a subtly wrong indent isn't just a cosmetic issue there.

Hand-typing nested checklists with correct, consistent indentation is exactly the kind of small-but-annoying formatting task worth offloading — our Markdown Checklist Generator builds the syntax (including nesting) for you, so the raw Markdown is correct before it ever reaches whichever platform you're pasting it into.

Markdown Task Lists and Checkboxes: Complete Guide — the syntax fundamentals and platform-specific formatting variations this post assumes you already know
Markdown Across Platforms: What Actually Works in GitHub, Notion, Obsidian, and Confluence — the broader platform-compatibility picture beyond just task lists
Why Your Markdown Isn't Rendering: A Troubleshooting Guide — if a checklist you pasted somewhere isn't behaving the way you expected
Markdown in Confluence: What Actually Works — more detail on Confluence's Action Item feature and /markdown panel behavior
Markdown to Jira Wiki Markup: The Complete Conversion Guide — for the full Jira wiki-markup syntax picture

And if you just want correctly-formatted checklist Markdown without hand-typing brackets and indentation, try the Markdown Checklist Generator.

Word to Markdown: Pandoc vs. Mammoth.js vs. Online Converters vs. Copy-Paste

2026-08-01T00:00:00+00:00

If you've searched for "convert Word to Markdown," you've probably landed on a tutorial that walks you through one specific tool — usually Pandoc — and calls it done. That's fine if Pandoc is actually the right tool for what you're doing, but it often isn't. A one-off conversion of a single memo has completely different requirements than migrating two hundred archived Word docs into a docs-as-code repo, and "install a command-line tool" is a non-starter for a lot of the people who actually need this conversion done.

This guide skips the single-tool tutorial and instead compares the four real approaches people use, with the tradeoffs that actually matter: how well formatting survives, what happens to images and footnotes, whether you can batch-process a folder of files, and — often overlooked — whether your document has to leave your machine to get converted at all.

The Four Approaches

Pandoc — a command-line, do-everything document converter
Mammoth.js — a purpose-built library that specifically targets clean Word-to-HTML/Markdown output, not general document conversion
Online converters — upload-and-download web tools, usually running Pandoc or Mammoth on a server behind a simple UI
Copy-paste — pasting Word content directly into a Markdown-aware editor and manually fixing the result

Pandoc

Pandoc is the Swiss Army knife of document conversion — it converts between dozens of formats, and Word-to-Markdown is one of its best-supported paths.

pandoc document.docx -f docx -t markdown -o document.md

Strengths:

Handles footnotes properly — Word footnotes become real Markdown footnote syntax ([^1]), not inline text dumps
Extracts embedded images to a folder automatically with --extract-media=./media, and rewrites the image references to point at them
Scriptable and batchable — trivial to write a loop that converts an entire folder of .docx files in one pass, which matters if you're migrating an archive rather than converting one document
Multiple Markdown "flavors" as output targets — GitHub-Flavored Markdown (-t gfm), CommonMark, or Pandoc's own extended Markdown, depending on where the output is headed
Free, open source, and runs entirely on your machine — nothing about your document touches a third party

Weaknesses:

It's a command-line tool. Someone has to install it, and it's not something you can hand to a coworker who just wants to drag a file onto a web page
Table conversion is functional but not always pretty — complex tables (merged cells, nested tables) can come out structurally correct but visually messy, needing manual cleanup
Comments and tracked changes are dropped entirely — Pandoc converts the current document state, not the review history
Styling nuance (custom paragraph styles, specific font choices) is intentionally discarded, since Markdown has no equivalent — this is correct behavior for Pandoc's philosophy, but surprises people expecting a style-preserving conversion

Pandoc is the right choice when you're comfortable with a terminal, need to convert more than a handful of files, or are building conversion into an automated pipeline (a CI job that converts newly-uploaded Word docs into a docs repo, for instance).

Mammoth.js

Mammoth.js takes a narrower, more opinionated approach than Pandoc. It's built specifically to convert .docx to clean HTML (and, via a Markdown wrapper, to Markdown) by mapping Word's semantic styles — "Heading 1," "Heading 2," "Quote" — onto their HTML/Markdown equivalents, and deliberately ignoring Word's more chaotic direct-formatting details (font sizes, exact colors, manual indentation) that don't have a clean semantic mapping.

This design choice is exactly why Mammoth tends to produce noticeably cleaner Markdown than a general-purpose converter for real-world business documents: a Word doc exported from a corporate template, full of inconsistent manual formatting layered on top of the actual paragraph styles, converts into simple, readable Markdown instead of dragging all that formatting noise along with it. The tradeoff is the same decision in reverse — if a document relies on manual formatting rather than proper Word styles (someone selected text and clicked "bold" and "18pt" instead of applying a Heading style), Mammoth has less to work with and the structural mapping is weaker.

Mammoth is a JavaScript library, not a standalone CLI tool by default, which makes it the natural choice for two different audiences:

Developers embedding conversion in an app — Mammoth runs both server-side (Node.js) and entirely client-side in a browser via WebAssembly-free pure JS, which is what makes browser-based, no-upload converters possible
Anyone who wants a private, in-browser conversion without installing anything or sending a file to a server

Strengths:

Produces cleaner output than Pandoc specifically for documents built on proper Word styles, since it maps semantic structure rather than trying to preserve everything
Runs entirely client-side in a browser — no upload, no server round-trip, which matters if the document is sensitive
Lightweight and embeddable — a few lines of JavaScript, not a system dependency

Weaknesses:

Narrower feature set than Pandoc — no footnote conversion, weaker table handling for complex/merged cells, and it's Word-to-HTML/Markdown only (not the dozens of format pairs Pandoc supports)
Quality depends heavily on the source document using real Word styles rather than manual formatting — a messily-formatted document won't convert as cleanly as it would with a converter that tries to preserve everything literally
Being a library rather than a CLI, it's not something you'd reach for from a terminal for a quick one-off unless you're comfortable writing a few lines of Node

Online Converters

Web-based upload-and-download tools are, under the hood, usually running either Pandoc or Mammoth on a server — the tool itself isn't a third conversion engine so much as a UI wrapped around one of the first two. The real distinguishing factor between online converters isn't conversion quality (that's inherited from whichever engine is underneath), it's where your document goes.

This is the tradeoff most tutorials skip past, and it's worth being direct about: uploading a document to a random website means that document — which might be a contract, an internal memo, an unpublished manuscript, anything — is sitting on someone else's server, at least temporarily, possibly logged, possibly retained. For a public blog post you're about to publish anyway, that's a non-issue. For anything with confidential, personal, or legally sensitive content, it's worth reading the site's privacy policy before uploading, or better, using a tool where the conversion happens in your own browser and the file never leaves your machine at all.

Our own Word to Markdown tool is built specifically to avoid that tradeoff: it uses Mammoth.js and Turndown running client-side, in your browser, so the .docx file you drop in is never uploaded anywhere — the conversion happens locally and the file never leaves your machine. If you'd rather do this conversion instantly in your browser without installing anything or worrying about where your document ends up, that's what it's for. It inherits Mammoth's strengths (clean output for properly-styled documents, in-browser privacy) and its limitations (weaker on documents that rely on manual formatting rather than Word styles, and not the tool to reach for if you need Pandoc-grade footnote handling or a scripted batch pipeline).

Strengths (as a category):

Zero installation — genuinely the fastest path for a non-technical user or a single one-off conversion
Client-side tools in this category (like ours) offer the privacy benefit of local-only processing, with no upload at all

Weaknesses (as a category):

Server-side converters mean your document is uploaded somewhere — check what that site actually does with it
Usually a single-file workflow — not built for batch-converting a folder of documents
Feature set is whatever the underlying engine (Pandoc or Mammoth) supports, often with a subset of the command-line flags/options exposed through the UI

Copy-Paste

The oldest method, and still a reasonable choice for a short, simple document: open the Word file, select the content, paste it into a Markdown-aware editor, and manually clean up the result.

Some Markdown editors and note apps (Obsidian, Notion, several browser-based Markdown editors) will auto-detect basic formatting on paste — bold and italic survive, headings sometimes survive if they were built from Word's actual Heading styles, plain paragraph text comes through fine. Tables, footnotes, and anything beyond basic inline formatting generally do not survive a raw paste and need to be rebuilt by hand.

Strengths:

No tooling at all beyond whatever editor you already use
For a two-paragraph memo with a couple of bold words, genuinely faster than installing or uploading anything

Weaknesses:

Doesn't scale past a short document — the more structure (tables, lists, headings, footnotes) the source document has, the more manual rebuilding you're signing up for
Inconsistent behavior between target editors — what survives paste in Obsidian is not the same as what survives paste in a plain textarea
No image handling at all — images from the Word doc don't come along in a text paste; you'll be exporting and re-inserting them separately

Reasonable for a single short document with light formatting. Not a real strategy for anything longer or more structured.

Quick Reference

Approach	Fidelity	Images	Footnotes	Batch conversion	Privacy
Pandoc	High, especially footnotes/tables	Extracted to a folder automatically	Converts cleanly	Yes — scriptable	Local only, no upload
Mammoth.js	High for style-based docs, lower for manually-formatted ones	Extracted (base64 or file, depending on config)	Not supported	Possible with custom scripting	Local only if run client-side
Online converters	Depends on underlying engine (Pandoc or Mammoth)	Usually supported	Depends on engine	Rare — mostly single-file	Server-side unless explicitly client-side (check the tool)
Copy-paste	Low — basic inline formatting only	Not handled at all	Not handled	No — one document at a time	Local (nothing uploaded)

Which One Should You Actually Use?

Migrating an archive of Word documents into a docs-as-code repo — Pandoc, scripted in a loop, with --extract-media for images. This is the only approach in the list built for real batch work.
A developer who wants Word-to-Markdown built into an app or an internal tool — Mammoth.js, either server-side in Node or bundled client-side, depending on whether the app should avoid uploads.
A one-off conversion of a single document, and you don't want to install anything — a client-side online converter, like our Word to Markdown tool, especially if the document has any sensitivity to it and you'd rather it never leave your browser.
A short memo with light formatting and you already have a Markdown editor open — copy-paste is genuinely fine; don't reach for a conversion tool to solve a problem that's faster to fix by hand.

None of these is universally "best" — they're optimized for different situations, and the honest answer to "which Word to Markdown tool should I use" depends more on your document count, your formatting complexity, and your privacy requirements than on any single feature comparison.

How to Convert Word Documents to Markdown: Complete Guide — the original step-by-step tutorial covering Pandoc installation and manual conversion techniques in more depth
Markdown to Word (DOCX): What Converts Cleanly and What Doesn't — the reverse direction, for teams going from Markdown back to Word
Markdown Across Platforms: What Actually Works in GitHub, Notion, Obsidian, and Confluence — for what happens to your converted Markdown once it lands somewhere else
Why Your Markdown Isn't Rendering: A Troubleshooting Guide — if your converted Markdown doesn't render the way you expect afterward

And if you just want to convert a document right now without installing anything, try the Word to Markdown converter — drop in a .docx file, get clean Markdown out, entirely in your browser.

Markdown to Email HTML: Getting Your Content Into Newsletters and ESPs

2026-07-24T00:00:00+00:00

If you write your newsletter or transactional emails in Markdown and then paste the rendered HTML straight into your ESP (Mailchimp, Substack's HTML block, SendGrid, a custom mailer), you've probably noticed it doesn't look the way it did in your browser preview. Headings lose their styling, spacing collapses, and in Outlook things can look outright broken. That's not a bug in your Markdown renderer — it's because HTML email is not the same target as a web page, and a plain markdown-to-html conversion doesn't account for the difference.

This guide covers why email HTML has to be built differently, what converts cleanly, the gotchas that catch people off guard, and how our Markdown to Email HTML converter handles it.

Why Email HTML Is a Different Target

A normal web page loads a stylesheet once and applies it to every element on the page. Email doesn't work that way, for a simple reason: most email clients strip <style> blocks and ignore external CSS entirely, either for security or because their rendering engine doesn't support it. Gmail, in particular, is aggressive about stripping <head> styles in some contexts. That means the only styling that reliably survives is a style="..." attribute written directly on the element itself — this is called inlining.

The second difference is layout. Browsers give you flexbox, grid, and reasonably consistent box-model behavior across engines. Email clients don't. The safest way to guarantee a layout holds together across a dozen different rendering engines is still the decades-old technique of nesting <table> elements — not because tables are a good layout tool in 2026, but because table rendering is the one thing almost every email client agrees on.

Put together, that means converting Markdown to email-safe HTML isn't just "run it through a Markdown parser." It means:

Every styled element gets its CSS written inline, on the tag itself
The outer structure — the thing that keeps your content centered and a sane width — uses a table shell instead of <div>s and CSS width rules
You explicitly plan for what email clients don't support (external images that aren't hosted, <style> blocks, modern CSS like flexbox)

The Design Choice: Styled Semantic Tags, Not Table Soup

Some hand-coded email tools go further and convert every single text element — headings, paragraphs, list items — into nested <table>/<td> structures, on the theory that tables are the only truly safe primitive. We didn't do that in our converter, and it's worth explaining why, since it's a deliberate tradeoff rather than a shortcut.

Our Markdown to Email HTML tool uses real semantic tags — <h1>–<h6>, <p>, <ul>/<ol>, <blockquote> — each with a full inline style attribute, and reserves table markup for the two places where it actually matters: the outer structural shell (a single-column, centered, fixed-width wrapper) and any actual Markdown tables in your source content. Modern email clients (Gmail, Apple Mail, most mobile mail apps) render styled semantic HTML just fine. The clients that historically didn't — older Outlook versions using Word's rendering engine — have specific, narrower problems (mostly around margins, background images, and some CSS properties), not a blanket rejection of non-table markup. Table-izing every paragraph adds a lot of markup weight and makes the output harder to hand-edit, for a compatibility gain that mostly doesn't apply anymore outside of layout-critical sections.

If your use case is a highly stylized marketing email — multi-column layouts, background images behind text, precise pixel positioning — you'll still want a dedicated tool like MJML (more on that below). This tool is aimed at the more common case: turning a piece of Markdown-authored content (a newsletter issue, a docs update, a transactional notice) into clean, reliable email HTML without hand-coding it.

What Converts Cleanly

Headings — converted to <h1>–<h6> with inline font-size, weight, and color, using an Arial/Helvetica fallback stack (email clients have unreliable web font support, so system fonts are the safe default)
Bold, italic, strikethrough, inline code — straightforward inline styling
Paragraphs — inline margin/line-height for readable spacing
Links — inline-styled <a> tags, underlined, in a consistent brand color
Lists — bulleted and numbered, including nesting
Blockquotes — left border plus muted, italicized text
Fenced code blocks — monospace font on a shaded background, with white-space: pre-wrap instead of horizontal scrolling, since email clients handle scrollable regions inconsistently (some just clip the overflow)
Tables — inline-styled <th>/<td>, with column alignment preserved
Horizontal rules — a simple bordered <hr>-equivalent
Images — <img> tags with inline max-width: 100% so they scale on mobile

What to Watch Out For

Images need to be hosted somewhere public

This is the one that trips people up most. A Markdown image reference — whether it's a relative path (./chart.png), a local file, or embedded base64 data — needs to become an absolute URL pointing at a publicly reachable image host before it'll actually display in an inbox. Most email clients either strip data URIs entirely or don't resolve relative paths (there's no concept of "relative to this file" once your HTML is sitting in someone's inbox). Upload your images to your ESP's asset host, an S3 bucket, or wherever your site serves static assets, then swap in the absolute URL. Our converter flags this with a warning banner rather than silently producing broken image tags.

Outlook's rendering engine is a special case

Desktop Outlook (2007 through current versions, on Windows) doesn't use a browser engine to render HTML email — it uses Microsoft Word's layout engine. This is a long-standing, well-documented quirk of the email ecosystem, not something specific to any one converter. It means a handful of common CSS properties behave differently or are ignored outright: background images on tables often don't render, max-width is unreliable (which is part of why fixed pixel widths are still common in email templates), and margin/padding on certain elements can collapse unexpectedly. There's no way for a client-side converter to fully paper over this — vendor-specific conditional comments () are the traditional workaround, and they're a manual, Outlook-specific layer on top of otherwise-standard HTML. Don't expect pixel-perfect Outlook rendering from any automated Markdown-to-email conversion, ours included; test in Outlook specifically if that audience matters to you.

Dark mode can invert your colors unpredictably

A growing share of mail clients now apply automatic dark-mode processing to emails that don't explicitly declare their own dark-mode styles, and the results are inconsistent across clients — some invert colors, some leave images alone but darken backgrounds, some do nothing at all. If your palette depends on specific colors reading correctly (a light background behind dark text, for instance), it's worth testing in at least one dark-mode client before sending to a large list. This is a known limitation of the underlying HTML email ecosystem, not something a single converter fixes for you.

Task list checkboxes, raw HTML, Mermaid diagrams, and footnotes

Following the same pattern as our Notion and Slack converters, a few Markdown features don't have a clean email equivalent:

Task list checkboxes (- [ ]) render as plain ☑/☐ text characters, not interactive form controls — HTML checkboxes inside email are unreliable at best and blocked at worst
Raw HTML passed through your Markdown source keeps its tags but doesn't automatically get the inline-style treatment, since the converter only styles the elements it generates itself
Mermaid diagram fences are kept as plain, unstyled code blocks — no email client renders Mermaid, or JavaScript of any kind
Footnote references ([^1]) are left as literal text, since the parser doesn't expand them

Our tool shows a warning banner for each of these when it detects them in your source, the same pattern used across our other conversion tools.

Comparison: How People Actually Solve This

Approach	Best for	Tradeoff
Markdown to Email HTML converter (this tool)	Turning existing Markdown content into inline-styled HTML fast, no signup	Semantic-tag approach, not a full visual template builder
MJML	Building polished, multi-column marketing templates from scratch	You write MJML markup, not Markdown — a different authoring workflow, with a build step
Word's "paste from Markdown" / your ESP's rich text editor	One-off emails where you're comfortable manually formatting	No inline-CSS control, styling is whatever the editor's defaults are
Litmus / Email on Acid	Pre-send rendering verification across dozens of real email clients	Testing tools, not converters — you still need HTML to test
Hand-coding email HTML	Maximum control, pixel-perfect Outlook support	Slow, requires deep email-HTML expertise, easy to regress

For content that starts life as Markdown — a newsletter issue drafted the same way you'd draft any other doc, a changelog, a docs update you're also emailing to subscribers — the converter approach is the fastest path from draft to send-ready HTML. If you're building a highly designed, multi-column marketing template from scratch, MJML or a dedicated email design tool is still the better starting point. And regardless of which approach you use to generate the HTML, running it through Litmus or Email on Acid before a big send is the only real way to catch client-specific rendering surprises before your subscribers do.

Using the Converter

Our Markdown to Email HTML tool takes your Markdown on one side and gives you fully inline-styled HTML on the other, plus a rendered preview so you can sanity-check the result before you leave the page:

Paste Markdown in, get inline-styled HTML out — no <style> blocks or CSS classes anywhere in the output
Table-based structural shell (centered, 600px wide — the standard hand-coded email template width) around styled semantic content
Copy HTML button for pasting straight into your ESP's HTML block, plus a Download .html option
Rendered visual preview so you can check the result without needing to send a test email first
Warning banners for the specific gotchas above (image hosting, task-checkbox rendering, raw HTML, Mermaid, footnotes) so you know exactly what to double check before sending

No signup, no upload — everything runs in your browser.

Markdown to Email HTML converter — the tool this post covers
Markdown Across Platforms — how Markdown behaves across GitHub, Notion, Obsidian, and Confluence
Why Your Markdown Isn't Rendering — troubleshooting guide covering renderer-specific quirks like the ones in this post
Markdown to Word (DOCX): What Converts Cleanly and What Doesn't — the same "what survives conversion" framing, for a different output format

Markdown Style Guide: Common Mistakes and How to Catch Them

2026-07-17T00:00:00+00:00

Markdown is forgiving. Almost anything you type will render into something — which is exactly the problem. A skipped heading level, an image with no alt text, or a URL you forgot to wrap in link syntax will all render "fine" in your editor's preview, then quietly cause real problems once the document ships: broken screen-reader navigation, a table of contents that doesn't nest correctly, a link that looks wrong on a different platform.

None of these are syntax errors. Markdown doesn't have a compiler that stops you. That's exactly why linting matters — and why we built a Markdown Linter that checks for these issues in the browser, no setup required.

This post walks through the mistakes that actually show up in real documents, grouped by why they matter, with a before/after for each.

Why Markdown Style Mistakes Matter

Unlike a programming language, Markdown failures are usually silent. Three categories of consequence show up over and over:

Accessibility — screen readers rely on a logical heading structure and on alt text to describe images. Get either wrong, and you've made the document harder to use for anyone relying on assistive technology.
Structure and navigation — table-of-contents generators, doc-site sidebars, and "on this page" widgets all build their outline from your headings. A skipped level (H2 straight to H4) breaks that outline even though the page still looks normal.
Cross-renderer consistency — a bare URL, a code block missing its language tag, or trailing whitespace can render differently — or not at all — depending on whether the renderer is GitHub, a static site generator, or an internal wiki.

None of these show up as a red squiggly line while you're typing. You only find out when the rendered page looks wrong, or an accessibility audit flags it, or someone tells you the sidebar navigation skipped a section.

The 10 Rules, With Before/After Examples

Our Markdown Linter checks for 10 specific issues, split into one hard error and nine warnings. Here's what each one actually catches.

1. Heading hierarchy (error)

The only rule in the tool that's treated as an error rather than a warning, because it's the one most likely to break something structural, not just look untidy.

Headings should step down one level at a time. You can jump back up freely (H3 back to H2 is fine — that's just starting a new section), but you should never skip a level going down.

<!-- Bad: skips H2 entirely -->
# Getting Started
### Installation

<!-- Good -->
# Getting Started
## Installation

Why it matters beyond looks: screen readers let users jump between headings by level, and they announce the jump ("entering level 3 heading") — a skipped level is confusing out of context. Search engines and TOC generators use the same hierarchy to build page outlines, so a skip can produce a lopsided or broken outline even though the text itself reads fine.

2. Multiple H1s

A document should have exactly one H1 — the page title. A second H1 partway through usually means someone meant to use H2.

<!-- Bad -->
# My Guide
Some intro text.
# Advanced Topics

<!-- Good -->
# My Guide
Some intro text.
## Advanced Topics

3. Duplicate headings

The same heading text appearing twice in one document — often from copy-pasting a section as a template for a new one and forgetting to rename it.

<!-- Bad -->
## Configuration
...
## Configuration

This matters for anchor links specifically: most renderers generate a heading's URL fragment (#configuration) from its text, so the second "Configuration" heading either silently gets a suffixed slug (#configuration-1) that nobody linked to on purpose, or overwrites the first one's anchor depending on the renderer — either way, a link meant for the first section can land on the wrong one.

4. No language on fenced code blocks

A ``` fence with no language identifier after it loses syntax highlighting and, on some platforms, loses the copy-button / line-numbering features that are tied to language detection.

<!-- Bad -->
```
function greet(name) {
  return `Hello, ${name}`;
}
```

<!-- Good -->
```javascript
function greet(name) {
  return `Hello, ${name}`;
}
```

5. Bare URLs

A plain URL sitting in text, not wrapped in [text](url) link syntax.

<!-- Bad -->
See https://example.com/docs/api-reference for details.

<!-- Good -->
See the [API reference](https://example.com/docs/api-reference) for details.

Some renderers auto-linkify bare URLs (GitHub does); others don't, and you end up with dead-looking plain text. Even where auto-linking works, a long raw URL is worse for readability and worse for screen readers, which read out the entire URL character by character instead of a meaningful label.

6. Missing alt text

An image reference with empty alt text — ![]() instead of ![description](...).

<!-- Bad -->
![](chart.png)

<!-- Good -->
![Bar chart showing monthly signups from January to June](chart.png)

This is the single highest-impact accessibility fix on this list. Screen reader users get nothing at all from an image with empty alt text — not even a filename fallback in most cases. It's also one of the easiest mistakes to make, since a missing alt attribute doesn't change how the image looks to a sighted reader.

7. Hard tabs for indentation

A line indented with a literal tab character instead of spaces.

Hard tabs render inconsistently — different editors and renderers expand a tab to a different number of spaces (commonly 4 or 8), so indentation-sensitive content like nested lists can shift alignment depending on where it's viewed. Most Markdown style guides (including markdownlint's defaults) require spaces for exactly this reason.

8. Trailing whitespace

Whitespace at the end of a line. This is a genuinely dangerous one because Markdown gives exactly two trailing spaces special meaning: it forces a line break within a paragraph. One trailing space (or three, or an odd number) does nothing visible in most editors, so it silently changes rendering behavior in a way you won't notice until you inspect the raw output. (The linter is deliberately careful here — it only flags true trailing whitespace, not the intentional two-space line-break convention.)

9. Multiple consecutive blank lines

More than one blank line between blocks. Markdown collapses any run of blank lines down to a single paragraph break during rendering, so extra blank lines have zero visual effect — they're pure noise in the source that makes diffs longer and documents harder to scan in an editor.

10. Line length

A prose line longer than 120 characters. Code blocks are excluded from this check, since code often has legitimate reasons to run long (and it's usually monospaced and horizontally scrollable in rendered output anyway).

Long prose lines aren't a rendering problem — Markdown reflows paragraphs regardless of source line length — but they're a diff problem. In a docs-as-code workflow where changes are reviewed as Git diffs, a one-word edit to a 400-character line shows the entire line as changed, making the actual edit hard to spot in review.

In-Browser Linting vs. CI Pipeline Linting

If you've read our docs-as-code workflow guide, you already know about markdownlint and Vale — the standard tools for enforcing Markdown style in CI. Those are the right tools for a real docs pipeline: they run on every pull request, they're configurable per-project, and Vale in particular goes beyond structure into prose style (banned phrases, terminology consistency, passive voice).

Our Markdown Linter isn't a replacement for that setup — it's the fast check before you get anywhere near a pull request. Paste a document, get instant feedback, no npm install, no config file, no CI run to wait on. It's useful in a few specific situations a CI pipeline doesn't cover well:

Reviewing someone else's Markdown you don't have local tooling set up for — paste it and check in seconds
Before pasting into a CMS or wiki that doesn't run any linting at all, where structural issues silently affect SEO and accessibility with no safety net
Quick self-review while drafting, before you've even opened a terminal
Teaching or onboarding — showing someone exactly what "broken heading hierarchy" looks like, with immediate before/after feedback, rather than pointing them at a CI log

Think of it as the same relationship a linter extension in your editor has to your project's full CI test suite: faster feedback, narrower scope, and no substitute for the real pipeline once the stakes are high enough to need one.

Try It

Paste your Markdown into the Markdown Linter and you'll get line-numbered results, color-coded by severity, updating as you type. No signup, nothing leaves your browser.

Markdown Linter tool — check your Markdown for these 10 issues instantly
Markdown for Technical Writers: The Docs-as-Code Workflow Guide — markdownlint and Vale in a CI pipeline
Why Your Markdown Isn't Rendering — troubleshooting guide for renderer-specific formatting failures
Markdown Across Platforms — how the same Markdown behaves differently on GitHub, Notion, Obsidian, and Confluence

Markdown to Slack Formatting: What Actually Works (mrkdwn Explained)

2026-07-10T00:00:00+00:00

If you've ever pasted a chunk of Markdown into Slack expecting headings and tables to show up nicely, you've already learned the hard way: Slack doesn't speak Markdown. It has its own lookalike format called mrkdwn (yes, missing the "a" — that's the actual name Slack uses in its own API docs), and it diverges from standard Markdown in ways that are easy to get wrong.

This guide covers the full syntax mapping, what Slack simply can't render, and the gotcha that trips up most people building bots or webhooks: the difference between typing in the Slack message box and sending mrkdwn through the API.

Markdown vs. Slack's mrkdwn

The two syntaxes look similar at a glance, but several common Markdown conventions use different characters in Slack — and a few have no equivalent at all.

Formatting	Markdown	Slack mrkdwn
Bold	`bold`	`bold`
Italic	`italic` or `_italic_`	`_italic_`
Strikethrough	`~~strike~~`	`~strike~`
Inline code	`code`	`code` (same)
Code block	```code```	```code``` (same)
Blockquote	`> quote`	`> quote` (same, one level only)
Link	`[text](url)`	`<url\|text>`
Heading	`# Heading`	No native heading — use bold instead
Unordered list	`- item`	`• item` (see notes below)
Ordered list	`1. item`	Not auto-numbered — type numbers manually
Horizontal rule	`---`	Not supported in message text
Table	`\| a \| b \|`	Not supported at all
Image	`![alt](url)`	Not supported inline

The single asterisk for bold is the one that catches people most often — it's the exact opposite of standard Markdown, where a single asterisk means italic. Type *this* in Slack and you'll get bold, not italics.

The Trap: Typing in Slack vs. Sending via API

Here's the detail that most guides skip, and the one that matters most if you're building a bot, webhook, or CI notification: Slack's message composer and Slack's API don't behave identically.

When you type directly into the Slack message box, the client does some helpful auto-formatting as you go — typing - at the start of a line converts it to a bullet, and typing 1. will auto-number subsequent lines while you're actively editing. This is a composer-only convenience.

When you send text programmatically — via chat.postMessage, an incoming webhook, or a Block Kit mrkdwn text object — none of that auto-formatting happens. A literal - item sent through the API renders as the literal characters - item, not a bullet. If you want real bullets from a bot or script, you need to insert the actual bullet character (•, Option+8 on Mac, or the Unicode character U+2022) yourself, or build proper Block Kit list structures. The same applies to numbered lists — the API will not auto-number 1. / 2. / 3. for you.

If your Markdown-to-Slack workflow runs through automation (a Git-to-Slack notifier, a changelog bot, a CI pipeline), test the actual API output, not just what you see typing manually in a channel.

What Doesn't Convert

Headings

Slack's mrkdwn has no heading syntax at all — no #, no font-size levels. The only way to get a "heading" look in an ordinary message is to bold the line: *Section Title*. If you're using Block Kit (Slack's structured message format for apps and bots), there's a dedicated header block type, but that's a separate block, not something you write inline in mrkdwn text.

Tables

There is no table support in Slack messages — not in mrkdwn, and not in standard Block Kit blocks either. If your Markdown source has tables, you have a few options: convert the table to a formatted list, use Block Kit's fields array in a section block to fake a rough two-column layout, or drop the table and link out to the full document instead. There is no clean equivalent, so if tables matter, don't rely on message text at all.

Images

![alt](url) doesn't render inline. Slack ignores the syntax entirely and shows it as literal text. To actually display an image in Slack, you need a separate image block in Block Kit, or you paste the image file itself into the channel. A Markdown image reference converted straight to Slack text will just look broken — most conversion tools (including ours) strip the image markup and keep the alt text so at least the description survives.

Nested Lists

Slack doesn't have a native concept of list nesting depth in mrkdwn. Manually indenting with spaces before a bullet character will usually render with some visual indentation in the client, but it's not a documented, reliable feature — behavior has changed across Slack client versions. If nesting matters for readability, consider flattening to a single level with prefixes (Frontend: Component X) rather than depending on indentation.

Horizontal Rules

--- has no special meaning in Slack message text — it renders as three literal dashes. The closest equivalent in Block Kit is the divider block, which is a structural element, not something you can type inline.

Footnotes, Definition Lists, Task Lists

None of these have any Slack equivalent. Footnote references ([^1]) show up as literal bracket text. Task list checkboxes (- [ ]) render as literal text — Slack has no native inline checkbox in message text (interactive checkboxes exist only as Block Kit UI elements requiring an app, not plain-text formatting).

HTML

Slack strips or ignores raw HTML in message text entirely. If your Markdown source has embedded HTML for layout tricks, none of it will survive — plan on it disappearing.

Escaping Characters for API Use

If you're sending mrkdwn through the API rather than typing manually, three characters need HTML-entity escaping because they have special meaning in Slack's format (particularly < and >, which wrap links):

Character	Escape as
`&`	`&`
`<`	`<`
`>`	`>`

Skip this and a message containing a literal < or > — say, example code like if (x < y) — can get mangled or silently dropped, since Slack tries to parse it as the start of a link tag.

Quick Reference

Markdown feature	Slack support	What happens
Bold / italic / strikethrough	Yes	Different characters (see table above)
Inline code / code blocks	Yes	Same backtick syntax
Blockquote	Partial	Works, single level only
Links	Yes	Different syntax: `<url\|text>`
Headings	No	Falls back to bold text
Tables	No	No equivalent, renders as broken text
Images	No	Ignored inline; needs a separate Block Kit block
Ordered/unordered lists	Partial	Composer auto-formats; API does not
Nested lists	No	Unreliable, client-dependent indentation only
Horizontal rule	No	Renders as literal dashes
Footnotes, definition lists, task lists	No	No equivalent
HTML	No	Stripped

Using the Converter

Our Markdown to Slack converter handles the mechanical parts of this conversion automatically:

Converts **bold** to *bold* and italics to _italic_
Converts ~~strikethrough~~ to ~strikethrough~
Converts headings to bold text (since Slack has no heading syntax)
Converts [text](url) links to Slack's <url|text> format
Strips image Markdown while keeping the alt text so the description isn't lost
Removes horizontal rules
Shows a warning badge if it detects a table in your source, since Slack can't render it
Protects code blocks and inline code from being touched by the other conversions

Paste your Markdown on the left and get Slack-ready mrkdwn on the right, with a side-by-side comparison so you can see exactly what changed. No signup required.

This is especially useful for release notes, changelog summaries, or documentation excerpts you're pasting into a channel — the kind of content that's authored in Markdown but consumed in Slack.

Markdown to Slack converter — real-time conversion, no signup required
Markdown Across Platforms — how Markdown behaves across GitHub, Notion, Obsidian, and Confluence
Why Your Markdown Isn't Rendering — troubleshooting guide covering renderer-specific quirks like this one
Markdown to Jira Wiki Markup — the same kind of syntax-mapping problem, different tool
Markdown for Notion — what converts cleanly (and what doesn't) when moving Markdown into Notion

Markdown to Word (DOCX): What Converts Cleanly and What Doesn't

2026-07-03T00:00:00+00:00

Markdown is great until someone who doesn't use Markdown needs to read your document. A legal team wants track changes. A client wants a Word file they can comment on. A stakeholder wants something they can print and mark up with a pen. None of these people are going to install a Markdown viewer, and pasting raw **bold** asterisks into an email is not a good look.

This is the most common reason technical teams end up converting Markdown to Word: not because Word is a better writing tool, but because it's the format everyone else already has open.

This guide covers what actually happens when you make that conversion — what comes through clean, what gets lossy or breaks outright, and which conversion method to reach for depending on your situation.

Why People Need Markdown to Word

A few recurring scenarios:

Non-technical stakeholders — product managers, executives, clients — who live in Word and Google Docs, not Git and Markdown editors
Legal and compliance review — redlines, track changes, and signature workflows are built around .docx, not diffs
Print and physical review — some reviewers still want a printed page with a red pen, and Word's print layout is more predictable than a browser print dialog
Formal deliverables — proposals, contracts, and reports that need to look like a "real document," complete with headers, page numbers, and a title page
Handoff to teams outside engineering — marketing, sales, and HR often maintain their own copies of documentation in Word because that's the tool their org standardizes on

If you're writing in Markdown because it's fast, version-controllable, and diff-friendly, but the last step of the workflow needs to land in someone else's inbox as a .docx, you need a reliable conversion path — and "reliable" is doing a lot of work in that sentence, because Word's formatting model doesn't map onto Markdown's the way you'd hope.

What Converts Cleanly

The core of Markdown — the stuff that maps directly onto Word's built-in styles — converts well across every method covered below:

Headings (# through ######) → Word's Heading 1–6 styles, which means your table of contents will auto-generate correctly if the target app supports it
Bold and italic (**bold**, *italic*) → Word's native bold/italic character formatting
Unordered and ordered lists → Word list styles, including basic nested lists (one or two levels deep)
Tables (with a proper separator row) → real Word tables, not just formatted text — you can resize columns and apply table styles afterward
Links ([text](url)) → clickable hyperlinks
Images (![alt](path)) → embedded images, provided the path resolves (see below)
Blockquotes → Word's Quote or Intense Quote paragraph style, depending on the converter
Horizontal rules (---) → a page-break-like divider line

For a straightforward prose document — headings, paragraphs, a few lists, maybe a table — any of the methods below will get you a usable Word file with minimal cleanup.

What's Lossy or Breaks

This is where it gets interesting, because "Markdown to Word" isn't a lossless round trip in either direction. Several Markdown features have no real equivalent in Word's document model.

Syntax-Highlighted Code Blocks

Word has no concept of a "code block with syntax highlighting." A fenced code block like:

```python
def hello():
    print("Hello, world!")
```

becomes, at best, monospaced text in a gray-shaded box with no color coding — Pandoc does this reasonably well with its --highlight-style option. At worst, with a naive converter, you get default-font text with the language tag (python) left dangling above it as plain text. If your document is full of code samples, expect to spend time manually reapplying a "Code" character style after conversion, or accept that the code will just look like indented text.

Footnotes

Markdown footnotes ([^1] with a corresponding [^1]: definition) map onto Word's native footnote/endnote system reasonably well if your converter supports it — Pandoc does. Weaker converters either drop the footnote marker entirely or dump the footnote text inline at the point of reference, which reads strangely and loses the actual footnote formatting (small superscript number, bottom-of-page text).

Nested Lists

Markdown handles nested lists with indentation, and in theory this maps to Word's multilevel list styles. In practice, list nesting is one of the most fragile parts of any Markdown-to-anything conversion. Watch for:

Inconsistent indentation width getting collapsed to the wrong nesting level
Mixed ordered/unordered nested lists (a numbered list inside a bulleted one) losing their list type on conversion
List numbering restarting unexpectedly when a code block or paragraph interrupts a list

If your source Markdown has three or more levels of nesting, check the converted document by hand — this is the single most common thing that needs manual fixing after conversion.

YAML Frontmatter

If your Markdown source starts with frontmatter like:

---
title: Q3 Planning Doc
author: Jane Smith
date: 2026-07-01
---

Word has no frontmatter concept. Depending on the converter, this either gets dropped silently (best case), or it renders as a literal block of title: Q3 Planning Doc text at the top of the document (worse case). Strip frontmatter before converting, or use a tool that recognizes and removes it automatically.

Mermaid Diagrams

A fenced ```mermaid block is diagram source code — a description of a flowchart or sequence diagram, not the diagram itself. Word cannot render Mermaid. On conversion, you'll get the raw Mermaid syntax printed as plain text, which is meaningless to a Word reader. If your document depends on diagrams, render them to PNG or SVG images first and embed the images, or accept that the Word version needs manual diagram insertion.

GitHub-Style Alerts

GitHub Flavored Markdown alerts like:

> [!WARNING]
> This endpoint is deprecated and will be removed in v3.

render as colored, icon-labeled callout boxes on GitHub, but there's no equivalent block-quote-with-icon primitive in standard Markdown-to-Word conversion. You'll typically get a plain block quote with the literal text [!WARNING] still sitting in it. If the alert type matters for your reader, convert it to plain prose ("Warning: This endpoint is deprecated...") before converting to Word, since Word's Quote style alone doesn't communicate severity the way a colored GitHub alert does.

Task List Checkboxes

Markdown checkboxes (- [ ] and - [x]) are interactive in GitHub, GitLab, and Notion. In Word, they typically convert to plain bullet points with a literal ☐ or ☒ character, or sometimes just the raw [ ] text — not an actual clickable/checkable Word content control. If you need genuinely interactive checkboxes in the Word file, you'll need to insert Word's native checkbox content controls manually after conversion; nothing on the Markdown side of the pipe maps to them automatically.

Quick Reference

Markdown feature	Converts cleanly?	What happens
Headings	Yes	Maps to Word Heading styles
Bold, italic	Yes	Native character formatting
Lists (1–2 levels)	Yes	Native list styles
Tables	Yes	Real, editable Word tables
Links	Yes	Clickable hyperlinks
Images (resolvable paths)	Yes	Embedded images
Blockquotes	Yes	Quote paragraph style
Code blocks	Partial	Monospace text; syntax highlighting depends on converter
Footnotes	Partial	Works with Pandoc; weaker tools inline or drop them
Deeply nested lists (3+ levels)	Partial	Often collapses or misnumbers
YAML frontmatter	No	Dropped or rendered as literal text
Mermaid diagrams	No	Renders as raw diagram source text
GitHub-style alerts	No	Becomes a plain block quote
Task checkboxes	No	Becomes plain bullets, not interactive controls

Comparing Conversion Approaches

There isn't one "correct" way to do this conversion — the right tool depends on how much control you need and how technical your workflow is.

Pandoc (Command Line)

Pandoc is the standard for this conversion and the engine behind most "Markdown to Word" tools you'll find, including several of the online converters below. Running:

pandoc input.md -o output.docx

gets you a solid baseline conversion with good table, footnote, and list support. The real power is in customization — you can supply a reference .docx file with --reference-doc=template.docx so the output inherits your organization's fonts, heading styles, and margins instead of Pandoc's plain defaults. This is the best option if you're generating Word documents as part of an automated pipeline (say, a GitHub Action that builds a .docx release artifact from your docs repo) or if you need precise control over the output styling.

The tradeoff: it's a command-line tool. Someone on your team needs to install it, and it's not something you hand to a non-technical stakeholder who just wants to paste some Markdown and get a file.

Word's Own Paste-from-Markdown

Recent versions of Microsoft Word (365) can autodetect Markdown formatting when you paste plain text — typing or pasting **bold** and having Word convert it to actual bold as you type, similar to how it autoformats a line starting with 1. into a numbered list. This only works for the most basic syntax (bold, italic, headings via #, simple lists) and is inconsistent between Word versions and platforms (desktop vs. web vs. Mac). It doesn't handle tables, code blocks, or anything more complex than inline formatting. Useful for a quick one-paragraph paste; not a real conversion pipeline.

Online Converters

Web-based converters (many of them Pandoc running server-side behind a simple upload form) are the path of least resistance for a one-off conversion — no installation, paste or upload, download a .docx. The tradeoffs are the usual ones for any "paste your content into a random website" tool: check what happens to your data (does it get stored, logged, or used for anything?), and be aware that free tiers often add limits on file size or strip formatting to encourage a paid upgrade.

Our Markdown to Word Converter

We're building a Markdown to Word (DOCX) converter that handles the common case — paste your Markdown, get a clean .docx — without a command-line tool or an account. Like our other conversion tools (Markdown to Confluence, Markdown to Notion), the goal is to handle the lossy edge cases explicitly rather than silently mangling them: frontmatter gets stripped with a warning instead of dumped as literal text, GitHub-style alerts get flattened into labeled block quotes instead of leaving [!WARNING] sitting in the output, and Mermaid blocks get flagged so you know to replace them with an image rather than discovering a wall of diagram syntax after you've already emailed the file to a client.

If you need reference-template styling or a scripted pipeline, Pandoc is still the right tool. If you want a fast, no-install way to hand someone a Word doc, that's what we built this for.

A Practical Workflow

For anything beyond a quick one-off paste, this order of operations avoids most of the pain described above:

Strip or note frontmatter before converting — decide if any of it (title, author, date) should become part of the Word document's actual title page instead of just disappearing.
Render diagrams to images first. Don't let Mermaid or other diagram syntax hit the converter as text.
Flatten GitHub-style alerts into plain, clearly-labeled text if the distinction between "note" and "warning" matters to your reader.
Check nested lists by hand after conversion — this is the highest-probability place for something to look wrong.
Reapply a template or style set in Word if you need consistent branding (fonts, headers, margins) — most converters, ours included, produce well-structured but plainly-styled documents, and matching your organization's house style is a separate step.

If you're dealing with Markdown across multiple destinations, not just Word, these guides cover related ground:

Markdown Across Platforms: What Actually Works in GitHub, Notion, Obsidian, and Confluence — the same "what converts cleanly" treatment for other platforms
Why Your Markdown Isn't Rendering: A Troubleshooting Guide — if your Markdown is breaking somewhere other than a Word export
Markdown for Technical Writers: The Docs-as-Code Workflow Guide — for teams trying to keep Markdown as the source of truth while still producing Word deliverables downstream
How to Convert Word Documents to Markdown — the reverse direction, if you're pulling content out of Word and into a Markdown-based workflow

And when you're ready to convert, try the Markdown to Word (DOCX) converter — paste your Markdown, get a clean Word document, no installation required.

Markdown for Notion: What Actually Works and What Doesn't

2026-06-26T00:00:00+00:00

Notion markets itself as Markdown-friendly, and for basic formatting it mostly is. But spend enough time moving documents between Notion and the rest of your toolchain and you'll hit the edge cases: frontmatter that renders as prose, tables that become databases, Mermaid diagrams that become plain text, and HTML that disappears entirely.

This is a guide to what actually happens — not what the docs say should happen.

How Notion Handles Markdown Input

Notion has three different ways to get Markdown in, and they don't all behave the same:

Method	Best for	Reliability
Paste	Short snippets, quick formatting	Medium — tables and code blocks often break
File import (drag .md file)	Full documents, preserved structure	High — most reliable option
`/markdown` slash command	Pasting a block of Markdown text	Medium — same caveats as paste

File import is more reliable than paste. When you paste Markdown, Notion processes it in real time, which can produce odd results with complex tables and fenced code blocks. Dragging a .md file into the sidebar triggers Notion's dedicated importer, which handles the format more consistently.

What Converts Cleanly

These elements survive the trip from Markdown to Notion reliably:

Headings (#, ##, ###) → Notion heading blocks (H1, H2, H3)
Bold and italic (**bold**, *italic*) → rich text formatting
Inline code (`code`) → inline code formatting
Fenced code blocks with language labels → Notion code blocks with syntax highlighting
Unordered lists (-, *) → bulleted list blocks
Ordered lists (1., 2.) → numbered list blocks
Checkboxes (- [ ], - [x]) → to-do blocks
Links ([text](url)) → hyperlinks
Blockquotes (>) → Notion quote blocks
Horizontal rules (---) → divider blocks

For plain prose documents, Notion is actually solid. The problems start with the more complex elements.

What Breaks or Gets Transformed

YAML Frontmatter

Notion has no concept of frontmatter. If your document starts with:

---
title: My Document
date: 2026-06-26
---

Notion imports this as plain text — the dashes become a divider block, and title: My Document renders as a heading or prose depending on context. If you're importing docs that have frontmatter, strip it before importing, or use our Markdown to Notion converter, which removes frontmatter automatically and warns you what was stripped.

Tables

Tables are the trickiest part. Notion renders them differently depending on context:

In the body of a page, a Markdown table becomes a simple inline table (not a database)
When imported via file, tables often become Notion databases with property columns
If the separator row is missing (|---|---|), the table may just render as pipe-separated text

Notion is strict about the GFM table format. Missing or malformed separator rows reliably break table rendering.

What Notion tables don't support:

Column alignment (:---: / ---: is ignored)
Multi-line cells
Colspan or rowspan

Images

Image syntax (![alt](url)) works for external URLs. If your images use relative paths (e.g., ![chart](./images/chart.png)), they'll break — Notion can't resolve relative filesystem paths. Convert relative paths to absolute URLs before importing.

HTML

Notion strips HTML entirely. Any <div>, <span>, <details>, <summary>, or other HTML elements in your Markdown will disappear on import. If you're using HTML for collapsible sections, badges, or custom alignment, those won't survive.

Mermaid Diagrams

Notion does not render Mermaid diagrams. A fenced code block tagged with mermaid will import as a plain code block containing the diagram source — not a rendered diagram. This trips people up because GitHub, GitLab, and several documentation tools do render Mermaid natively.

If you have Mermaid diagrams, your options are: export them as images and embed, or use Notion's native embed integration (which requires a third-party service).

Footnotes

Standard Markdown footnote syntax ([^1]) isn't supported by Notion. On import, footnote references typically disappear and the footnote definitions render as plain text at the bottom of the page. Our converter inlines footnotes — replacing [^1] references with the footnote text in italics — which is the most readable fallback.

GitHub-Style Alerts

GitHub Flavored Markdown alerts like:

> [!NOTE]
> This is an important note.

...render in GitHub as styled callout boxes, but Notion imports them as plain blockquotes. The [!NOTE] text appears literally in the quote. In newer Notion workspaces you can manually convert the blockquote to a callout block after import, but it's a manual step.

Exporting Markdown from Notion

Notion's export (Page → Export → Markdown & CSV) produces reasonable Markdown, but with quirks to know about:

Tables export as CSV files — not inline Markdown tables. If your page contains a database, the export creates a separate .csv file and links to it from the Markdown. This roundtrip doesn't work well for docs-as-code workflows where you expect embedded tables.

Internal page links export as full Notion URLs — not relative paths. An internal link to another Notion page becomes something like [Page Title](https://www.notion.so/workspace/abc123...). These links break when you move content out of Notion.

Callout blocks export as blockquotes with the emoji prepended as plain text.

Nested pages export as subdirectories. The folder structure maps to page hierarchy, which is useful if you want to mirror the Notion structure but inconvenient if you want a flat directory.

Whitespace in exported tables includes trailing spaces for column alignment. Most parsers handle this fine, but some produce artifacts.

Notion API and Markdown

If you're using the Notion API to create or update pages programmatically, you can't POST Markdown directly. The API uses Notion's own block format — each heading, paragraph, list item, and code block is a separate JSON object. You need to convert Markdown to block format before posting.

This matters for teams automating documentation workflows: syncing a Git repo to Notion, generating pages from templates, or importing content on a schedule. The Notion API is capable, but it expects its own block format, not Markdown strings.

Quick Reference: Import Compatibility

Markdown feature	Imports correctly?	Notes
Headings H1–H3	Yes
Bold, italic	Yes
Inline code	Yes
Fenced code blocks	Yes	Language labels preserved
Unordered / ordered lists	Yes
Checkboxes	Yes
Links	Yes
Blockquotes	Yes
Tables (with separator row)	Mostly	No alignment, colspan
YAML frontmatter	No	Renders as prose / divider
Images (relative paths)	No	Absolute URLs only
HTML	No	Stripped entirely
Mermaid diagrams	No	Renders as plain code block
Footnotes	No	Definitions appear as text
GitHub-style alerts	Partial	Renders as plain blockquote

Using the Converter Tool

If you're regularly moving content into Notion, our Markdown to Notion converter handles the pre-processing:

Strips YAML frontmatter (with a warning listing what was removed)
Inlines footnotes as italic text inline with the reference
Converts GitHub-style alerts to labeled blockquotes
Removes HTML tags (with a warning)
Flags Mermaid diagrams so you can handle them manually

Paste your Markdown on the left, get Notion-ready Markdown on the right. No signup required.

Markdown to Notion converter — cleans up Markdown before importing
Markdown Across Platforms — how Markdown behaves in GitHub, Obsidian, Confluence, and more
Obsidian vs Notion vs Roam Research — which note-taking tool fits your workflow
Markdown in Confluence — the same treatment for Confluence users
HTML to Markdown — extract Markdown from Notion's HTML export

Obsidian Plugins for Developers: The Essential Setup (2026)

2026-06-26T00:00:00+00:00

Obsidian's plugin ecosystem has over 1,500 community plugins. Most of them are noise. After spending two years using Obsidian as a developer's second brain — for architecture notes, runbooks, incident retrospectives, and project planning — these are the ones I'd install on a fresh vault today.

This guide covers plugins that are genuinely useful for software developers specifically, not general note-taking plugins that any knowledge worker might use.

The short list

If you're in a hurry, install these seven and you'll be well set up:

Plugin	What it does
Dataview	Query your notes like a database
Templater	Powerful templates with JavaScript
Obsidian Git	Auto-sync vault via Git
Code Block Enhancer	Copy button, language badges on code blocks
Advanced Tables	Spreadsheet-style table editing
Tasks	Track to-dos across your entire vault
Linter	Keep Markdown consistent and clean

Read on for installation tips, configuration, and the use cases each one handles best.

1. Dataview — query your vault like a database

Dataview is the most powerful plugin in the Obsidian ecosystem. It lets you write SQL-like queries over your notes, pulling in data from YAML frontmatter and inline fields.

Install: Community plugins → search "Dataview"

Why developers love it

You can build dashboards that automatically populate from your notes. A few real examples:

All open tasks tagged #backend created this week:

```dataview
TASK FROM #backend
WHERE !completed AND file.ctime >= date(today) - dur(7 days)
```

List of all architecture decisions (ADRs) in the decisions/ folder:

```dataview
TABLE file.ctime AS "Created", status, context
FROM "decisions"
SORT file.ctime DESC
```

A dashboard of all projects with their status from frontmatter:

```dataview
TABLE status, stack, last-updated
FROM "projects"
WHERE status != "done"
SORT last-updated DESC
```

Configuration tips

Enable JavaScript queries in Dataview settings — this unlocks dataviewjs blocks where you can write arbitrary JS against your vault data. It's what separates useful queries from genuinely powerful ones.

2. Templater — templates that actually do things

The core Templates plugin is fine for static snippets. Templater is what you reach for when you want templates that run code.

Install: Community plugins → search "Templater"

Developer-specific use cases

New ADR template — auto-populates the date and a sequential number:

---
title: <% tp.file.title %>
date: <% tp.date.now("YYYY-MM-DD") %>
status: proposed
---

## Context

## Decision

## Consequences

New incident retrospective — prompts for severity and affected service:

---
date: <% tp.date.now("YYYY-MM-DD") %>
severity: <%* tR += await tp.system.prompt("Severity (P0/P1/P2)?") %>
service: <%* tR += await tp.system.prompt("Affected service?") %>
---

## Timeline

## Root cause

## Action items
- [ ]

New daily note — pulls in incomplete tasks from yesterday:

# <% tp.date.now("dddd, MMMM D") %>

## Carry-forward
<%* 
const yesterday = tp.date.now("YYYY-MM-DD", -1)
const yNote = app.vault.getAbstractFileByPath(`daily/${yesterday}.md`)
// add your task extraction logic here
%>

## Today's focus

## Notes

Configuration tips

Set the template folder in Templater settings (I use _templates/)
Enable Trigger Templater on new file creation so templates auto-run when you create a note from a template
Bind a hotkey to Templater: Open Insert Template modal — I use Ctrl+T

3. Obsidian Git — vault version control

Obsidian Git syncs your vault to a Git repository automatically. For developers, this is the obvious choice over Obsidian Sync: you get full version history, branching, and you own your data.

Install: Community plugins → search "Obsidian Git"

Setup for developers

Init a Git repo in your vault folder: git init && git remote add origin <your-repo-url>
Install the plugin and set Auto-pull interval (I use 10 minutes) and Auto-push after auto-commit to on
Set a Commit message template — I use vault: {{date}} auto-commit

What it gives you

Full git log on your notes — see exactly when you changed an idea
Branch your vault for major projects (e.g., feature/q3-planning)
Team shared vaults via a private repo — though Obsidian Sync is smoother for real-time collaboration
Backup without a subscription fee

Caveat: Sync conflicts when editing from multiple devices simultaneously are painful. If you need seamless multi-device sync, combine Obsidian Sync with Git for backup only, or use iCloud/Dropbox and accept the occasional conflict.

4. Code Block Enhancer — make code blocks developer-friendly

The default Obsidian code block experience is minimal: no copy button, no language badge, no line numbers. Code Block Enhancer adds all of this with zero configuration.

Install: Community plugins → search "Code Block Enhancer"

After installing, every code block gets:

A copy button in the top-right corner
A language badge (shows the syntax language)
Optional line numbers (enable in settings)

It's a tiny plugin that makes a disproportionate difference when your vault is full of shell commands, SQL snippets, and configuration examples.

5. Advanced Tables — actual table editing

Markdown tables are famously painful to type. Advanced Tables turns them into a spreadsheet-style experience.

Install: Community plugins → search "Advanced Tables"

What it does

Press Tab to move between cells (auto-aligns the table)
Press Enter to add a new row
Sort columns, add/delete rows and columns via a right-click menu
Auto-formats the pipe characters so the raw Markdown is readable

For developers writing documentation, ADRs, or capability matrices, this is essential. Before Advanced Tables, I would export tables from a spreadsheet and paste them in. Now I write them directly.

Alternative: use our table tools

If you're building a table from data that's already in a spreadsheet or CSV:

Google Sheets → Markdown — paste a spreadsheet selection
Excel → Markdown — upload an .xlsx file
CSV → Markdown — paste CSV data

6. Tasks — cross-vault task tracking

Tasks extends Obsidian's native - [x] task syntax with due dates, recurrence rules, priorities, and cross-file queries.

Install: Community plugins → search "Tasks"

Syntax you get

- [ ] Write runbook for new deployment process 📅 2026-07-01 ⏫
- [ ] Review PR from @alice 📅 2026-06-28 🔁 every week
- [x] Update dependencies ✅ 2026-06-25

Dashboard query

Put this in a dedicated tasks.md file to see everything due this week:

```tasks
not done
due before in 7 days
group by due
sort by priority
```

For developers who live in Obsidian and want to track project work without switching to Jira/Linear/Trello, Tasks is a solid alternative. The lack of real-time collaboration is the main limitation.

7. Linter — keep your Markdown consistent

Linter automatically fixes common Markdown style issues on save: trailing spaces, inconsistent heading levels, missing blank lines around headings, duplicate headings, and more.

Install: Community plugins → search "Linter"

Why this matters for developers

If you publish from Obsidian (to a Jekyll blog, MkDocs site, or GitHub wiki), consistent Markdown saves you debugging time. Malformed tables, missing blank lines, and inconsistent heading hierarchies can break renderers in ways that are hard to diagnose.

Configure Linter to auto-fix on save (Settings → Linter → Lint on save), and set the rules that matter to your publishing target. For Jekyll/GitHub Pages, I always enable:

YAML frontmatter formatting
Heading levels increment by one
No trailing spaces
Proper blank lines around code blocks

Want to check Markdown quality before pushing? Try our Markdown Linter tool — same rules, no plugin required.

Honorable mentions

These didn't make the essential list but are worth knowing about:

Excalidraw (excalidraw-plugin) — embed whiteboard diagrams directly in notes. Useful for architecture sketches that live next to the ADR they explain.

Kanban (obsidian-kanban) — Trello-style boards inside Obsidian. Each card is a Markdown note. Good for sprint planning if you prefer staying in Obsidian.

Local REST API (obsidian-local-rest-api) — exposes your vault via a local HTTP API. Lets you build scripts that read/write notes from the command line or automate note creation from external tools.

Shell Commands (obsidian-shellcommands) — run shell commands from Obsidian's command palette. I use this to open the current note's folder in Terminal and to run git pull on demand.

Iconize — add emoji or icon prefixes to folder names in the sidebar. Trivial, but makes the vault faster to navigate when you have 20+ folders.

Recommended vault structure for developers

A folder structure that works well with Dataview:

vault/
├── _templates/          # Templater templates
├── daily/               # Daily notes (YYYY-MM-DD.md)
├── projects/            # One folder per project
│   └── project-name/
│       ├── README.md    # Project overview with frontmatter status
│       ├── decisions/   # ADRs
│       └── retros/      # Incident retrospectives
├── reference/           # Long-lived reference docs
│   ├── runbooks/
│   └── architecture/
├── inbox/               # Quick capture, triage weekly
└── tasks.md             # Dataview task dashboard

Frontmatter for project notes:

---
title: Project Alpha
status: active   # active | paused | done
stack: [Node.js, PostgreSQL, Docker]
team: [alice, bob]
last-updated: 2026-06-26
---

With this structure, the Dataview queries from earlier work immediately.

What to skip

A few popular plugins that aren't worth the friction for a typical developer workflow:

Mind Map — generating a mind map from a note sounds useful but in practice is never the right tool. Use Excalidraw for diagrams that need real thought.

Sliding Panes / Andy's Mode — horizontal scrolling panels instead of tabs. It was useful before Obsidian added proper tab groups; now it's just weird.

Natural Language Dates — parses "next Friday" as a date. The Tasks plugin handles this better with its own date picker.

AI writing plugins — there are several. Most of them call external APIs, which means your notes leave your machine. If data privacy matters (and for developer notes it usually does), be cautious.

Getting started

Open Obsidian → Settings → Community plugins → Turn off Restricted Mode
Browse and install the seven plugins from the list at the top
Enable Templater's template folder and set up your first template
Configure Obsidian Git with your remote repository
Create tasks.md with a Dataview query and use it as your starting point

The setup takes about 30 minutes. After that, the vault mostly manages itself.

Related: Markdown in Obsidian: The Complete Workflow Guide covers the Obsidian-specific Markdown features (wiki links, callouts, embedded notes) that you'll use alongside these plugins.

Markdown for API Documentation: OpenAPI, Stoplight, and the Docs-as-Code Stack

2026-06-19T00:00:00+00:00

API documentation sits at the intersection of technical writing, software development, and developer experience. It's also one of the areas where Markdown has quietly become essential — often in ways that aren't obvious until you're knee-deep in an OpenAPI spec or fighting a Stoplight rendering issue.

This guide covers where Markdown appears in API documentation, how the major platforms handle it, how to set up a docs-as-code workflow, and what to watch out for when writing descriptions that survive the journey from spec to rendered docs.

Where Markdown Lives in an OpenAPI Spec

If you're working with OpenAPI (formerly Swagger), Markdown appears in several places:

Description fields are the most common. Nearly every object in the OpenAPI spec accepts a description field, and these support CommonMark Markdown:

info:
  title: Payments API
  version: "2.0"
  description: |
    The **Payments API** lets you create, capture, and refund charges.

    ## Authentication

    All requests require a Bearer token in the `Authorization` header.
    Rate limits apply: 100 requests/second per API key.

The description field on paths, operations, parameters, request bodies, and response schemas all support Markdown:

paths:
  /charges:
    post:
      summary: Create a charge
      description: |
        Creates a new charge. The `amount` is in the **smallest currency unit**
        (e.g., cents for USD, pence for GBP).

        See [currency codes](/docs/currencies) for a full list.
      parameters:
        - name: idempotency_key
          in: header
          description: |
            A unique key to safely retry requests. If you send the same key twice,
            the API returns the original response rather than creating a duplicate.

            Recommended for all `POST` requests.

Markdown guide files alongside the spec are the second major use case. Most teams write long-form content — tutorials, quickstart guides, authentication flows — as .md files that live in the same repository as openapi.yaml, versioned and reviewed together.

Changelog files are almost always Markdown. Your CHANGELOG.md lives in git alongside the spec and gets rendered by whatever platform you use for documentation.

The API Documentation Platforms Compared

Most teams don't render OpenAPI specs manually — they use a platform that reads the spec and generates documentation. These platforms differ significantly in how they handle Markdown.

Platform	Markdown in descriptions	Custom Markdown pages	Self-hostable	Pricing model
Redocly	Full CommonMark + extensions	Yes (docs-as-code)	Yes	Open-source CLI; hosted plans
Stoplight	Full CommonMark	Yes (separate `.md` files)	Limited	Freemium SaaS
Scalar	Full CommonMark	Yes	Yes (open-source)	Open-source; hosted option
Readme.io	CommonMark + custom blocks	Yes (guides section)	No	Commercial SaaS
Swagger UI	Limited (sanitized HTML)	No (spec only)	Yes	Open-source
RapiDoc	CommonMark	No (spec only)	Yes	Open-source

Redocly is the go-to choice for teams who want full docs-as-code. You write OpenAPI + Markdown files, run redocly build-docs, and get a self-hosted documentation site. Their @redocly/cli also lints your OpenAPI spec for correctness, consistency, and style. Markdown support is robust: admonitions (callouts), tabs, code blocks with syntax highlighting, and cross-references between guides and reference docs.

Stoplight Studio is the most popular visual editor for OpenAPI. It renders Markdown in description fields faithfully and lets you write standalone Markdown pages that appear alongside the generated reference docs. The tradeoff: the visual editor can sometimes mangle complex Markdown in descriptions — always verify in preview mode before committing.

Scalar is newer and gaining momentum fast. It's fully open-source, renders OpenAPI specs with a modern, clean UI, and handles CommonMark properly in all description fields. Worth considering for teams who want something that looks great without vendor lock-in.

Readme.io is the commercial choice for teams that want a hosted developer portal with analytics, user authentication for private docs, and API key management built in. Their Markdown support includes custom callout blocks and interactive example makers. The tradeoff: more lock-in than the open-source alternatives, and the pricing climbs quickly.

Swagger UI is the original and still widely deployed — many teams use it for internal reference or expose it directly from their API. Its Markdown support is limited, though: descriptions pass through a sanitized HTML pipeline, and complex Markdown elements don't always behave as expected. Stick to basic formatting (bold, italic, inline code, links) if Swagger UI is your target.

Setting Up Docs-as-Code for API Documentation

The docs-as-code approach treats documentation like code: stored in git, reviewed in pull requests, deployed through CI/CD. For API docs, this means your repository looks something like:

api-docs/
├── openapi.yaml
├── docs/
│   ├── getting-started.md
│   ├── authentication.md
│   ├── rate-limits.md
│   └── changelog.md
├── redocly.yaml
└── .github/
    └── workflows/
        └── docs.yml

A minimal GitHub Actions workflow with Redocly:

name: API Docs

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  lint-and-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Redocly CLI
        run: npm install -g @redocly/cli

      - name: Lint OpenAPI spec
        run: redocly lint openapi.yaml

      - name: Build docs
        run: redocly build-docs openapi.yaml --output dist/

      - name: Deploy to GitHub Pages
        if: github.ref == 'refs/heads/main'
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: dist/

The redocly lint step catches spec errors and missing descriptions before they reach production. For Markdown files, adding markdownlint to the same workflow catches style issues in your guide files — the same rules you'd run locally with our Markdown Linter.

Writing Good Markdown API Descriptions

The descriptions in your OpenAPI spec are often the first thing a developer reads about an endpoint. A few principles that make a meaningful difference:

Lead with the "what", not the "how". The operation name already tells you what it does; the description should explain when to use it and what to watch for.

Instead of:

description: Creates a user in the database.

Write:

description: |
  Creates a new user account. Returns the created user object including the generated `id`.

  **Rate limit:** 10 requests/minute per IP. Creating users in bulk? Use the
  [batch import endpoint](/reference/users/import) instead.

Always show the unit, not just the type. For numeric fields, clarify what the number represents:

parameters:
  - name: amount
    description: |
      The charge amount in the **smallest currency unit** for the given currency.
      For USD: `100` = $1.00. For JPY (zero-decimal): `100` = ¥100.

Use code fences for examples. Most platforms (Redocly, Stoplight, Scalar) syntax-highlight fenced code blocks in description fields:

description: |
  Include a unique idempotency key on every `POST` request:

  ```
  X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
  ```

  Keys expire after 24 hours. Reusing an expired key creates a new request.

Note the nested code fences here — a triple-backtick block inside a YAML string. Most OpenAPI renderers handle this correctly; Swagger UI is the common exception.

Link between operations. Relative links ([see also](/reference/refunds)) connect related endpoints and keep users in the docs. Most platforms render these as proper links; the Markdown source stays readable in the raw spec.

What Doesn't Work Well

Complex tables in Swagger UI. Swagger UI renders Markdown tables inconsistently — the cell contents are sometimes sanitized in ways that strip inline formatting. Test tables in your target platform before relying on them for critical information.

Nested code blocks. Showing a code block example that contains another code block (meta-documentation) trips up some renderers. If you need to demonstrate nested fences, use an indented code block (4 spaces) for the inner example instead of triple backticks.

HTML in descriptions. OpenAPI allows HTML in description fields, and CommonMark allows inline HTML in Markdown. But documentation platforms sanitize it — <script>, <iframe>, <style>, and sometimes even <details> get stripped. Don't rely on raw HTML for anything load-bearing.

Relative paths across platforms. A link like [authentication](/docs/authentication) works perfectly when self-hosting with Redocly but breaks in Stoplight if your docs live at a different base path. Always test cross-links in the actual deployed environment.

Checking Your Markdown Before It Ships

Before committing an updated OpenAPI spec or guide file:

Run the platform's linter. redocly lint openapi.yaml catches spec-level issues; markdownlint catches Markdown style problems in your .md files.
Preview in the target platform. What looks right in VS Code may render differently in Stoplight or Readme.io — especially for tables and nested code blocks.
Check every code block manually. Unterminated fences are the most common rendering failure. They can silently swallow everything below them.
Verify all cross-links. Use a link-checker in CI for large doc sets; manual spot-checking for smaller ones.

For catching Markdown style issues locally before pushing, the Markdown Linter at Markdown Tools checks heading hierarchy, bare URLs, missing alt text, unclosed code blocks, and more. The Markdown Editor gives you live preview so you can see how your guide content will look before it hits the platform.

Platform Support Quick Reference

Format	OpenAPI descriptions	Guide `.md` files	Swagger UI
Bold, italic	All platforms	All platforms	Yes
Inline code	All platforms	All platforms	Yes
Fenced code blocks	Redocly, Stoplight, Scalar, Readme	All platforms	Limited
Tables	Redocly, Stoplight, Scalar, Readme	All platforms	Inconsistent
Links	All platforms	All platforms	Yes
Task lists	Some	Redocly, Readme	No
Footnotes	Some	Redocly (MDX), Readme	No
Admonitions / callouts	Redocly, Readme (custom blocks)	Redocly, Readme	No
Raw HTML	Varies — most sanitize	Varies	No

Markdown Linter — catch style issues before committing
Markdown Editor — live preview while drafting guide content
Markdown to HTML — export clean HTML for platforms that accept HTML
Our guide: Markdown for Technical Writers: The Docs-as-Code Workflow
Our guide: Markdown Syntax Highlighting — getting language tags right in code blocks
Our guide: MkDocs vs Docusaurus vs GitBook — choosing the right docs platform

Markdown to Jira Wiki Markup: The Complete Conversion Guide

2026-06-19T00:00:00+00:00

If you write documentation in Markdown but need to post it to Jira, you've hit the wall: Jira has its own wiki markup language, and pasting Markdown directly doesn't work — or doesn't work reliably. The results depend on which version of Jira you're using, which project type, and whether your admin has enabled anything.

This guide maps out every syntax difference, explains what actually works in each Jira context, and shows you how to do the conversion reliably.

Why Jira Doesn't Just Support Markdown

Jira's text formatting language (wiki markup) predates widespread Markdown adoption. It uses its own syntax that's close to — but not the same as — Markdown. In Cloud and Server, Atlassian has gradually added Markdown-like support, but it's incomplete and inconsistent across project types.

The result: the same pasted content renders differently in:

Jira Data Center/Server — pure wiki markup, very little native Markdown support
Jira Cloud (classic projects) — hybrid editor, some Markdown autocomplete on the Visual side
Jira Cloud (next-gen / team-managed projects) — rich text editor, accepts some Markdown on paste, no wiki markup at all

This distinction matters more than anything else in this guide.

Which Jira Version Are You Using?

Before converting anything, identify your environment:

Jira type	How to tell	Markdown support	Wiki markup
Data Center / Server	Self-hosted, URL isn't atlassian.net	None	Full
Cloud — classic project	atlassian.net domain, Text/Visual editor toggle	Partial (autocomplete)	Full
Cloud — next-gen project	atlassian.net, no "Text" tab in editor	Paste-in only	None

For Data Center/Server and Cloud classic: Convert to wiki markup before pasting.
For Cloud next-gen: Paste Markdown directly into the rich text editor; basic formatting survives (bold, italic, lists), but tables and code blocks usually break.

The Complete Markdown → Jira Wiki Markup Conversion Table

Element	Markdown	Jira Wiki Markup
Heading 1	`# Heading`	`h1. Heading`
Heading 2	`## Heading`	`h2. Heading`
Heading 3	`### Heading`	`h3. Heading`
Bold	`text`	`text`
Italic	`text`	`_text_`
Strikethrough	`~~text~~`	`-text-`
Inline code	`code`	`{{code}}`
Code block	```lang	`{code:lang}...{code}`
Blockquote	`> text`	`{quote}text{quote}`
Link	`[text](url)`	`[text\|url]`
Image	`![alt](url)`	`!url!`
Unordered list	`- item`	`* item`
Ordered list	`1. item`	`# item`
Horizontal rule	`---`	`----`
Table header	`\| head \|`	`\|\| head \|\|`
Table cell	`\| cell \|`	`\| cell \|`

The differences look subtle but they trip people up constantly — especially *bold* becoming _italic_ in Jira (the opposite of how Markdown works).

Converting Code Blocks

This is where things get interesting. Jira uses macro syntax for code blocks:

Markdown:

```javascript
const greeting = 'Hello, world!';
console.log(greeting);
```

Jira wiki markup:

{code:javascript}
const greeting = 'Hello, world!';
console.log(greeting);
{code}

The language name goes as a parameter to the {code} macro. Supported languages include java, javascript, python, sql, xml, html, css, bash, ruby, php, and dozens more. If you omit the language, the block renders as plain preformatted text.

For inline code, Markdown uses backticks while Jira uses {{double curly braces}}:

Markdown	Jira
`variable`	`{{variable}}`
`npm install`	`{{npm install}}`

Converting Tables

Tables are one of the clearest differences. Markdown uses a --- separator row to mark headers; Jira uses double pipes (||) for header cells and single pipes (|) for body cells.

Markdown:

| Name | Role | Access |
|------|------|--------|
| Alice | Admin | Full |
| Bob | Developer | Read/Write |

Jira wiki markup:

|| Name || Role || Access ||
| Alice | Admin | Full |
| Bob | Developer | Read/Write |

There's no separator row in Jira. The header is inferred purely from whether the row uses || or |.

What Jira wiki markup tables don't support:

Column alignment (:---: / ---: syntax is ignored)
Multi-line cells
Colspan or rowspan (requires the HTML macro)
Cell background colours (without the HTML macro)

If you need any of those, convert to HTML using our Markdown to HTML tool and paste using Jira's HTML macro.

Converting Lists and Nesting

Both Markdown and Jira use * and # for lists, but Jira doesn't use indentation for nesting — it uses repeated characters:

Markdown (nested):

- Item 1
  - Nested item
  - Another nested
- Item 2

Jira wiki markup (nested):

* Item 1
** Nested item
** Another nested
* Item 2

Each additional level of nesting repeats the character. Two levels deep is **, three is ***. Indentation in Markdown doesn't translate automatically — you need to count nesting depth and repeat accordingly.

Mixed ordered/unordered nested lists work the same way:

* First level unordered
*# Second level ordered under unordered
*#* Third level unordered under ordered under unordered

Converting Blockquotes

Markdown blockquotes use > prefixes. Jira uses a {quote} macro:

Markdown:

> This is a quoted passage from the requirements document.
> It can span multiple lines.

Jira:

{quote}
This is a quoted passage from the requirements document.
It can span multiple lines.
{quote}

Nested blockquotes (> > text) aren't directly supported in Jira wiki markup — you get one level.

Jira-Only Macros

Wiki markup has macros that have no Markdown equivalent. Knowing these is useful when you're writing content that will only ever live in Jira:

Colour text:

{color:red}This text is red.{color}
{color:#0052CC}This text is Jira blue.{color}

Info/note/warning/tip panels:

{info}This is an informational note.{info}
{warning}Caution: this action cannot be undone.{warning}
{note}Note: configuration required.{note}
{tip}Pro tip: use keyboard shortcuts.{tip}

Panel with title and styling:

{panel:title=Important|borderColor=#ddd|titleBGColor=#f0f0f0}
Panel content here.
{panel}

No-format block (preformatted text, no syntax highlighting):

{noformat}
Plain text that should appear as-is.
Stack traces, log output, etc.
{noformat}

Jira issue link:

{jira:KEY-123}

These macros render as styled components in Jira but have no Markdown equivalent. If you're round-tripping content (Jira → Markdown → Jira), you'll lose these macros on the Markdown side.

What Doesn't Convert Cleanly

Some Markdown features have no wiki markup equivalent:

Markdown feature	In Jira
Footnotes `[^1]`	Not supported
Definition lists	Not supported
Task lists `- [x]`	Use `(/)` and `(x)` emoji for checkmarks; not linked to issue checklists
Custom heading IDs `{#anchor}`	Not supported
Strikethrough in tables	Works, but renders inconsistently
HTML elements	Use `{html}` macro (Cloud only, off by default)
Fenced code inside blockquotes	Loses code formatting

For task lists specifically: Jira has a built-in checklist feature in Cloud, but it's separate from the text editor and not accessible via wiki markup.

Using Our Markdown to Jira Converter

The fastest way to convert is with our Markdown to Jira tool. Paste your Markdown on the left, get Jira wiki markup on the right in real time.

The converter handles:

All heading levels (h1–h6)
Bold, italic, strikethrough
Inline code and fenced code blocks with language tags preserved
Tables with header row conversion (|| vs |)
Ordered and unordered lists with nesting depth
Blockquotes
Links and images
Horizontal rules

It's particularly useful when you have long documentation pages to migrate, or you're regularly posting Markdown from a blog or docs tool into Jira issues.

Which Editor Mode to Use

For Data Center/Server: always use wiki markup. It's the native format. Click the Text tab in the issue editor, paste wiki markup, done.

For Cloud classic projects: the Text tab accepts wiki markup directly. The Visual tab is WYSIWYG. If you're using the REST API to create or update issues, the description field accepts wiki markup for classic projects.

For Cloud next-gen (team-managed) projects: there's no Text tab. The editor is rich text only. For basic formatting, paste Markdown and let it auto-convert. For tables and code blocks, paste HTML using your browser's paste shortcut after converting with our Markdown to HTML tool.

For Jira Cloud API (creating issues programmatically): Cloud's REST API v3 uses Atlassian Document Format (ADF), not wiki markup. You can't paste wiki markup into the description field via the API on Cloud — you need to build an ADF document. Wiki markup is only supported in the Server/DC REST API. This is a significant pain point for teams automating Jira content creation.

Jira Wiki Markup Reference Cheat Sheet

Quick reference for the conversions you'll use most often:

Text formatting:

*bold*           _italic_         -strikethrough-
+underline+      ^superscript^    ~subscript~
??citation??     {color:red}text{color}

Structure:

h1. Heading 1          h2. Heading 2          h3. Heading 3
----                   (horizontal rule)

Lists:

* Bullet             # Numbered
** Nested bullet     ## Nested numbered

Links and media:

[Link text|https://example.com]
[Page title|PAGE TITLE]     (Confluence-style, not standard Jira)
!image.png!                 !image.png|thumbnail!
^file.pdf                   (attachment link)

Macros:

{code:java}code here{code}
{{inline code}}
{quote}quoted text{quote}
{noformat}plain text{noformat}

Markdown to Jira converter — real-time conversion, no signup required
Markdown to Confluence — Confluence uses similar wiki markup; see our Confluence guide for the differences
Markdown to HTML — for Jira Cloud next-gen where wiki markup isn't available
Markdown Across Platforms — how Markdown behaves in each major platform
Markdown for Technical Writers — if you're managing docs alongside Jira tickets

Why Your Markdown Isn't Rendering: A Troubleshooting Guide

2026-06-12T00:00:00+00:00

You write clean Markdown, hit preview, and something goes wrong. The heading doesn't appear. The code block is mangled. The table renders as pipe characters scattered across a paragraph. The bold text shows up as literal asterisks.

This isn't a Markdown problem — it's almost always a renderer problem. Markdown isn't one thing; it's a family of related syntaxes interpreted differently by dozens of parsers. The same document can render perfectly in VS Code, break in Confluence, and look different again on GitHub. Knowing which renderer you're debugging is the key to solving the problem fast.

This guide covers the most common causes, organized by symptom and by platform.

Start Here: Identify Your Renderer

Before anything else, answer this question: what is rendering your Markdown?

Where you're writing	Renderer
GitHub README / PR description	GitHub Flavored Markdown (GFM)
Jekyll site	kramdown (usually)
Hugo site	Goldmark
Docusaurus / MDX	remark
VS Code preview	Markdown-it
Confluence	Not really Markdown — XHTML-based
Slack	mrkdwn (Slack's own format)
Obsidian	Markdown-it with plugins
Reddit	Snoomark (new) or older Reddit Markdown
Notion	Notion's own parser (paste-only)

Each renderer supports a different subset of Markdown features. Most support CommonMark as a baseline; the extended features (tables, task lists, footnotes, strikethrough) vary.

The Most Common Causes

1. The renderer doesn't support that syntax

This is the most frequent cause. Something looks like standard Markdown but isn't supported by your target renderer.

Examples:

Footnotes — CommonMark doesn't include them. They work in Pandoc, kramdown, and GitHub (for Wikis), but not in basic GFM for README files.
Definition lists — supported by kramdown, not by most others.
Custom heading IDs (## Heading {#my-id}) — supported by Pandoc and some Hugo themes, not in GitHub Flavored Markdown.
Subscript/superscript (H~2~O, x^2^) — Pandoc and some plugins only.

Fix: Check the renderer's documentation for which extensions it supports. Don't assume something works because it works in your local editor.

2. Missing blank lines around block elements

Markdown parsers are pickier than you'd expect about blank lines. Most renderers require a blank line before and after:

Block-level HTML tags
Fenced code blocks
Lists that follow a paragraph
Headings that follow content

Without the blank line, a renderer may treat the content as a paragraph continuation instead of a new block.

This won't render correctly:

Some text.
```code
example

More text.


**This will:**
```markdown
Some text.

```code
example

More text.


### 3. Indentation inconsistency in lists

List item continuation and nested lists depend on consistent indentation. The rules vary by renderer:

- CommonMark requires **2 spaces** of indentation for nested items
- Some older parsers require **4 spaces** or a tab
- Mixing tabs and spaces causes unpredictable behaviour

**Symptom:** A nested list renders flat, or a code block inside a list item renders as a paragraph.

**Fix:** Use consistent 2-space indentation throughout, and never mix tabs with spaces.

### 4. HTML inside Markdown getting stripped

Many renderers strip raw HTML for security reasons. This is intentional.

- **GitHub** strips `<style>`, `<script>`, and most event handlers from README files. It keeps safe tags like `<details>`, `<summary>`, `<kbd>`, and `<br>`.
- **Hugo's Goldmark** strips raw HTML by default. You must add `markup.goldmark.renderer.unsafe: true` to your config to allow it.
- **Confluence** rejects HTML entirely unless you use the dedicated HTML Macro.
- **Docusaurus/MDX** interprets HTML as JSX — missing a closing tag or a non-void self-closing tag will break the entire page.

**Symptom:** Your carefully crafted HTML layout renders as plain text, or throws an error.

**Fix:** Check your renderer's HTML-in-Markdown policy. For Hugo, enable unsafe rendering. For GitHub, use only the subset of HTML tags that GFM allows. For Confluence, use the HTML Macro.

### 5. Jekyll: Liquid syntax in code blocks


Jekyll processes Liquid template tags *before* Markdown rendering. This means any `{% ... %}` or `{{ ... }}` inside a code block — even a fenced one — will be executed as a template, not displayed as code.


**Symptom:** Code block content disappears, or you see a Liquid error like `Liquid Warning: Liquid syntax error`.

**Fix:** Wrap the problematic code block in `{% raw %}` and `{% endraw %}` tags. Your file should look like this:


```bash
echo "Hello {{ name }}"

This is required any time your code block contains {{, }}, {%, or %} — common when documenting Liquid, Jinja2, Handlebars, or Hugo templates.

6. Jekyll: Posts not appearing (date in the future)

Jekyll doesn't render posts with a date in the future by default.

Symptom: A post exists in _posts/ but doesn't appear on the site.

Fix: Either set the date to today or earlier in the frontmatter, or add future: true to _config.yml in your development environment. Don't add it to production unless you intend posts to publish early.

7. Hugo: Shortcodes in Markdown code blocks

Hugo processes shortcodes ({{< ... >}}) before rendering, same as Jekyll's Liquid problem.

Symptom: A code block showing how to use a Hugo shortcode is broken or missing.

Fix: Use Hugo's {{</* ... */>}} comment syntax inside shortcode examples, or wrap in a highlight shortcode instead of a fenced block:

{{</* warning */>}}
This is a warning box.
{{</* /warning */>}}

8. Tables: Missing separator row

A Markdown table requires a separator row of dashes between the header and the body rows. Without it, most renderers won't recognise it as a table at all.

This won't render as a table:

| Name | Role |
| Alice | Admin |
| Bob | Editor |

This will:

| Name | Role |
|------|------|
| Alice | Admin |
| Bob | Editor |

The number of dashes doesn't matter (minimum 1 per cell), but the separator row is required.

9. Confluence: Markdown paste doesn't work as expected

Confluence is not a Markdown-native tool. Its internal format is XHTML. When you paste Markdown, Confluence converts it — and the conversion is lossy.

What works on paste:

Basic headings, bold, italic
Simple unordered and ordered lists
Code blocks (language tag is often dropped)

What breaks:

Tables (often rendered as plain text)
Task lists
Footnotes
Nested blockquotes
Raw HTML

Better approach: Use the /markdown slash command (Confluence Cloud) or the Wiki Markup import path. For reliable table conversion, use our Markdown to Confluence tool to convert to wiki markup first, then paste using Insert → Wiki Markup.

See our full guide: Markdown in Confluence: What Actually Works.

10. GitHub: GFM vs standard Markdown

GitHub Flavored Markdown adds extensions on top of CommonMark, but it also restricts some things.

Things that work in GFM but not standard Markdown:

Tables (pipe syntax)
Task lists (- [x])
Strikethrough (~~text~~)
Autolinks (https://... without brackets)
Alerts / callouts (> [!NOTE])

Things that do NOT work in GitHub README files:

Footnotes (they work in GitHub Wikis and GitHub Pages, but not README.md)
Definition lists
Custom CSS or <style> tags
<script> tags

Symptom: A footnote [^1] renders as literal text in a README but works fine in your local Markdown editor.

Fix: Check the GitHub Flavored Markdown spec for what's in-scope. For README files specifically, if a feature isn't listed there, it won't work.

Platform Comparison: What Renders Where

Feature	GitHub README	Jekyll (kramdown)	Hugo (Goldmark)	Obsidian	Confluence
Tables	✅	✅	✅	✅	⚠️ partial
Task lists	✅	✅ plugin	✅	✅	❌
Footnotes	❌	✅	✅	✅	❌
Strikethrough	✅	✅	✅	✅	⚠️
Definition lists	❌	✅	❌	❌	❌
Raw HTML	⚠️ safe subset	✅	⚠️ opt-in	⚠️	❌
Math (LaTeX)	✅ (2022+)	✅ plugin	✅ plugin	✅	❌
Mermaid diagrams	✅	✅ plugin	✅ plugin	✅	❌
Custom heading IDs	❌	✅	✅	✅	❌

See our full platform compatibility guide for a more detailed breakdown.

Debugging Workflow

When your Markdown breaks, work through this checklist:

Isolate the problem — create a minimal reproduction. Copy just the broken section into a fresh file. If that renders correctly, the issue might be something earlier in the document (unclosed code block, broken table, etc.) affecting parsing.
Check for unclosed code blocks — an unterminated fenced code block (missing closing ) will cause everything after it to render as code. Search for lone in your document.
Check the raw output — inspect the HTML source of the rendered page (right-click → View Source). This tells you whether the renderer is producing output at all or silently failing.
Test in a known-good renderer — paste the Markdown into our live editor to see if it renders there. If it does, the issue is your target renderer, not the Markdown itself.
Check your linter — use our Markdown Linter to catch structural issues (skipped heading levels, unclosed blocks, missing alt text) before they cause render failures.
Read the error logs — Jekyll and Hugo both print build warnings to the terminal. A Liquid error, a missing file, or a frontmatter parse failure will appear there before you spend 30 minutes debugging Markdown.

Summary

Most Markdown rendering failures fall into one of these categories:

Renderer doesn't support the syntax — check the spec for your specific tool
Missing blank lines around block elements
Template tags in code blocks — use {% raw %} in Jekyll, comment syntax in Hugo
HTML being stripped — check security settings, use only allowed tags
Confluence — it's not a Markdown renderer; use our wiki markup converter
Table missing separator row — always required

The fix is almost always straightforward once you know which renderer is involved. Start there, and the rest usually follows.

Markdown Across Platforms: What Works in GitHub, Notion, Obsidian, and Confluence — the reference guide for cross-platform compatibility
Markdown in Confluence: What Actually Works — deep dive on Confluence specifically
Markdown for Technical Writers: The Docs-as-Code Workflow — setting up markdownlint and Vale in CI
Markdown Linter — check your Markdown for style issues instantly
Markdown Live Editor — test how your Markdown renders in real time
Markdown to Confluence — convert Markdown to Confluence wiki markup

Markdown for Technical Writers: The Docs-as-Code Workflow Guide

2026-05-15T00:00:00+00:00

"Docs-as-code" is the practice of treating documentation the same way software teams treat code: write in plain text (usually Markdown), version-control in Git, review through pull requests, and build automatically with CI/CD.

The approach has moved from niche to mainstream, and for good reason — it gives technical writers the collaboration and review tools that developers have used for decades. This guide covers the practical setup: which tool to pick, how to structure the review workflow, linting, CI/CD, and the real trade-offs you'll face.

What Docs-as-Code Looks Like in Practice

In a docs-as-code workflow:

Source files are Markdown — stored in a Git repository alongside (or separate from) the code they document
Changes go through pull requests — reviewers comment on line-level diffs, just like code review
A static site generator builds the site — MkDocs, Docusaurus, Hugo, or Sphinx turns Markdown into a deployed documentation site
CI/CD builds and deploys automatically — merge to main, and the docs site updates within minutes

This is the approach used by major open-source projects: the React docs, Kubernetes docs, and many commercial API documentation sites all use variants of this workflow.

Choosing a Static Site Generator

This is the most consequential decision. The right tool depends on your audience, tech stack, and how much configuration overhead you can absorb.

MkDocs + Material theme

Best for: Python projects, internal engineering docs, teams who want to be up in an hour

MkDocs is the most approachable option. Install it with pip, write a mkdocs.yml, and run mkdocs serve for a live preview. The Material for MkDocs theme adds search, versioning, admonitions, and a professional design out of the box.

# mkdocs.yml
site_name: My Docs
theme:
  name: material
  features:
    - navigation.tabs
    - navigation.sections
    - search.suggest
nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - API Reference: api-reference.md

MkDocs supports extended Markdown: admonitions (!!! note), code block line numbers, content tabs, and more. See our MkDocs vs Docusaurus vs GitBook comparison for a full breakdown.

Docusaurus

Best for: JavaScript/React projects, developer-facing docs, versioned API references

Docusaurus (by Meta) is the most feature-rich option for developer documentation. It supports versioned documentation, MDX (Markdown with embedded React components), and integrates well with Algolia search. The downside: it requires Node.js and has more configuration overhead.

npx create-docusaurus@latest my-docs classic
cd my-docs
npm start

Hugo

Best for: Large sites (thousands of pages), teams who need extreme build speed

Hugo is the fastest static site generator available — it can build thousands of pages in seconds. The trade-off is a steeper learning curve. Its template system takes time to master, and its Markdown handling has some quirks (it uses Goldmark by default, which differs slightly from CommonMark).

Sphinx

Best for: Python packages, teams that need API auto-documentation from docstrings

Sphinx uses reStructuredText by default, but the myst-parser extension gives you Markdown input with full Sphinx features. It's the standard for Python library documentation (NumPy, Django, Flask) because its autodoc system reads Python docstrings and generates API reference pages automatically.

The Review Workflow

The core of docs-as-code is Git-based review. Here's what a typical workflow looks like.

Branching strategy

Keep it simple. Most documentation teams do well with a single main branch as the source of truth, with short-lived feature branches:

main                       ← deployed to production
├── docs/update-auth-section
├── docs/add-webhook-guide
└── docs/fix-typos-api-ref

Some teams mirror software release branches (v2.1, v2.2) for versioned documentation.

Pull request review

When a writer opens a PR, reviewers see a line-level diff. They can comment on specific sentences rather than leaving vague feedback on a shared document. This is a significant productivity gain over wiki-based review.

Tips for effective docs PRs:

Keep PRs focused — one topic or section per PR, not "update all the docs"
Use the PR description to explain the why ("users were confused about X, so I clarified Y")
Request review from subject matter experts for accuracy; editors for style
Require at least one approval before merge — documentation errors in production are real bugs

Reviewing large diffs for non-git users

For reviewers who aren't comfortable with git diffs, our Markdown Diff tool lets them paste the before and after versions of a section and see a colour-coded comparison — no git access required.

Linting: markdownlint and Vale

Linting documentation catches problems before review: broken syntax, inconsistent formatting, and prose style issues.

markdownlint

markdownlint enforces Markdown syntax consistency. Run it in CI to catch:

Missing blank lines around headings
Hard tabs instead of spaces
Duplicate headings on the same page
Inconsistent list marker styles (- vs *)
Lines over a configured maximum length

npm install -g markdownlint-cli
markdownlint '**/*.md' --ignore node_modules

Configure it with a .markdownlint.json file in the repository root:

{
  "default": true,
  "line-length": { "line_length": 120 },
  "no-duplicate-heading": false
}

Vale: prose style linting

Vale is a linter for prose style. It enforces:

A style guide (Microsoft, Google, or a custom one you define)
Banned words and phrases ("simply", "just", "easy", "obviously")
Consistent terminology (always "API key", never "api key" or "apikey")
Passive voice frequency limits

# .vale.ini
StylesPath = styles
MinAlertLevel = suggestion

[*.md]
BasedOnStyles = Vale, Microsoft

Vale catches what a human style reviewer would catch — at scale, in seconds. It's what separates mature docs-as-code setups from basic ones.

CI/CD: Building and Deploying Docs

The CI pipeline for documentation is usually simpler than for software. A typical GitHub Actions workflow for a MkDocs site:

# .github/workflows/docs.yml
name: Docs CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npx markdownlint '**/*.md' --ignore node_modules

  build:
    runs-on: ubuntu-latest
    needs: lint
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install mkdocs-material
      - run: mkdocs build --strict

  deploy:
    if: github.ref == 'refs/heads/main'
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force

The --strict flag on mkdocs build fails the build if there are any warnings — broken internal links, missing pages — which catches link rot before it ships to production.

Structuring Markdown for Documentation

Well-structured Markdown makes navigation, search, and updates easier.

One topic per file

Each file should cover one complete, focused topic. When a file grows beyond 600–800 lines, it's usually a sign it should be split into separate pages.

Consistent frontmatter

Define a standard frontmatter schema and enforce it across the team:

---
title: Authentication Guide
description: How to authenticate API requests using API keys or OAuth 2.0.
last_updated: 2026-05-15
---

Heading discipline

One # H1 per file (the page title)
Use ## and ### for sections and subsections
Don't skip heading levels (don't jump from ## to ####)
Write headings that make sense out of context — search engines and screen readers encounter them in isolation

For more on heading-based navigation and anchor links, see our guide to Markdown internal links.

Callouts and admonitions

Most documentation generators support callout blocks. Use them to highlight warnings, tips, and important notes. In MkDocs Material:

!!! warning "Breaking change"
    This endpoint was deprecated in v2.0 and will be removed in v3.0.
    Migrate to `/v2/auth` before upgrading.

In Docusaurus (MDX):

:::warning Breaking change
This endpoint was deprecated in v2.0...
:::

See our Markdown admonitions guide for platform-specific admonition syntax.

Code blocks: always specify the language

Always add a language identifier to fenced code blocks. It improves syntax highlighting, helps readers orient quickly, and some generators use the language tag for copy-button behavior.

```bash
curl -X POST https://api.example.com/v1/tokens \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json"
```

For more on code block highlighting across platforms, see our syntax highlighting guide.

The Trade-offs: Docs-as-Code Isn't for Everyone

Docs-as-code has real costs. Be honest with yourself about them.

Learning curve for non-developers — technical writers who haven't used Git may need weeks to become comfortable with branching, rebasing, and conflict resolution. Budget for training.

Less intuitive for SME contributions — subject matter experts who write occasional documentation may struggle with the Git workflow. Solutions: a web-based editor (Netlify CMS, TinaCMS) for non-technical contributors, or a contribution guide with screenshots.

No rich inline collaboration — Google Docs-style simultaneous editing doesn't exist in Git-based workflows. PRs cover review, but live co-writing requires a workaround.

Image management is awkward — images live in the repo or an external CDN. Large images bloat repository size; external images can go dead. Establish an image convention early.

Docs-as-code is clearly the right choice when:

Documentation lives alongside code and should move with it through releases
The team is primarily developers already working in Git daily
You need versioned docs to match versioned software releases
You want to enforce a style guide at scale with Vale and markdownlint

It might not be the right choice when:

Most contributors are non-technical
You need real-time collaborative editing
The documentation is heavily visual (screenshots, interactive diagrams)
You don't have bandwidth to maintain the toolchain

Getting Started: a Minimal Setup

If you want to try docs-as-code without committing to a full setup:

Create a GitHub repository for your documentation
Install MkDocs Material: pip install mkdocs-material
Create mkdocs.yml with the minimal config shown above
Write a docs/index.md as your home page
Run mkdocs serve to preview locally
Enable GitHub Pages and run mkdocs gh-deploy to publish

You'll have a live documentation site in under an hour. From there, add markdownlint to CI, then Vale when you're ready to enforce style.

MkDocs vs Docusaurus vs GitBook: which should you use? — full decision guide with setup examples
Markdown for GitHub: the complete workflow guide — GitHub-specific Markdown features, PR templates, wikis
Markdown in Confluence: what works and what doesn't — for teams who need docs in both systems
Markdown admonitions and callouts guide
Markdown syntax highlighting guide

Markdown Tools Blog

How to Remove Markdown Formatting from ChatGPT and Claude Output

Why AI output is full of Markdown

Option 1: Ask for plain text up front

Option 2: Strip it with a converter

Option 3: Do it yourself with a regex (and why it breaks)

When you should not strip everything

What gets lost

Quick checklist

Markdown Footnotes Across Platforms: Where They Actually Render

Native support, no configuration needed

Needs configuration — off by default

No support at all

Quick reference

Cleaning up messy footnotes before you publish

Related reading

Markdown Comments Across Platforms: Hidden, Stripped, or Still Sitting in Your HTML?

The distinction that matters: removed vs. hidden

Platform-by-platform behavior

GitHub — repo files vs. Issues/PRs

GitLab

npm and PyPI package pages

Jekyll (this site's own engine) — and why it's a special case

Hugo

MkDocs, Docusaurus, and other static-site generators

Confluence

Notion

Obsidian

VS Code Markdown Preview

Quick reference

What this means in practice

Related reading

Mermaid Diagrams in Slack, Jira, Confluence, Word, and Email: The Static Export Workaround

Why this keeps catching people off guard

The fix: render it once, export a static image

Platform by platform

Slack

Jira

Confluence

Word (.docx)

Email (newsletters, transactional templates)

SVG vs. PNG: which to export

Quick reference

Related reading

Markdown Word Count and Reading Time: How the Numbers Actually Get Calculated

The Part Everyone Skips: What Counts as a "Word" in Markdown Source

How Our Tool Calculates Reading Time

Why Other Tools Give You a Different Number

Quick Reference: What Varies Between Reading-Time Approaches

Practical Implications for Writers

Use Cases

Related Tools

Markdown Image Sizing and Alignment Across Platforms: What Actually Works

The Core Technique: Inline HTML

GitHub and GitLab: Full Support

Notion: Strips HTML, Uses Its Own Block Instead

Slack: Strips HTML, No Sizing Control At All

Obsidian: Its Own Embed Syntax, Not HTML

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

Confluence and Jira: Neither HTML Nor a Text Syntax

Quick Reference

What This Means in Practice

Related Reading

Markdown Callouts and Admonitions Across Platforms: What Actually Renders

GitHub and GitLab Alerts: Native, But Not CommonMark

Obsidian Callouts: A Similar Look, a Different (Larger) Vocabulary

MkDocs: A Real Extension, Config Required, Indentation-Sensitive

Docusaurus: A Third Shape Entirely — Fenced Directives

Quick Reference

What Doesn't Cross-Render, Concretely

Related Reading

Markdown Math Rendering Across Platforms: Where LaTeX Actually Works

Native Support: GitHub, GitLab, Obsidian

Needs a Plugin: Static Site Generators

Real Feature, Different Trigger: Notion

Needs a Marketplace App or Doesn't Support It: Confluence, Jira, Slack

MathJax vs. KaTeX: Why the Same Formula Can Look Different

Quick Reference

Practical Takeaways

Related Reading