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.
Wikilinks
Obsidian's signature feature. Type [[ and an autocomplete menu lists every note in your vault. Obsidian rewrites links for you when you rename a note (Settings β Files and links β Automatically update internal links), and clicking a link to a note that doesn't exist yet creates it.
Links to a note by name. The .md extension is optional: [[Note Title.md]] works too. Type [[ for autocomplete.
[[Note Title]]A pipe separates the target from the text shown in the note.
[[Note Title|Display Text]]Add # and the heading text. Chain subheadings with more hashes: [[Note#Heading#Subheading]].
[[Note Title#Heading]]Leave out the note name. Type [[## to search headings across the whole vault.
[[#Heading]]#^ plus a block ID links to one paragraph, list item, or other block. See Block References below.
[[Note Title#^block-id]]Folder paths start at the vault root and use forward slashes, even on Windows.
[[Projects/Note Title]][[ still autocompletes, but Obsidian writes a standard Markdown link such as [Note Title](Note%20Title.md) that GitHub and other apps understand.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.
An ! in front of any internal link embeds the target. Embeds update when the source changes.
![[Note Title]]Embeds just the part of the note under that heading.
![[Note Title#Heading]]Embeds one paragraph, list, or other block by its ID.
![[Note Title#^block-id]]|300 sets the width in pixels and keeps the aspect ratio. |300x200 sets width and height.
![[image.png|300]]Images from a URL use Markdown image syntax. The same |width or |widthxheight goes after the alt text.
#page=N opens a specific page; #height=N sets the viewer height. Combine them with &.
![[Document.pdf#page=3&height=400]]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.
![[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.
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.
- Buy milk
- Book flights
- Renew passport
^travel-list
> A quote worth reusing.
^good-quoteFor 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.
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]
> Default callout. Unknown types fall back to this one.Default callout. Unknown types fall back to this one.
> [!tip]
> Helpful advice or shortcuts. Aliases: hint, important.Helpful advice or shortcuts. Aliases: hint, important.
> [!success]
> Positive outcomes or completed work. Aliases: check, done.Positive outcomes or completed work. Aliases: check, done.
> [!warning]
> Cautions or risks. Aliases: caution, attention.Cautions or risks. Aliases: caution, attention.
> [!danger]
> Critical hazards. Alias: error.Critical hazards. Alias: error.
also: [!hint], [!important]
also: [!check], [!done]
also: [!caution], [!attention]
also: [!error]
also: [!help], [!faq]
also: [!cite]
also: [!summary], [!tldr]
also: [!fail], [!missing]
> [!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 >.
> [!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.
This sentence has ==highlighted text== in the middle.==π΄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.
Math (LaTeX)
Obsidian renders LaTeX math with MathJax. Inline math goes between single dollar signs, $...$; block math goes between $$ lines.
The Pythagorean theorem is $a^2 + b^2 = c^2$.$$
\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{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.
---
tags:
- project
- research
aliases:
- Project Alpha
cssclasses:
- wide-page
status: draft
due: 2026-11-01
related: "[[Project Brief]]"
---
# Note body starts heretags β 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.
```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.
```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.
Line one
Line twoLine one
Line two
Line one Line two
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.
| Feature | Source mode | Live Preview | Reading view |
|---|---|---|---|
| Editable | Yes | Yes | No |
| Markdown syntax shown | All of it | Only where the cursor is | None |
| Wikilinks and embeds render | No | Yes | Yes |
| %%comments%% | Visible | Visible | Hidden |
| Inline footnotes ^[...] | Raw text | Raw text | Rendered |
| Math and Mermaid render | No | Yes | Yes |
| Default | Optional editing mode | Default editing mode | Toggle 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.
# Heading
**Bold** and *italic* text.
- [x] Task one
- [ ] Task two
| Col A | Col B |
|-------|-------|
| 1 | 2 |Heading
Bold and italic text.
- 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 / Feature | Works? | Notes |
|---|---|---|
| CommonMark basics (bold, italic, lists, headings) | Yes | Notes are plain .md files. Everything in CommonMark works. |
| GFM tables | Yes | Right-click a table in Live Preview to add, move, or sort rows and columns. Escape | inside cells as \|. |
| GFM task lists (- [ ]) | Yes | Clickable checkboxes. Any character in the brackets, such as [?] or [-], counts as checked. |
| Strikethrough (~~text~~) | Yes | Double tildes. |
| Wikilinks [[Note]] | Yes | Obsidian-only. [[Note|text]], [[Note#Heading]], [[Note#^id]], [[Folder/Note]]. |
| Markdown links to notes | Yes | [text](Note%20Name.md). Encode spaces as %20 or wrap the path in < >. |
| Embeds ![[Note]] | Yes | Notes, sections, blocks, images (|width), audio, video, PDFs (#page=N), canvases, and bases. |
| Block IDs ^block-id | Yes | Latin letters, numbers, and dashes only. Obsidian-only. |
| Tags (#tag, #parent/child) | Yes | No spaces, at least one non-number, case-insensitive. Also set with the tags property. |
| Highlights (==text==) | Yes | Obsidian-only. Since 1.14, a color emoji picks one of six colors: ==π΄text==. |
| Comments (%%text%%) | Yes | Hidden in Reading view, visible while editing. Obsidian-only. |
| Callouts (> [!note]) | Yes | 13 types plus aliases, foldable with - or +, nestable. GitHub's five alert types render too. |
| Math ($...$ and $$...$$) | Yes | LaTeX, rendered with MathJax. |
| Mermaid (```mermaid) | Yes | Built in. Since 1.13 each vault asks once before rendering Mermaid. |
| Footnotes ([^1]) | Yes | Reference footnotes work everywhere. Inline ^[note] footnotes render in Reading view only. |
| Properties (YAML frontmatter) | Yes | tags, aliases, cssclasses built in. No Markdown in values; quote links: "[[Note]]". |
| Bases (.base files, ```base) | Yes | Core plugin: table, card, list, kanban, and map views of your notes' properties. |
| HTML | Partial | Sanitized: <script> is stripped, and Markdown inside an HTML element is not rendered. |
| Underline | Partial | No 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: . 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.
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).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.