Obsidian Flavored Markdown: Four Layers, and What Survives Without It

I use Obsidian to write the articles I publish on obsidianstats.com, and recently I added a table to one of them for the first time. In Obsidian it looked fine. When the site built the page, the table came out as a row of raw pipe characters. My site parses Markdown with remark, and remark left the pipes as text until I added remark-gfm. One small gap, and it sent me after a bigger question: which Markdown does Obsidian speak, and where did each part come from?

The Four Layers

Your vault is plain .md, which is the reason I stopped worrying about lock-in years ago. Portability turns out to be a separate question. What survives in another editor depends on which layer of Markdown that editor understands, and hardly at all on Obsidian. I had written Markdown for years without once wondering where any of it came from. A broken table is an odd thing to send you into history, but here we are. Four flavors, each one somebody else's idea, each stacked on the last.¹

Original Markdown

Markdown starts with John Gruber in 2004, with Aaron Swartz as a sounding board. His goal was almost stubborn: plain text that you can read as-is without decoding, that still turns cleanly into a web page. He shipped a syntax page and a Perl script, Markdown.pl, and that was the whole thing. Most of what people picture is already here. Headings, paragraphs, bold and italic, lists, blockquotes, links, images, code spans, indented code blocks, a horizontal rule. What is missing matters more. Fenced code blocks were not here yet. Tables and footnotes were still years off, which is why the one that broke my post could not have existed in this version at all.

CommonMark

Then Markdown got popular, and popular broke it. Everyone wrote a parser, Gruber's description was ambiguous, and they all disagreed in different ways. One file could render one way in a wiki and another through a converter, and each tool was sure it was right. Markdown Extra and MultiMarkdown had already wandered off and grown their own tables and footnotes. So in 2014 a group around John MacFarlane, with Jeff Atwood and people from GitHub, Reddit and Stack Overflow, wrote CommonMark: a strict spec with a test suite, so a parser could finally be checked against something. It barely added a feature, and that was the point. The one piece it did fold into the core is the fenced code block. Those triple backticks you use without thinking only became standard right here.

GitHub Flavored Markdown

GitHub needed more than that. Issues, pull requests and READMEs wanted tables and checkboxes, so GitHub had been running its own variant since around 2009 and turned it into a formal spec in 2017, built as a strict superset of CommonMark. This is the tier of everyday extras: tables, task lists with - [ ], strikethrough with ~~ and bare-URL autolinks. It is also, as it happens, the exact layer my table needed. remark-gfm is just those extensions bolted onto a CommonMark parser, which is why one line in my pipeline fixed the pipes.

Obsidian Flavored Markdown

Obsidian sits on top of all of it, adds LaTeX, and tries to do so without breaking anything underneath. People say Obsidian does not use standard Markdown, and this layer is where that reputation comes from. It is not one thing. Part of it is Markdown wearing a new coat: ==highlight== is really emphasis, and a > [!note] callout is a blockquote with a label. The rest was never Markdown. [[wikilinks]] and ![[embeds]] are wiki syntax, double brackets that predate Markdown itself. #tags are a convention borrowed from plain text everywhere. Math is LaTeX, fenced by $. That second group is the fragile part, and in a plain reader none of it means a thing.

What You Keep And What You Lose

Put the same split in a table. The lower layers render in any Markdown editor. The Obsidian rows are the ones that break, because a tool with no rule for a marker just prints it.

Two of these bite. %%comments%% are meant to stay private, yet every non-Obsidian renderer prints them in full. [[wikilinks]] quietly stop linking, so your navigation dies with no error at all. Publish a vault as-is elsewhere and you can leak private notes and break every link at once, with nothing to warn you.

Where This Stops

This map covers the built-in flavor and nothing else. Plugin syntax like Dataview fields, raw HTML and Bases each travel their own way. I left them out on purpose. For me, that is the whole point of plain files: the lower layers go anywhere, and I would rather give up a few Obsidian niceties than risk the notes themselves. The habit that saves you is small: paste a note into the new tool before you trust it, and watch what happens to the Obsidian-only parts.

What I Read

After the table broke, I went reading. These are the pages I checked while piecing the layers together:

• Original Markdown: https://daringfireball.net/projects/markdown/syntax
• CommonMark: https://commonmark.org/
• GitHub Flavored Markdown spec: https://github.github.com/gfm/
• Obsidian Flavored Markdown: https://obsidian.md/help/obsidian-flavored-markdown
• Markdown history and dates: https://en.wikipedia.org/wiki/Markdown
• Wiki-link origin, UseModWiki: https://en.wikipedia.org/wiki/UseModWiki
• GitHub math with MathJax: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/writing-mathematical-expressions