Obsidian — How it works

A single-file, long-term reference. Starts with the most common formatting and ends with rarer / plugin-driven features. Includes examples, use-cases and tips so you can copy/paste straight into your notes.

Shortcuts to use for Obsidian: Quick syntax summary (copy, paste reference)

Table of contents

  1. Basic Markdown (the essentials)

  2. Obsidian‑specific basics (links, tags, frontmatter)

  3. Embeds & Transclusion (files, headings, blocks)

  4. Images & media (importing, resizing, attributes)

  5. Callouts & admonitions (core + plugin differences)

  6. Lists, tasks & checkboxes (core + Tasks plugin)

  7. Tables & table tips

  8. Code blocks, syntax highlighting & special block types

  9. Math (KaTeX), diagrams (Mermaid) and visual blocks

  10. Inline fields, YAML frontmatter & Properties

  11. Dynamic content: embedded queries, Dataview, Tasks queries

  12. Interactivity: Templater, Buttons, Meta‑Bind (quick examples)

  13. Styling and customisation: CSS snippets, classes, attributes

  14. Canvas, Excalidraw & other visual formats

  15. Rarer / plugin-driven features (definition lists, Pandoc, PlantUML, etc.)

  16. Practical tips, pitfalls & quick reference table

1 — Basic Markdown (the essentials — start here)

These are the things you’ll use 90% of the time.

Headings

# H1
## H2
### H3

H1

H2

H3

Use case: pages, section titles, TOC anchor targets.

Bold / Italic / Strikethrough / Highlight

**bold**  _italic_  ***bold+italic***  ~~strikethrough~~  ==highlight==

bold italic bold+italic strikethrough highlight

Use case: emphasis, inline highlights for quick scanning.

Paragraphs & line breaks

Links

