Obsidian Markdown: your files, the syntax, and what stays portable

The base flavour: CommonMark plus GFM

Before any of Obsidian's own additions, the ground floor is standard. Obsidian follows CommonMark, the precise specification most modern parsers implement. On top of that sit the GitHub Flavored Markdown extensions. Everything below behaves exactly as it would in a README:

# Heading 1
## Heading 2

**bold**, *italic*, ~~strikethrough~~, `inline code`

- bullet
  - nested bullet
1. numbered item

- [ ] unchecked task
- [x] finished task

> A blockquote

| Column A | Column B |
| -------- | -------- |
| cell     | cell     |

```python
print("fenced code with a language label")
```

[A standard link](https://mdeditor.tw)
![Standard image](picture.png)

A sentence with a footnote.[^1]

[^1]: The footnote body.

Which parts are GFM rather than original Markdown

Tables, task lists, strikethrough, autolinked URLs and footnotes all come from the GFM layer. That is worth knowing before you move text somewhere older. Our GFM guide covers the dialect in full, and the tables guide handles the construct that breaks most often.

The setting to find on day one

Look for strict line breaks in Settings. It decides what a single newline does. With it on, Obsidian follows CommonMark and folds the next line into the same paragraph. With it off, one press of Enter shows as a visible break. That is friendlier for quick notes, but it is not what a strict parser will do later.

Tip: Unsure which half of a note is portable? Paste it into the editor on this site. Whatever still shows its raw characters is Obsidian-only. Whatever renders travels, with one caveat: math and Mermaid render here and on GitHub, but they are extensions, so a plainer parser will still show them as text.

The syntax Obsidian adds on top

Everything in this section is Obsidian's own. It is genuinely useful, and none of it is standard Markdown. Files that use it are still valid text files. Other renderers just print the raw characters.

Wiki-links and embeds

[[Project Alpha]]                   link to a note by its name
[[Project Alpha|the alpha work]]    link with different display text
[[Project Alpha#Goals]]             link straight to a heading
![[Project Alpha]]                  embed the whole note inline
![[Project Alpha#Goals]]            embed only that section
![[diagram.png]]                    embed an image from the vault
![[diagram.png|300]]                embed the image at 300px wide

The only difference between a link and an embed is the leading exclamation mark. That mirrors how standard Markdown tells a link from an image, which the links guide walks through. Wiki-links are what drive backlinks and the graph view, and they survive a rename, because Obsidian rewrites every reference for you.

Block references

The deadline is 14 March. ^deadline

Then from any other note:

[[Meeting notes#^deadline]]
![[Meeting notes#^deadline]]

A caret plus an identifier at the end of a block marks that one paragraph, list item or table. You can then link or embed it on its own. Build the reference through Obsidian's link picker and the identifier comes out as a short random string rather than a readable word.

Callouts

> [!note] An optional custom title
> The body of the callout goes here.

> [!warning]- Starts folded
> A minus sign makes the callout collapsed by default,
> a plus sign makes it collapsible but open.

Types include note, tip, info, todo, success, question, warning, failure, danger, bug, example and quote. Each has its own colour and icon. Callouts have one lovely property: they are built on blockquote syntax, so a tool that has never heard of them still shows something sensible.

Tags and comments

#project  #project/alpha  #reading/2026

%%This text is invisible in reading view.%%

%%
A multi-line comment works the same way.
%%

Tags are written inline with no space after the hash, and a slash nests them into a hierarchy. Comments wrapped in double percent signs vanish in reading view but stay in the file, which is handy for notes to yourself.

Careful: One character does two jobs here. #project with no space is a tag, while # project with a space is a level-one heading. Get it backwards and a quiet tag becomes a giant title.

YAML front matter and properties

A block fenced by three hyphens at the very top of a file is YAML front matter. It has to be the first thing in the note, with nothing above it. Obsidian reads it and shows it as the properties panel:

---
title: Weekly review
tags:
  - review
  - planning
aliases: [Weekly, Review note]
date: 2026-03-14
published: false
---

# Weekly review

The body of the note starts here.

Keys that already mean something

Property values are typed, so a date behaves like a date and a checkbox like a boolean. Two keys are wired straight into the app:

• tags feeds the same tag system as inline hashtags, so both show up in the same searches.
• aliases lets one note be found and wiki-linked under several names.

The safest non-standard thing in your files

Front matter is not part of CommonMark, but Obsidian did not invent it either. Hugo, Jekyll, Astro and most static site generators expect this exact block. That is why a vault makes a workable blog source. Renderers that do not know it usually hide it or show a small table, so little is lost when a note travels.

Math and diagrams

Math with dollar signs

Obsidian renders LaTeX math through MathJax. One dollar sign on each side gives you inline math. A doubled pair gives a centred display block:

Inline: the identity $a^2 + b^2 = c^2$ sits in the sentence.

$$
\frac{d}{dx} e^{x} = e^{x}
$$

Diagrams stored as text

Diagrams use a fenced code block with mermaid as the language label. The diagram then lives in the file as readable text instead of an image, using the same language-tag trick that fenced code blocks use everywhere else:

```mermaid
graph TD
  A[Rough idea] --> B[Permanent note]
  B --> C[Published article]
```

Both are extensions rather than core Markdown, yet both travel unusually well. GitHub renders Mermaid blocks and dollar-sign math inside Markdown files, so notes that use them often survive a trip to a repository. The editor on this site renders both as well, with KaTeX for the math and Mermaid for the diagrams, which makes it a quick way to check a note before you push it anywhere. Lightweight preview panes elsewhere show the code block as code instead. That is a graceful failure, not a broken file.

What travels, what does not, and how to stay portable

Here is the honest support matrix. The last column is what a CommonMark or GFM renderer outside Obsidian will show a reader:

The fix for the syntax that breaks

Start with the switch. Open Settings → Files & links and turn the wiki-link option off. New links are then written the standard way, as [Note](Note.md). Set the companion option, new link format, to relative paths. Those survive leaving the vault more often than absolute ones do.

Only the rows marked No really break, and the wiki-link is the painful one, because links are the whole point of a note system. The rest degrade gently. Callouts become quotes, tags become words, comments become visible. Nothing is lost. It just looks plainer.

Careful: The setting applies to new links only. Every [[double bracket]] already in the vault stays exactly as it is until you rewrite it.

Making an existing vault portable

1. Turn off wiki-links, so everything you write from now on is standard.
2. Rewrite the double-bracket links you already have, one folder at a time.
3. Replace ![[image.png]] embeds with ![alt text](image.png).
4. Decide which callouts are worth keeping as plain blockquotes, and flatten the rest.

Note embeds have no standard equivalent at all, so step three is where most of the work sits. If images matter to you, the images guide covers the portable form and the alt-text rules that come with it.

Opening your vault in another editor

VS Code, GitHub and a browser tab

Because the vault is only a folder, nothing stops you opening it elsewhere. Point VS Code at it and you get highlighting, multi-file search and Git. Push the folder to GitHub and every note renders as a web page, with wiki-links sitting there as literal text. Drop a note into the editor here and the standard parts preview live, math and Mermaid blocks included.

If the notes are headed for a website

Plan for that early. Decide whether to write in the portable subset or to run a conversion step, because most static site generators need wiki-links and embeds rewritten before they build. If the notes are only ever for you, use every Obsidian feature you like. The bill arrives only at the moment you leave.

Two references are worth keeping open while you write: the cheat sheet for standard syntax, and the complete guide for the detail behind it. Still choosing a dialect? Our answer on which Markdown flavor to write in is the short version.

Chat and forum tools play by different rules again. A note pasted into Discord loses its tables, and the same note on Reddit loses its single line breaks. The platform hub lines every app up side by side.