Markdown editor workflow: write once, render anywhere

Markdown, created by John Gruber in 2004, was designed around one principle: the source should be publishable as-is. Asterisks for emphasis, pound signs for headings, and hyphens for lists were chosen because people already typed them in plain-text email. The format asks almost nothing of the reader — a Markdown file with no renderer in sight is still a perfectly legible document.

That property has practical consequences that richer formats cannot match. Markdown files diff line by line in version control, so a docs change shows up in code review exactly like a code change. They survive tool migrations — content written for Jekyll a decade ago moves to Hugo or Next.js without conversion. And they keep writing friction low enough that developers actually maintain documentation, which is the real reason every README, changelog, and wiki converged on the format.

The trade-off is that Markdown covers common formatting only. Tables beyond simple grids, precise image sizing, and complex layout require either raw HTML embedded in the document or platform-specific extensions — which is exactly how the flavor problem described below came to exist.

A Markdown renderer works in two phases. The block phase walks the document line by line and carves it into block-level structures: headings, paragraphs, block quotes, list items, fenced code blocks, horizontal rules. Blank lines are the primary separator, and indentation decides whether a line continues the previous block or starts something new. This phase builds a tree — a list contains items, items contain paragraphs or nested lists.

The inline phase then runs inside each block, resolving emphasis, strong emphasis, inline code, links, and images. It is the trickier phase because delimiters interact: asterisks can open or close emphasis depending on the characters around them, backticks protect their contents from all other processing, and link syntax nests brackets inside parentheses. The renderer walks the finished tree and emits an HTML element per node — a heading node becomes an h2, a list becomes ul and li elements.

For its first decade, Markdown had no specification — only Gruber's original description and a reference script, both silent on dozens of edge cases. How does emphasis behave mid-word, or a list interrupted by a blank line? Every implementation guessed differently, so the same file rendered differently everywhere. CommonMark, published in 2014, resolved those ambiguities in an exhaustive spec with hundreds of test examples, and most serious renderers now build on it. This history is worth knowing for one reason: when a preview disagrees with a platform, it is usually because the two sit on different sides of some edge case or extension, not because either is broken.

GitHub Flavored Markdown, or GFM, is CommonMark plus the extensions people actually notice: pipe tables, task list checkboxes, strikethrough with double tildes, automatic linking of bare URLs, and fenced code blocks with language tags for syntax highlighting. Because GitHub is where most developers meet Markdown, GFM is the de facto standard — but it is not universal.

The divergences bite in specific places. Discord supports emphasis and code but not tables or headings in normal messages. Reddit historically ran its own dialect with quirks around escaping. Static site generators each ship a particular engine — Hugo uses goldmark, Jekyll defaults to kramdown — with their own extension sets and front-matter conventions. Platform previews can even differ from the platform itself when a renderer updates.

The working habit that follows: write to CommonMark for anything portable, use GFM extensions when the destination is GitHub or a GFM-compatible engine, and always check a file against its actual destination before publishing. A live-preview editor covers the drafting loop; the final paste into your CMS, repo, or docs platform deserves one last visual check on the platform itself.

A handful of syntax details cause the overwhelming majority of mangled Markdown. Learn these once and most rendering surprises disappear:

The most common case is the README. Repository readmes are a project's landing page, and pushing a commit just to discover a broken table is a slow feedback loop; drafting in a live-preview editor gets the structure right before the file ever reaches the repo. The same applies to pull request descriptions and issue templates long enough to have real structure.

Blog posts for static sites are the second big case. Hugo, Jekyll, Astro, and Next.js content workflows all consume Markdown files, and a browser editor gives you the writing environment without opening the whole project in an IDE — draft the post, preview it, then drop the file into the content directory. HTML export covers the adjacent need: a CMS or email tool that accepts HTML but not Markdown gets clean semantic markup — proper heading tags, paragraphs, and lists — converted from a source that was pleasant to write.

There are also cases where Markdown is the wrong tool, and recognizing them saves effort. Print-faithful layout, multi-column design, and pixel-controlled documents belong in a word processor or design tool. Deeply interactive content needs a richer format. Markdown excels precisely at structured prose — documentation, articles, notes, wikis — where content matters and layout should be the renderer's job.