[External link text](https://example.com)
Internal note name          # Obsidian wiki link
Page#Heading               # link to a heading inside another note
Page#^blockID              # link to a specific block by block-id
Display text          # link with custom display text

External link text
[[Internal note name]] # Obsidian wiki link
[[Page#Heading]] # link to a heading inside another note
[[Page#^blockID]] # link to a specific block by block-id
Display text # link with custom display text

Use case: connect notes; use pipe | to change the visible link label.

Images (basic)

![](https://example.com/image.png)         # external
!image.png                             # embed a file from your vault (recommended)

# external
!image.png # embed a file from your vault (recommended)

Inline code & fenced code blocks

`inline()`

inline()

```javascript
console.log('fenced code block')

console.log('fenced code block')

Use case: code snippets, copyable examples.

Blockquote

> Quoted text
> > Nested quote

Quoted text

Nested quote

Horizontal rule

---

Task lists / checkboxes (core)

- [ ] todo item
- [x] done item

Footnotes

This is a footnote.[^1]

[^1]: The footnote text.

This is a footnote.[1]

Comments

2 — Obsidian‑specific basics

Internal links / wiki links — [[Note Title]] is the most powerful Obsidian primitive. Links create backlinks, suggestions, and graph edges.

Aliases in frontmatter (so [[ autocompletes alternate titles)

---
aliases: ["Main Page", "Home"]
---

aliases: ["Main Page", "Home"]

Tags

#tag #topic/subtopic

#tag #topic/subtopic

Aliases in-line: alias text — only affects this link’s display.

Block references — create a block anchor by appending a caret id to a block:

This is a paragraph I want to reference.
{ #myblock}

This is a paragraph I want to reference. ^myblock

Then elsewhere: ![[Note Name#^myblock]] or [[Note Name#^myblock]] (link or transclude).

Backlinks & graph — creating links populates backlinks & the graph automatically.

Properties panel (frontmatter editor) — Obsidian can prompt you for frontmatter keys (tags, aliases, cssclasses) using its Properties / Frontmatter UI.

3 — Embeds & Transclusion (the '!' syntax)

Obsidian can embed whole files or specific parts.

Embed a whole note (transclusion)

!Some Note    # embeds the rendered content of Some Note inline

![[Some Note]] # embeds the rendered content of Some Note inline

Embed a heading or block

!Some Note#Heading
!Some Note#^blockID

![[Some Note#Heading]]
![[Some Note#^blockID]]

Notes & pitfalls:

Embedded search/query (core) — show live search results inside a note (works with Search core plugin):

```query
tag:#meeting "project x"

tag:#meeting "project x"

(Results auto-update as your vault changes.)

4 — Images & media (how to import and control them)

Ways to get images into a vault

Embedding from the vault

![[image.png]]                  # embed
!200             # set width to 200 px (shortcut)
!200x100         # width x height (if supported)

![[image.png]] # embed
!200 # set width to 200 px (shortcut)
!200x100 # width x height (if supported)

In tables: escape vertical bars or use \| to avoid column splitting when using !200.

External images & web embeds

![](https://i.imgur.com/xyz.png)

Video/audio — embed local files or remote links:

!video.mp4                  # local video; plays inline if the format is supported
![](https://www.youtube.com/watch?v=VIDEOID)   # YouTube embed using markdown image syntax
<!-- or using iframe: -->
<iframe src="https://www.youtube.com/embed/VIDEOID" width="560" height="315"></iframe>

![[video.mp4]] # local video; plays inline if the format is supported
# YouTube embed using markdown image syntax

Accepted file types & tips

5 — Callouts & Admonitions (note boxes)

Core (Obsidian) callout syntax — create a callout by starting a blockquote with a [!TYPE] tag:

> [!NOTE]
> This is a note callout.
>
> - It can contain lists and multiple lines.
Note

This is a note callout.

  • It can contain lists and multiple lines.

Common types: NOTE, TIP, WARNING, IMPORTANT, INFO, DANGER (Obsidian renders icons and colours). Use uppercase but Obsidian is forgiving.

Admonitions plugin (community)

```ad-note
Some content

Some content

Use cases:

6 — Lists, tasks & checkboxes

Standard lists

- item
* item
+ item
1. ordered
  1. ordered

Task lists

- [ ] This is an open task
- [x] Completed task

Tasks plugin (community) — enables querying and richer task metadata and interactive task queries inside notes:

```tasks
not done
due before tomorrow
sort by due

not done
due before tomorrow
sort by due

Use case: build dashboards of open tasks across your vault, toggle tasks from query results, schedule and recurring tasks.

Nesting & subtasks

7 — Tables & tips

Markdown table

| Name | Value |
|------|-------|
| Foo  | 123   |
Name Value
Foo 123

Formatting tips

Large data and CSV

8 — Code blocks, syntax highlighting & special block languages

```lang
code...

code...

Special codeblock languages (rendered)

```mermaid
graph TD
  A-->B

graph TD
  A-->B

Plugin-defined block languages (examples):

Notes:

9 — Math (KaTeX), diagrams (Mermaid) and visual blocks

Inline math

Euler: $e^{i\pi} + 1 = 0$

Euler: eiπ+1=0

Block math

$
\int_0^1 x^2 dx = 1/3
$
∫01x2dx=1/3

Mermaid

```mermaid
sequenceDiagram
    Alice->>Bob: Hello Bob

sequenceDiagram
    Alice->>Bob: Hello Bob

PlantUML / other diagram types

10 — Inline fields, YAML frontmatter & Properties

YAML frontmatter — put metadata at top of file inside --- block:

---
aliases: ["Main Page"]
tags: [project, draft]
date: 2024-01-02
author: "Jane"
---

Use case: publishing, Dataview queries, templates, note metadata.

Inline fields value — widely used by Dataview and other tools:

status:: todo
difficulty:: easy

Properties UI — Obsidian provides a Properties / Frontmatter editor that maps YAML to a GUI.

Tip: keep frontmatter minimal and consistent (same typed keys across notes) to use Dataview/Bases reliably.

11 — Dynamic content: embedded queries, Dataview, Tasks queries

Embedded query (core)

```query
file:Notes folder

file:Notes folder

Dataview plugin — treat your vault like a database. Examples:

| File | status | file.mtime |
| ---- | ------ | ---------- |

{ .block-language-dataview}`

| File | status | file.mtime |
| ---- | ------ | ---------- |

{ .block-language-dataview}`

**Inline Dataview value**
```md
Obsidian and how to work with it   # dataview inline JavaScript-style evaluation

Obsidian and how to work with it # dataview inline JavaScript-style evaluation

Dataview JS — full JS access:

<div><table class="dataview table-view-table"><thead class="table-view-thead"><tr class="table-view-tr-header"><th class="table-view-th"><span>File</span><span class="dataview small-text">0</span></th><th class="table-view-th"><span>Title</span></th></tr></thead><tbody class="table-view-tbody"></tbody></table><div class="dataview dataview-error-box"><p class="dataview dataview-error-message">Dataview: No results to show for table query.</p></div></div>`

<div><table class="dataview table-view-table"><thead class="table-view-thead"><tr class="table-view-tr-header"><th class="table-view-th"><span>File</span><span class="dataview small-text">0</span></th><th class="table-view-th"><span>Title</span></th></tr></thead><tbody class="table-view-tbody"></tbody></table><div class="dataview dataview-error-box"><p class="dataview dataview-error-message">Dataview: No results to show for table query.</p></div></div>`

**Tasks plugin queries** — examples use ```tasks code block:
```md
```tasks
not done
path includes "Daily"
sort by created

not done
path includes "Daily"
sort by created

Use cases: dashboards, weekly review pages, task rollups, dynamic tables of notes, automated reports.

12 — Interactivity: Templater, Buttons, Meta‑Bind (quick examples)

Templater (community)


<% tp.date.now("YYYY-MM-DD") %>

Use case: daily notes with automated TODOs, insert title, unique IDs.

Buttons plugin

Meta‑Bind / Inline fields editors

Important: these interactive features depend on community plugins. Install from the Community Plugins gallery and read plugin docs for exact code syntax.

13 — Styling and customisation: CSS snippets, classes, attributes

CSS snippets

Custom classes / block classes

---
cssclasses: [compact, small-toc]
---

Markdown attributes (rare / plugin-driven)

Tip: prefer CSS snippets for consistent vault-level styling; use class-based styling when you need targeted formatting.

14 — Canvas, Excalidraw & other visual formats

Canvas (core)

Excalidraw plugin

Use case: concept maps, visual note summaries, workflows and architectural diagrams.

15 — Rarer / plugin-driven features (less common but powerful)

This section lists features usually provided by community plugins or by extended markdown parsers.

Definition lists (not core) — plugins or Pandoc-style extensions can add Term\n: Definition syntax.

Pandoc extended markdown — some plugins implement Pandoc features (superscript ^x^, subscript ~x~, extended list styles).

PlantUML — community plugin or external tool to render UML diagrams.

Admonition / Advanced callouts — plugins such as Admonition or enhanced callouts add collapsible, templated and CSS-targeted blocks.

Custom block languages — many plugins register code block languages (e.g., dataview, tasks, ad-note, meta-bind-button, tldraw, excalidraw), which turn code blocks into rendered UI.

Sync & remote embedding restrictions — some embedding features behave differently when using Obsidian Publish, sync services or mobile; test on target platform.

16 — Practical tips, pitfalls & quick reference

Keep templates and frontmatter consistent — consistent key names (status, tags, project) make queries predictable.

Naming files — use human-readable names and add aliases if you want machine-friendly IDs and human-friendly titles.

Escaping characters — in tables or when using pipe characters inside links/aliases, escape | with \|.

Performance — heavy Dataview / large queries across hundreds of thousands of notes can impact performance. Use limit and narrow FROM paths.

When to use a plugin — if your use-case involves dynamic queries (Dataview), automation (Templater, Buttons), or visual drawings (Excalidraw, Canvas), consider installing those community plugins.

Where to go next / plugin checklist

If you want to extend your Obsidian with the features, the community plugins to inspect first are:

  1. The footnote text. ↩︎