Skip to main content

Obsidian Markdown Formatting

Every Obsidian formatting syntax with copy-ready examples: wikilinks, embeds, block links, callouts, highlights, comments, properties, and the settings that change how your notes render.

Short answer

Yes, Obsidian is a Markdown editor: every note is a plain .md file, and it supports CommonMark, GitHub Flavored Markdown (tables, task lists, ~~strikethrough~~), and LaTeX math. On top of that it adds its own syntax: [[wikilinks]], ![[embeds]], ^block-ids, ==highlights==, %%comments%%, and > [!note] callouts. Those extras are Obsidian-only: GitHub and most other Markdown apps show them as plain text.

Embeds (Transclusion)

Put ! in front of any wikilink to show the target inside the current note. Notes, sections, blocks, images, audio, video, PDFs, canvases, and bases can all be embedded. On desktop you can also drag a file into a note to embed it.

Embed a whole note

An ! in front of any internal link embeds the target. Embeds update when the source changes.

Obsidian
![[Note Title]]
Embed a section

Embeds just the part of the note under that heading.

Obsidian
![[Note Title#Heading]]
Embed a single block

Embeds one paragraph, list, or other block by its ID.

Obsidian
![[Note Title#^block-id]]
Embed and resize an image

|300 sets the width in pixels and keeps the aspect ratio. |300x200 sets width and height.

Obsidian
![[image.png|300]]
External image with a size

Images from a URL use Markdown image syntax. The same |width or |widthxheight goes after the alt text.

Obsidian
![alt text|300](https://example.com/photo.jpg)
Embed a PDF at a page

#page=N opens a specific page; #height=N sets the viewer height. Combine them with &.

Obsidian
![[Document.pdf#page=3&height=400]]
Embed audio or video

Audio (mp3, wav, m4a, ogg, flac, webm, 3gp) and video (mp4, webm, mov, mkv, ogv) get a built-in player. Playback depends on your device's codecs.

Obsidian
![[recording.mp3]]

Block References

A block is a paragraph, list item, quote, callout, or table. Give it an ID and you can link to it or embed it from any note. You rarely type the ID yourself: type [[Note#^ and pick a block from the list, and Obsidian adds a random ID such as ^37066d to that block. Type [[^^ to search blocks across the whole vault.

Paragraphs: ID at the end of the line
This paragraph has a block ID. ^my-quote

[[Other Note#^my-quote]]
![[Other Note#^my-quote]]

^my-quote, after a space at the end of the line, marks that paragraph as a block (in a note called Other Note).

[[Other Note#^my-quote]] links to it from any note; ![[Other Note#^my-quote]] embeds it.

IDs use Latin letters, numbers, and dashes only, and must be unique within the note.

Lists, quotes, callouts, tables: ID on its own line
- Buy milk
- Book flights
- Renew passport

^travel-list

> A quote worth reusing.

^good-quote

For structured blocks, put the ID on a line of its own with a blank line before and after. The ID then covers the whole list or quote.

You can also tag a single list item by ending that bullet with ^id. Linking to part of a quote, callout, or table isn't supported.

Tags

Tags are vault-wide labels. They are case-insensitive (#Tag and #TAG are the same tag), can't contain spaces, and show up in the Tags view and in search with tag:#project.

Inline tag

A # followed directly by text, with no space, is a tag. Tags show in the Tags view and search (tag:#project).

#project
Nested tag

Slashes nest tags. Searching tag:project also matches #project/research and #project/research/draft.

#project/research/draft
Tags with numbers

Letters, numbers, _ , - and / are allowed, plus Unicode such as emoji. A tag needs at least one non-number: #1984 is not a tag, #y1984 is.

#Q3-2026
Tags as a property

The tags property must be a YAML list. Leave off the # inside properties.

---
tags:
  - project
  - research
---

Callouts

A callout is a blockquote whose first line is [!type]. Obsidian has 13 types plus aliases. The type is case-insensitive, and any type Obsidian doesn't recognize renders as a note. Callout bodies can hold Markdown, wikilinks, and embeds.

[!note]
> [!note]
> Default callout. Unknown types fall back to this one.
Renders in Obsidian as
Note

Default callout. Unknown types fall back to this one.

[!tip]aliases: hint, important
> [!tip]
> Helpful advice or shortcuts. Aliases: hint, important.
Renders in Obsidian as
Tip

Helpful advice or shortcuts. Aliases: hint, important.

[!success]aliases: check, done
> [!success]
> Positive outcomes or completed work. Aliases: check, done.
Renders in Obsidian as
Success

Positive outcomes or completed work. Aliases: check, done.

[!warning]aliases: caution, attention
> [!warning]
> Cautions or risks. Aliases: caution, attention.
Renders in Obsidian as
Warning

Cautions or risks. Aliases: caution, attention.

[!danger]aliases: error
> [!danger]
> Critical hazards. Alias: error.
Renders in Obsidian as
Danger

Critical hazards. Alias: error.

All 13 callout types (plus aliases)
[!note]
[!tip]

also: [!hint], [!important]

[!success]

also: [!check], [!done]

[!warning]

also: [!caution], [!attention]

[!danger]

also: [!error]

[!question]

also: [!help], [!faq]

[!quote]

also: [!cite]

[!bug]
[!todo]
[!abstract]

also: [!summary], [!tldr]

[!info]
[!example]
[!failure]

also: [!fail], [!missing]

Titles, folding, and nesting
> [!note]+ Open by default
> Click the title to collapse.

> [!warning]- Closed by default
> Click the title to expand.

> [!tip] Title-only callout

> [!question] Can callouts be nested?
> > [!todo] Yes, add another >

Text after the type replaces the default title. Leave out the body for a title-only callout.

+ right after the type makes the callout foldable and open; - makes it foldable and closed. See collapsible sections for the equivalents on other platforms.

Nest callouts by adding a level of >.

GitHub alerts render too. GitHub uses the same > [!NOTE] syntax but only five types: NOTE, TIP, IMPORTANT, WARNING, and CAUTION. All five work in Obsidian, where important is an alias of tip and caution an alias of warning. Stick to those five if a note also has to look right on GitHub. Custom types can be styled with a CSS snippet targeting .callout[data-callout="my-type"].

Highlights

Wrap text in double equals signs (==text==) to highlight it. This is not part of CommonMark or GFM: GitHub, Notion, Reddit, Slack, and Discord all show the equals signs as literal text.

Highlight syntax
This sentence has ==highlighted text== in the middle.
This sentence has highlighted text in the middle.
Highlight colorsObsidian 1.14+
==πŸ”΄Important==
==🟠Follow up==
==🟑Remember this==
==🟒Completed==
==πŸ”΅Reference==
==🟣Idea==

Put a color emoji right after the opening == to pick red, orange, yellow, green, blue, or purple. Without one, the highlight uses your theme's default color.

You can also choose a color from the formatting menu, and typing == suggests colors. Other apps will show the emoji and the equals signs as plain text. For colored text elsewhere, see Markdown text color.

Comments

Wrap text in double percent signs (%%hidden%%) to hide it in Reading view and on Obsidian Publish. Comments stay visible while you edit, in both Live Preview and Source mode, so they work as notes to yourself. Other Markdown apps show %% as literal text; use an HTML comment when the file has to render elsewhere (see Markdown comments).

Inline and block comments
This paragraph is %%hidden inline%% visible.

%%
This whole block is
hidden in Reading view.
%%
Reading view

This paragraph is visible.

An inline comment opens and closes on the same line. A block comment starts with %% at the beginning of a line and ends at the next %%; leave it unclosed and Reading view hides the rest of the note.

Math (LaTeX)

Obsidian renders LaTeX math with MathJax. Inline math goes between single dollar signs, $...$; block math goes between $$ lines.

Inline math
The Pythagorean theorem is $a^2 + b^2 = c^2$.
The Pythagorean theorem is a2 + b2 = c2.
Block math
$$
\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}
$$
Ξ£ (n=1 to ∞) 1/nΒ² = π² / 6

Properties (YAML Frontmatter)

Properties are YAML at the very top of a note, between two --- lines. Type --- on the first line or press Cmd/Ctrl + ; and Obsidian shows a property editor. To see the raw YAML instead, set Settings β†’ Editor β†’ Properties in document to Source.

Default and custom properties
---
tags:
  - project
  - research
aliases:
  - Project Alpha
cssclasses:
  - wide-page
status: draft
due: 2026-11-01
related: "[[Project Brief]]"
---

# Note body starts here

tags β€” a YAML list, no # prefix

aliases β€” other names for the note. Pick one in link autocomplete and Obsidian writes [[Note|Alias]]

cssclasses β€” CSS classes for styling this note with a snippet

Any other key β€” your own property, typed as text, list, number, checkbox, date, or date & time

Wrap links in quotes, and don't use Markdown in values: it isn't rendered. The old singular keys tag, alias, and cssclass stopped working as default properties in Obsidian 1.9.

Bases: database views of your properties
```base
filters:
  and:
    - file.hasTag("book")
views:
  - type: table
    name: Reading list
```

Bases is a core plugin that shows notes as rows and their properties as columns, in table, card, list, kanban, or map layouts. The data stays in your Markdown files.

Save a base as a .base file and embed it with ![[Books.base]], or write it inline in a base code block like this one. Dataview, which does something similar with queries, is a community plugin.

Mermaid Diagrams

Open a fenced code block with ```mermaid and write standard Mermaid syntax. Mermaid is built in, no plugin required, but since Obsidian 1.13 each vault shows a one-time banner asking you to allow Mermaid rendering. Add the internal-link class to turn nodes into links to notes with the same name.

Flowchart with linked nodes
```mermaid
flowchart LR
  A[Inbox] --> B{Has tag?}
  B -- Yes --> C[Projects]
  B -- No --> D[Archive]

  class A,C,D internal-link;
```

Line Breaks and Strict Mode

By default, Obsidian keeps single line breaks in Reading view: press Enter once and the next line starts on a new line. Standard Markdown doesn't do that. Turn on Settings β†’ Editor β†’ Strict line breaks to follow the spec, where a single newline joins the lines and a line break needs two trailing spaces or <br>. Turn it on if your notes also get published to GitHub or a static site, so Reading view matches what they will show.

Same Markdown, two settings
Line one
Line two
Strict line breaks off (default)
Strict line breaks on

Reading view vs Live Preview vs Source mode

Obsidian has one reading view and two editing modes. Some syntax behaves differently depending on which one you're in.

FeatureSource modeLive PreviewReading view
EditableYesYesNo
Markdown syntax shownAll of itOnly where the cursor isNone
Wikilinks and embeds renderNoYesYes
%%comments%%VisibleVisibleHidden
Inline footnotes ^[...]Raw textRaw textRendered
Math and Mermaid renderNoYesYes
DefaultOptional editing modeDefault editing modeToggle with Cmd/Ctrl+E

Switch between editing and Reading view with Cmd/Ctrl + E. Pick Live Preview or Source mode under Settings β†’ Editor β†’ Default editing mode, or assign a hotkey to Toggle Live Preview/Source mode.

Standard Markdown Still Works

Everything from CommonMark and GFM works in Obsidian: headings, lists, tables, code blocks, task lists, strikethrough, links, images, and footnotes. Ordered lists can use 1. or 1), and code blocks get syntax highlighting from a language name after the opening fence.

Standard Markdown in Obsidian
# Heading

**Bold** and *italic* text.

- [x] Task one
- [ ] Task two

| Col A | Col B |
|-------|-------|
| 1     | 2     |

Common Mistakes

The Obsidian-specific gotchas that break links, blocks, and formatting most often.

Don't

[[Q&A: Week #3]]

Do

[[Q&A - Week 3]] (rename the note)

Note names containing # | ^ : %% [[ or ]] may not work as link targets, because those characters mean something inside a wikilink (# is a heading, | is display text, ^ is a block). Rename the note.

Don't

| [[Note|Alias]] | ![[img.png|200]] |

Do

| [[Note\|Alias]] | ![[img.png\|200]] |

Inside a table, an unescaped | starts a new column. Put a backslash before the pipe in link aliases and image sizes.

Don't

Some text.^my_id

Do

Some text. ^my-id

Block IDs need a space before the caret and can only use Latin letters, numbers, and dashes. For lists, quotes, callouts, and tables, put the ID on its own line after a blank line instead.

Don't

<div>**Important**</div>

Do

<div><b>Important</b></div>

Obsidian does not render Markdown inside HTML elements, so the asterisks show up literally. Use HTML tags inside HTML, or keep the Markdown outside the tag.

Don't

%% draft notes, never closed

Do

%% draft notes %%

A block comment runs until the next %%. Forget to close it and Reading view hides the rest of the note.

Don't

# tag

Do

#tag

At the start of a line, # plus a space is a heading. Tags have no space after the # and can't contain spaces at all: use #camelCase, #snake_case, or #kebab-case.

Don't

[[Setup Guide]] in a README on GitHub

Do

[Setup Guide](Setup%20Guide.md)

Wikilinks, ==highlights==, %%comments%% and callout types beyond GitHub's five show as plain text outside Obsidian. If notes leave your vault, turn off Settings β†’ Files and links β†’ Use [[Wikilinks]] so Obsidian writes standard Markdown links.

Quick Reference

Every Obsidian Markdown feature at a glance.

Syntax / FeatureWorks?Notes
CommonMark basics (bold, italic, lists, headings)YesNotes are plain .md files. Everything in CommonMark works.
GFM tablesYesRight-click a table in Live Preview to add, move, or sort rows and columns. Escape | inside cells as \|.
GFM task lists (- [ ])YesClickable checkboxes. Any character in the brackets, such as [?] or [-], counts as checked.
Strikethrough (~~text~~)YesDouble tildes.
Wikilinks [[Note]]YesObsidian-only. [[Note|text]], [[Note#Heading]], [[Note#^id]], [[Folder/Note]].
Markdown links to notesYes[text](Note%20Name.md). Encode spaces as %20 or wrap the path in < >.
Embeds ![[Note]]YesNotes, sections, blocks, images (|width), audio, video, PDFs (#page=N), canvases, and bases.
Block IDs ^block-idYesLatin letters, numbers, and dashes only. Obsidian-only.
Tags (#tag, #parent/child)YesNo spaces, at least one non-number, case-insensitive. Also set with the tags property.
Highlights (==text==)YesObsidian-only. Since 1.14, a color emoji picks one of six colors: ==πŸ”΄text==.
Comments (%%text%%)YesHidden in Reading view, visible while editing. Obsidian-only.
Callouts (> [!note])Yes13 types plus aliases, foldable with - or +, nestable. GitHub's five alert types render too.
Math ($...$ and $$...$$)YesLaTeX, rendered with MathJax.
Mermaid (```mermaid)YesBuilt in. Since 1.13 each vault asks once before rendering Mermaid.
Footnotes ([^1])YesReference footnotes work everywhere. Inline ^[note] footnotes render in Reading view only.
Properties (YAML frontmatter)Yestags, aliases, cssclasses built in. No Markdown in values; quote links: "[[Note]]".
Bases (.base files, ```base)YesCore plugin: table, card, list, kanban, and map views of your notes' properties.
HTMLPartialSanitized: <script> is stripped, and Markdown inside an HTML element is not rendered.
UnderlinePartialNo Markdown syntax. Use <u>text</u>.

Frequently Asked Questions

Does Obsidian use Markdown?

Yes. Every Obsidian note is a plain-text .md file in a folder on your device (your vault), so any text editor can open it. Obsidian supports CommonMark, GitHub Flavored Markdown (tables, task lists, strikethrough), and LaTeX math, and adds its own extensions: wikilinks ([[Note]]), embeds (![[Note]]), block IDs (^id), highlights (==text==), comments (%%text%%), and callouts (> [!note]). Those extensions show as plain text in other Markdown apps.

What is the difference between [[wikilinks]] and Markdown links in Obsidian?

[[Note Title]] links by note name and needs no file extension or URL encoding. A Markdown link, [Note Title](Note%20Title.md), works in any Markdown app but needs spaces encoded as %20 (or the path wrapped in < >). Obsidian treats both the same and updates both when you rename a note. To make Obsidian insert Markdown links instead of wikilinks, turn off Settings β†’ Files and links β†’ Use [[Wikilinks]].

How do I link to a block in Obsidian?

Type [[, the note name, then #^, and pick the block from the suggestions. Obsidian adds a random ID such as ^37066d to that block and completes the link. To choose your own ID, end the line with a space and ^your-id (Latin letters, numbers, and dashes only). For lists, quotes, callouts, and tables, put the ID on its own line with a blank line before and after. Link with [[Note#^your-id]] or embed with ![[Note#^your-id]].

How do I resize an image in Obsidian?

Add a pipe and a width: ![[image.png|300]] makes the image 300 pixels wide and keeps its aspect ratio, and ![[image.png|300x200]] sets both width and height. Images from a URL take the size after the alt text: ![alt|300](https://example.com/image.png). Inside a table, escape the pipe: ![[image.png\|300]].

How do I highlight text in Obsidian?

Wrap it in double equals signs: ==highlighted text==. Since Obsidian 1.14 you can choose one of six colors by putting a color emoji right after the opening ==, such as ==πŸ”΄urgent== or ==🟒done==, or by picking a color from the formatting menu. Without an emoji the highlight uses your theme's default color. Other Markdown apps show the == literally.

What are the differences between Reading view, Live Preview, and Source mode?

Reading view shows the finished note and can't be edited. Live Preview, the default editing mode, renders formatting in place and reveals the Markdown only where your cursor is. Source mode shows all the raw Markdown. %%comments%% are visible in both editing modes and hidden in Reading view, and inline footnotes (^[...]) render only in Reading view. Cmd/Ctrl+E switches between editing and Reading view.

How do I add a line break in Obsidian?

Press Enter. With Strict line breaks off, which is the default, a single line break shows up in Reading view. If you turn on Settings β†’ Editor β†’ Strict line breaks, Obsidian follows standard Markdown instead: a single newline joins the two lines, so end the line with two spaces (or use <br>) for a line break, and leave a blank line for a new paragraph.

How do tags work in Obsidian?

Type # followed by the tag with no space: #meeting. Tags can use letters, numbers, underscores, hyphens, slashes for nesting (#project/research), and Unicode such as emoji, but not spaces, and they need at least one non-number (#1984 is not a tag). Tags are case-insensitive. You can also list tags in the tags property, written without the #.

How do I create callouts in Obsidian?

Start a blockquote with [!type] on its first line, optionally followed by a title: > [!warning] Check this first. Obsidian has 13 types (note, abstract, info, todo, tip, success, question, warning, failure, danger, bug, example, quote) plus aliases such as tldr, faq, and error. Add - after the type to collapse it by default (> [!note]-) or + to make it foldable but open. The type is case-insensitive, unknown types fall back to note, and GitHub's five alert types render too.

Can I use HTML in Obsidian notes?

Yes, but Obsidian sanitizes it: <script> is stripped, and Markdown inside an HTML element is not rendered, so <div>**bold**</div> shows the asterisks. HTML blocks also can't contain blank lines. Common uses are underline (<u>text</u>), styled text (<span style="color:red">), image sizing (<img width="300">), and <iframe> embeds of web pages.

Does Obsidian support Mermaid diagrams?

Yes, with no plugin. Put the diagram in a ```mermaid code block. Since Obsidian 1.13, each vault shows a one-time banner asking you to allow Mermaid rendering; after you accept, flowcharts, sequence diagrams, timelines, and other Mermaid diagrams render in Live Preview and Reading view.

What is YAML frontmatter in Obsidian?

It's the properties block at the very top of a note, between two --- lines. Obsidian's built-in properties are tags, aliases, and cssclasses, plus publish, permalink, description, image, and cover for Obsidian Publish. Any other key becomes your own property with a type: text, list, number, checkbox, date, or date & time. Wrap links in quotes ("[[Note]]"), and don't expect Markdown to render inside values. The Bases core plugin builds table, card, and kanban views from these properties; Dataview is a separate community plugin.