Obsidian Markdown: Syntax Guide and Unique Features

Obsidian uses markdown as its file format, which means your notes are plain .md files that work with any text editor. On top of standard GFM syntax, Obsidian adds several proprietary extensions: wikilinks, callouts, embeds, block references, and more. These features are powerful inside Obsidian but do not render on other platforms.

This guide covers what standard markdown works in Obsidian, what Obsidian adds, and how to keep your documents portable.

Standard Markdown in Obsidian

All core GFM syntax works in Obsidian:

If you stick to these features, your Obsidian notes are fully portable.

Obsidian-Only Features

Wikilinks

Obsidian’s signature feature. Link to other notes by name using double brackets:

See [[My Other Note]] for details.
Link to a specific heading: [[My Note#Section Title]]
Link with display text: [[My Note|Click here]]

Wikilinks do not work outside Obsidian. On GitHub or other platforms, [[text]] renders as literal brackets. Obsidian can also use standard markdown links if you enable “Use [[Wikilinks]]” → off in settings.

Callouts (Admonitions)

Obsidian callouts use blockquote syntax with a type marker:

> [!NOTE]
> This is a note callout.

> [!WARNING]
> This is a warning callout.

> [!TIP]
> This is a tip callout.

> [!QUESTION]
> Is this a callout? Yes.

Obsidian renders these as styled boxes with icons and colors. The five types that overlap with GitHub alerts (NOTE, TIP, IMPORTANT, WARNING, CAUTION) render on GitHub too. Obsidian-specific types (QUESTION, BUG, EXAMPLE, QUOTE, and custom types) do not.

Foldable callouts:

> [!FAQ]- Click to expand
> This callout starts collapsed.

The - after the type makes it collapsed by default. + makes it expanded. This is Obsidian-only.

Embeds

Embed the content of another note or a specific block inline:

![[My Other Note]]
![[Note#Section Title]]
![[Note^block-id]]

The embedded content appears inline in the reading view. This is unique to Obsidian and not portable.

Block References

Reference a specific paragraph by its block ID:

Some paragraph text. ^my-block-id

Link to it from elsewhere: [[Note#^my-block-id]]

Block IDs are appended to the end of a line with a ^ prefix. Obsidian uses these for granular linking and embedding.

Image Sizing

Obsidian adds a pipe-based syntax for image dimensions:

![Logo|200](logo.png)
![Screenshot|600x400](screenshot.png)

The number after | sets the width. widthxheight sets both dimensions. This does not work on GitHub, VS Code, or other platforms. For portable sizing, use HTML: <img src="logo.png" width="200" />.

Highlights

This is ==highlighted text== in Obsidian.

Renders with a yellow background. Not supported in GFM, GitHub, or most other platforms.

Comments

%%This is a comment that does not render in reading view.%%

Obsidian-only. The content is hidden in reading view but visible in editing view. Use HTML comments (<!-- -->) for portable comments.

Math (LaTeX)

Inline: $E = mc^2$

Block:
$$
\sum_{i=1}^n x_i
$$

Obsidian renders LaTeX math using MathJax. GitHub also supports this syntax. VS Code needs an extension.

Mermaid Diagrams

```mermaid
graph TD
    A[Start] --> B[End]
```

Obsidian renders Mermaid diagrams natively. GitHub also supports this. VS Code needs the Mermaid extension.

Portability Guide

If you write in Obsidian but need your documents to work on GitHub, MDtoLink, or other platforms:

Obsidian setting for portable links: Go to Settings > Files and Links > toggle “Use [[Wikilinks]]” off. Obsidian then uses standard [text](path) syntax for new links.

Obsidian vs GitHub Markdown

Sharing Obsidian Notes

Obsidian stores notes as local files. To share them, you need to convert or publish:

For quick sharing of individual notes, MDtoLink is the fastest path: publish with one command and share the URL. Convert wikilinks to standard links first, or the tool handles the raw markdown as-is.

For publishing an entire vault as a website, Obsidian Publish is purpose-built. See our Obsidian Publish alternatives guide for comparisons.

FAQ

Does Obsidian use standard markdown?

Obsidian uses GFM (GitHub Flavored Markdown) as its base and adds proprietary extensions: wikilinks, callouts, embeds, highlights, and block references. Standard markdown features work perfectly. The extensions only work in Obsidian.

Are Obsidian notes portable?

The files are plain .md text files that any editor can open. However, Obsidian-specific features (wikilinks, embeds, highlights) will not render on other platforms. If portability matters, stick to standard GFM syntax or convert before sharing.

What is the difference between Obsidian callouts and GitHub alerts?

Both use the > [!TYPE] syntax. Five types overlap: NOTE, TIP, IMPORTANT, WARNING, CAUTION. Obsidian adds more types (QUESTION, BUG, EXAMPLE, QUOTE, custom) and supports collapsible callouts with + and -. GitHub only supports the five standard types.

Can I share an Obsidian note as a web page?

Yes. Export the note or use a publishing tool. MDtoLink publishes any .md file to a URL with one command. Obsidian Publish creates a full website from your vault. You can also push to GitHub where the README renders automatically.

Try It Out

Export your Obsidian notes and publish them with the MDtoLink editor or the Obsidian plugin. Get a shareable URL in seconds.

For the standard syntax reference, see the markdown cheat sheet. For VS Code as an alternative editor, see Markdown in VS Code.