Markdown Portability Preflight
Paste Markdown source and see exactly which constructs will render differently — or break outright — depending on where it's viewed: GitHub, a strict CommonMark renderer, or a stripped-down renderer like old Reddit.
Processed locally in your browser. Your file is never uploaded.
How to use this tool
- Paste your Markdown source, or a whole README/doc file — nothing leaves your browser.
- Select "Check portability".
- Review each flagged construct: what makes it non-portable, and which renderers disagree.
- Use the suggested rewrite where one is offered — most of these issues genuinely can't be auto-fixed without guessing, and those are explained instead.
Assumptions
- Recognises seven specific portability-relevant constructs: bare URLs, tab-indented code blocks, GFM pipe tables, GFM strikethrough, GFM task lists, reference-style links/images with no matching definition, and raw HTML blocks using tags that are commonly sanitized. Anything else about Markdown rendering is out of scope.
- This is a line-aware text scanner, not a full Markdown parser — it does not build a document tree, and content inside fenced code blocks is deliberately skipped rather than analyzed.
- A reference link/image is only flagged when no definition for its reference label exists anywhere in the pasted document; matching is case-insensitive, matching CommonMark's own rule.
Sources & reference data
Methodology
Each construct is found with a targeted pattern match (with fenced code blocks tracked and excluded), then checked against known, documented rendering differences between GitHub-Flavored Markdown, the CommonMark specification, and common stripped-down renderers. A rewrite is offered only when it is mechanically safe and unambiguous — wrapping a bare URL in angle brackets — never for a case where the correct fix requires knowing intent (a missing reference definition's target URL) or where the syntax is valid and intentional (a GFM table, task list or strikethrough is not a mistake to silently rewrite).
Worked example
A bare URL with no angle brackets or link syntax
Inputs: See https://example.com for details.
Result: GFM autolinks this automatically, but strict CommonMark renderers leave it as plain, unclickable text. Flagged as a warning; safely rewritten to "See <https://example.com> for details.", which autolinks everywhere.
A reference-style link with no matching definition
Inputs: Read the [migration guide][missing-ref] before upgrading.
Result: No "[missing-ref]: url" definition exists anywhere in the document, so this link renders as broken or literal text in every renderer — not a portability difference but a genuine bug. Flagged as an error; no rewrite is offered because the intended target URL can't be known.
A GFM pipe table
Inputs: | Name | Age | |------|-----| | Ada | 30 |
Result: Pipe-table syntax is a GitHub-Flavored Markdown extension with no equivalent in CommonMark core. Flagged as info; a plain CommonMark renderer shows the pipes and dashes as literal text instead of a table.
Practical guidance
- Always wrap a bare URL in angle brackets, or turn it into a full [text](url) link, if the document might ever be viewed through a strict CommonMark renderer.
- Prefer fenced code blocks (```) over tab- or space-indented code blocks — they have no tab-width ambiguity and are visually unambiguous to the next editor of the document, too.
- Double-check every reference-style link/image before publishing — a missing or misspelled reference definition is a real bug, not a rendering quirk, and it fails silently in the rendered output.
- Avoid raw <script>/<iframe>/<style>/<object>/<embed> tags in Markdown meant for a public platform — treat sanitization as the expected, not exceptional, behavior.
Common mistakes
- Assuming a Markdown table or task list "just works" because it renders correctly on GitHub — GFM extensions are not part of the CommonMark specification, and plenty of renderers implement only the strict spec.
- Treating a broken reference link as a portability quirk rather than a bug — unlike the other issues here, a missing reference definition breaks the link everywhere, not just on stricter renderers.
FAQs
Why is a bare URL only a warning, but a broken reference link an error?
A bare URL still displays as readable plain text everywhere, even where it doesn't autolink — nothing is lost, just a convenience. A broken reference link renders as literal bracket syntax or a missing link everywhere, which is a functional bug regardless of the renderer.
Why doesn't the tool rewrite GFM tables or task lists into something more portable?
There isn't a strictly-portable equivalent that preserves the same meaning and appearance — a plain CommonMark renderer has no table or checkbox concept at all. The tool flags these so you can decide whether GFM-only rendering is acceptable for where the document will be read, rather than guessing a rewrite that would change the content's structure.
Does this tool check content inside fenced code blocks?
No — text inside ``` fenced code blocks is deliberately skipped, since it's meant to be shown verbatim and isn't Markdown syntax itself. A bare URL or ~~text~~ shown as an example inside a code fence is not a real portability issue.
Why does a Markdown table render on GitHub but not in CommonMark?
Pipe tables are a GitHub-Flavored Markdown extension, not part of core CommonMark. A CommonMark-only renderer may show the pipes and separator row as text instead of a table; this preflight identifies that renderer difference but does not render or compare every Markdown implementation.
Last reviewed: 2026-09-25
This is a narrow, line-aware scanner, not a full Markdown parser: it recognises seven specific constructs and nothing else, so other CommonMark/GFM edge cases (nested emphasis ambiguity, footnotes, autolink edge cases, HTML entity handling) are never analyzed. It also can't know what a broken reference link was actually meant to point to — it reports the break rather than guessing a fix.
Theme and tool preferences, along with saved and recently used lists, are stored only in this browser.