Obsidian Markdown: Complete Guide to Links, Callouts & Vault Workflows (2026)
Master Obsidian-flavored Markdown — wikilinks, tags, YAML frontmatter, callouts, embeds, block references, plugins, and Git sync patterns for a future-proof personal knowledge base.
Obsidian is a local-first Markdown vault — a folder of plain .md files on your disk, enriched with features no other mainstream editor matches: wikilinks, backlinks, graph view, block references, and a plugin ecosystem that turns notes into a personal knowledge system.
Because files stay plain text, everything you write remains portable. But Obsidian also extends Markdown with conventions that only work inside the app (or compatible tools like Quartz, MkDocs Material, and some static site generators).
This guide covers standard Markdown in Obsidian, every Obsidian-specific extension, vault organization patterns, and the workflows researchers, developers, and writers use to keep thousands of notes searchable for years.
What makes Obsidian different
| Concept | Standard Markdown | Obsidian |
|---|---|---|
| File storage | Varies | Plain .md on disk |
| Internal links | [text](page.md) | [[Page]] wikilinks |
| Tags | Not standard | #tag and #nested/tag |
| Metadata | Optional YAML | Frontmatter + Properties UI |
| Embeds | HTML <img> | ![[note]] transclusion |
| Callouts | GFM alerts (limited) | > [!type] admonitions |
| Graph | None | Backlinks + global graph |
Your vault is just a folder. You can open it in VS Code, sync it with Git, publish it with Hugo — Obsidian is the lens, not the cage.
Standard Markdown (fully supported)
Obsidian renders CommonMark plus GitHub Flavored Markdown:
# Heading 1
## Heading 2
**bold** and *italic* and ~~strikethrough~~
- Bulleted list
1. Numbered list
- [ ] Task list item
> Block quote
`inline code`
| Col A | Col B |
| ----- | ----- |
| 1 | 2 |
Fenced code blocks with syntax highlighting:
```python
def hello():
print("vault")
```
Standard Markdown links work everywhere:
[Markdown Viewer](https://trymarkdownviewer.com)
[Relative note](./daily/2026-06-05.md)
Use the Markdown syntax tutor to practice GFM rules inside your vault.
Wikilinks — Obsidian's superpower
Wikilinks connect notes without knowing the file path:
See [[Daily notes]] for the template.
Link with alias: [[Daily notes|today's log]]
Link to heading: [[Project Alpha#Milestones]]
Link to block: [[Project Alpha#^task-12]]
How wikilinks resolve
Obsidian matches [[Page Name]] to a file when:
- Filename matches (case-insensitive on Windows).
- Full path is unique —
folder/Page Name.mdworks as[[Page Name]]if no collision. - Aliases in frontmatter override display names.
Add aliases in YAML:
---
aliases:
- Alpha
- Project A
---
Now [[Alpha]] resolves to this note.
Backlinks panel
Every note shows linked mentions and unlinked mentions — text that matches a note title but is not yet a wikilink. One click converts plain text to [[wikilink]]. This is the feature that makes Obsidian irreplaceable for research: you discover connections you forgot you made.
Check for duplicate note titles with the slug collision checker before publishing a vault to the web.
Tags
Tags are #word tokens embedded in the note body or frontmatter:
#project/alpha #status/active
Meeting with #person/alice about #topic/api-design.
Rules:
- Tags support nesting:
#work/meetings/2026. - Tags in frontmatter (
tags: [work, api]) index the same as inline tags. - Tags are case-sensitive on some sync setups — pick lowercase and stick to it.
The tag pane gives a frequency-sorted overview — lightweight taxonomy without maintaining a rigid folder tree.
YAML frontmatter and Properties
Obsidian reads YAML between --- delimiters at the top of a file:
---
title: API Design Notes
date: 2026-06-05
tags:
- project/alpha
- api
status: draft
aliases:
- API notes
---
Obsidian 1.4+ exposes frontmatter as Properties in the UI — same data, friendlier editing.
Common fields teams standardize on:
| Field | Purpose |
|---|---|
title | Display name (can differ from filename) |
date | Created or published date |
tags | Structured taxonomy |
aliases | Extra wikilink targets |
cssclasses | Per-note styling (with Minimal theme etc.) |
publish | Boolean gates for Quartz / Obsidian Publish |
Edit frontmatter in bulk with the frontmatter editor before committing to Git.
Callouts (admonitions)
Obsidian callouts extend blockquotes with a type marker:
> [!note]
> Neutral context readers can skim.
> [!tip]
> Shortcuts and quality-of-life hints.
> [!warning]
> Breaking changes or data loss risk.
> [!danger]
> Irreversible actions.
> [!quote]
> Attribution and citations.
Foldable callouts hide long content:
> [!faq]- Collapsed by default
> Answer hidden until expanded.
> [!info]+ Expanded by default
> Visible on load, can collapse.
Generate syntax for Obsidian, GitHub, Docusaurus, and MkDocs in the callout generator.
Callouts vs. GFM alerts
GitHub now supports > [!NOTE] alerts in READMEs and issues. Obsidian callouts use the same syntax family but support more types, custom titles, and fold modifiers. When publishing vault notes to GitHub, preview in the GFM checklist.
Embeds and transclusion
Embed another note, image, PDF page, or heading block inline:
![[Meeting 2026-06-05]]
![[Architecture#Diagram]]
![[screenshots/ui.png|400]]
![[slides.pdf#page=3]]
Behavior:
- Embedded notes render full content (respecting their own headings).
- Embed a heading to transclude one section.
- Embed a block with
![[Note#^block-id]]. - Maximum embed depth prevents infinite recursion.
Transclusion is powerful for dashboards: one Home.md note can assemble today's tasks, weekly goals, and project status from smaller atomic notes.
Block references
Assign a block ID with ^id at the end of a paragraph or list item:
The API rate limit is 100 requests per minute. ^rate-limit
Link from anywhere:
As noted in [[API docs#^rate-limit]], stay under 100 rpm.
Block IDs must be unique within a file. Use descriptive slugs (^decision-log-2026-q2) not random strings — future you will grep for them.
Headings and outline
Obsidian supports ATX headings # through ######:
# H1 — usually one per note
## H2 — major sections
### H3 — subsections
The outline panel mirrors heading hierarchy. Reorder sections logically with the outline reorder tool before splitting long notes.
Naming convention: lead with H1 matching the note title (or title property). Deep stacks of H2/H3 beat multiple H1s in a single file.
Links: when to use wikilinks vs. Markdown
| Situation | Prefer |
|---|---|
| Internal vault notes | [[Wikilink]] |
| External URLs | [label](https://...) |
| Static site export (Hugo) | Markdown links + slug |
| Open vault in VS Code | Both work; wikilinks show as raw text without plugin |
For vaults published to the web, run the link checker on exported HTML or the Markdown source before deploy.
Math
Obsidian supports LaTeX via MathJax:
Inline: $e^{i\pi} + 1 = 0$
Block:
$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$
Enable Strict line breaks and math in Settings → Editor if equations fail to render.
Audit unclosed delimiters with the math inventory — a single stray $ breaks rendering for the rest of the note.
Mermaid diagrams
Fenced mermaid blocks render flowcharts, sequence diagrams, and Gantt charts:
```mermaid
flowchart LR
Draft --> Review --> Publish
Review -->|reject| Draft
```
Use the diagram tools hub to prototype diagrams, then paste into vault notes. For GitHub-bound exports, confirm Mermaid renders in the target (GitHub README supports it; not all SSG themes do).
Images and attachments
Markdown syntax

Wikilink syntax (Obsidian-preferred)
![[diagram.png]]
Store attachments in a dedicated attachments/ or assets/ folder. Obsidian's default is to put pasted images in the vault root — change Default location for new attachments in Settings → Files & Links to avoid clutter.
Relative paths survive Git sync and static export. Avoid file:// URLs.
Templates and daily notes
Templates are notes with placeholders inserted via core Templates plugin or Templater:
---
date: {{date:YYYY-MM-DD}}
tags:
- daily
---
# {{date:dddd, MMMM D}}
## Log
## Tasks
- [ ]
Daily notes auto-create YYYY-MM-DD.md from a template — the backbone of journaling, Zettelkasten capture, and meeting logs.
Pair templates with the reading time tool to estimate how long exported compilations will take to read.
Vault organization patterns
PARA method
| Folder | Holds |
|---|---|
Projects/ | Active work with deadlines |
Areas/ | Ongoing responsibilities |
Resources/ | Reference material |
Archive/ | Inactive items |
Zettelkasten
Atomic notes with IDs like 202606051430-api-rate-limits.md, heavy linking, minimal folders. Titles become declarative sentences: "API rate limits protect shared infrastructure."
Map of Content (MOC)
Hub notes that only contain curated wikilinks:
# API Documentation MOC
- [[Authentication]]
- [[Rate limits]]
- [[Error codes]]
- [[Changelog]]
MOCs scale better than deep folder trees when cross-links are dense.
Flat vs. nested
Obsidian search and graph view reduce the need for folders. Many power users keep < 3 folder levels and rely on tags + MOCs instead.
Plugins worth knowing
| Plugin | Category | Why |
|---|---|---|
| Dataview | Query | SQL-like queries over frontmatter |
| Templater | Automation | Advanced templates with JS |
| Calendar | Navigation | Visual daily note picker |
| Excalidraw | Diagrams | Hand-drawn figures in vault |
| Git | Sync | Commit/push from Obsidian |
| Linter | Quality | Enforce heading caps, spacing |
| Advanced Tables | Editing | Excel-like table editing |
Plugins do not lock you in — disable them and your files remain valid Markdown (minus Dataview query blocks, which are fenced code).
Sync and Git workflows
Obsidian Sync (paid)
End-to-end encrypted, conflict resolution, version history. Best for multi-device users who do not want to manage Git.
Git sync (free)
- Initialize repo in vault root.
.gitignoreworkspace cache:.obsidian/workspace.json,*.tmp.- Commit
.obsidian/plugins/andcommunity-plugins.jsonif you want settings portable. - Use the Obsidian Git plugin or commit from terminal.
Merge conflicts appear as standard Git conflict markers inside .md files — resolve in Obsidian or VS Code, then commit.
Publish to web
- Obsidian Publish — hosted, selective note publishing.
- Quartz — static site from vault Markdown.
- MkDocs Material — docs sites with Obsidian-style callouts.
- Hugo / Astro — import
content/from vault subfolder.
Run HTML to Markdown on legacy web content before importing into a vault.
Obsidian vs. other platforms
| Feature | Obsidian | Notion | GitHub README |
|---|---|---|---|
Plain .md on disk | ✅ | ❌ | ✅ (in repo) |
| Wikilinks | ✅ | ❌ | ❌ |
| Backlinks graph | ✅ | Partial | ❌ |
| Real-time collab | ❌ | ✅ | via PRs |
| Databases | via Dataview | native | ❌ |
| Offline | ✅ | ⚠️ | ✅ (clone) |
See the Notion Markdown guide for paste quirks when moving content between apps.
Common Obsidian mistakes
1. Non-unique filenames. Meeting.md in three folders confuses wikilinks — use descriptive names or paths.
2. Giant monolithic notes. Split at ~500 lines; link with MOCs instead.
3. Pasting from Notion without cleanup. Export artifacts and broken links multiply — convert through the Markdown formatter.
4. Random attachment sprawl. Configure default attachment folder on day one.
5. Plugin overload. Ten plugins doing overlapping jobs slows startup and confuses teammates.
6. Wikilinks in published exports. Configure your SSG to convert [[links]] or use Markdown links for public output.
7. Skipping frontmatter conventions. Without tags and date, Dataview queries return empty.
API and automation
For programmatic vault processing — extract frontmatter, convert HTML, validate links — use the Markdown Viewer API:
curl -X POST https://trymarkdownviewer.com/api/v1/extract/frontmatter \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"markdown": "---\ntitle: Note\n---\n\nBody"}'
See extract frontmatter docs and the API playground for interactive testing.
Preview vault notes in the browser
Before sharing a note with non-Obsidian users, paste it into the Markdown editor. Standard GFM renders faithfully. Expect differences for:
[[wikilinks]]— shown as text unless preprocessed.![[embeds]]— not transcluded in browser preview.> [!callout]— may render depending on preview flavor; use the callout generator to verify target platform.
Related articles
- Docs-as-code guide — publish vault notes as a static site
- Notion Markdown guide — block editor quirks and import/export
- GitHub README guide — ship project docs from vault notes
- Markdown links guide — URL vs. relative vs. anchor patterns
- Markdown frontmatter — edit YAML without breaking notes
- Best Markdown editors — how Obsidian compares in 2026
Quick reference
| Syntax | Purpose |
|---|---|
[[Note]] [[Note|alias]] [[Note#Heading]] | Wikilinks |
[[Note#^block]] | Block reference link |
#tag #nested/tag | Tags |
--- YAML frontmatter --- | Metadata |
> [!note] > [!tip]+ > [!warning]- | Callouts (fold modifiers + / -) |
![[file]] ![[note#section]] | Embeds |
^block-id | Block ID anchor |
$inline$ / $$block math$$ | LaTeX math |
```mermaid fence | Diagrams |
- [ ] task | GFM checklist |
Obsidian's bargain is simple: write in Markdown, think in graphs. Master wikilinks, callouts, and frontmatter early — every note you add makes the vault smarter.
Written by Markdown Viewer Team. Found this useful? Try the editor →
Keep reading
Hand-picked articles related to this one.
Master Markdown in Microsoft Teams — chat compose formatting, the differences from GitHub GFM, Adaptive Card markdown, and incoming-webhook message formatting for bots and CI.
Every WhatsApp formatting trick — bold, italic, strikethrough, monospace, bulleted and numbered lists, block quotes, and inline code — plus what breaks when you paste from elsewhere.
Complete Telegram formatting guide — MarkdownV2 vs legacy Markdown vs HTML parse modes, the full escaping rules, spoilers, custom emoji, and in-app shortcuts that actually work.