What Obsidian, Notion and Logseq each need from Markdown
Last reviewed
Markdown is a standard in the way that a handshake is a standard. Every note tool reads it, none reads it identically, and the differences are concentrated in exactly the features a converted document depends on.
This is a practical comparison of what the three most common destinations do with a converted file, and what to change before importing into each.
8 minute read
What they agree on
All three read GitHub Flavored Markdown, which is what conversion produces. Headings, paragraphs, bold, italic, inline code, fenced code, blockquotes, bulleted and numbered lists and pipe tables mean the same thing in all three.
That covers most of a converted document. The disagreements are about organisation rather than syntax: what a note is, what links look like, and what metadata belongs at the top of a file.
Obsidian: the heading ladder is the structure
Obsidian stores plain files in a folder, so a converted Markdown file is already an Obsidian note with nothing done to it. What it needs is a correct heading ladder, because the outline pane, folding, heading links and much of search ranking are all derived from it.
It reads YAML front matter into properties, which drive queries and filters. A converter cannot generate any of it, since none of it is in the source document, so it is worth adding at import time.
One convention specific to Obsidian: let the filename carry the document title and start the body at level two. Obsidian already displays the filename as the note title, so an opening level-one heading that repeats it wastes the top of every note.
Notion: the import is a conversion of its own
Notion does not store Markdown. It stores blocks in a database and converts your file on import, which means the file is read once and then discarded — so anything Notion does not understand at that moment is lost rather than preserved as text.
The consequences are worth knowing before you import a hundred files.
- Front matter is not metadata to Notion. A YAML block at the top of the file is imported as ordinary text, so strip it or convert it into database properties first.
- Pipe tables become Notion tables, which is the good news. Malformed ones become paragraphs with visible pipes, so validate tables before importing rather than after.
- Nesting deeper than a few levels is flattened. Deeply nested outlines survive better if you split them across pages.
- Internal links have to be rebuilt. Relative Markdown links between files do not resolve to Notion pages, so cross-references need doing after import, inside Notion.
Logseq: the bullet is the unit
Logseq is outline-first. Every piece of content is a block in a bullet tree, and blocks rather than files are what you link to and reference.
A converted document is mostly paragraphs, which is the shape furthest from that model. Imported as-is it becomes a small number of very large blocks — technically fine, and it defeats the entire point of the tool, since a block you cannot reference precisely is a block you will not reference.
So a document destined for Logseq wants a genuine restructuring pass rather than a tidy-up: break the prose into one idea per bullet, nest under the headings, and accept that this is editorial work no converter can do for you. It is worth it for a document you will cite from repeatedly and not worth it for one you are archiving.
Side by side
| Storage | Obsidian: files. Notion: a database. Logseq: files of blocks |
|---|---|
| Import cost | Obsidian: none. Notion: a one-way conversion. Logseq: restructuring |
| Front matter | Obsidian: properties. Notion: plain text. Logseq: page properties |
| Links | Obsidian and Logseq: double brackets. Notion: rebuilt after import |
| Tables | All three, from valid GFM. All three fail on ragged rows |
| Wants most | Obsidian: headings. Notion: valid tables. Logseq: small blocks |
The one file that suits all three
If you do not yet know where a document is going, or it is going to more than one place, there is a shape that survives everywhere.
- A correct heading ladder, with no level skipped. This is the only property all three tools use, and the only one worth fixing before you know the destination.
- Valid tables, checked. A ragged table fails in all three, and it is the one error that is both common and completely deterministic.
- Front matter in a separate block at the very top, so it can be removed with one edit if the destination does not want it.
- Plain relative links rather than tool-specific link syntax. Converting relative links to double-bracket links is a find-and-replace; converting the other way is harder.
- Paragraphs left as paragraphs. Do not pre-break prose into bullets unless you know the file is destined for Logseq, because the reverse edit is much more work.
Moving between them later
Obsidian to Logseq is the easy direction, since both are files on disk and the double-bracket link syntax is shared. The work is structural rather than syntactic: breaking prose into blocks.
Notion outward is the hard direction and it is worth planning for at import rather than discovering later. Notion exports Markdown, but page identifiers are appended to filenames and internal links point at them, so an export needs a rename-and-relink pass before it is usable elsewhere. If there is any chance a corpus will move again, keeping the converted Markdown files as the source of truth and treating Notion as a view of them is far less painful than treating Notion as the archive.