Obsidian has grown from a niche note-taking app to one of the most popular tools among developers, writers, and researchers. It’s built entirely around plain Markdown files stored locally — and that combination of local-first storage with a rich linking system has attracted millions of users.

But Obsidian’s Markdown isn’t quite standard Markdown. It layers on proprietary extensions that make it incredibly powerful for knowledge management, but those extensions can break compatibility when you share files elsewhere.

This guide covers everything you need to use Markdown effectively in Obsidian: what’s standard, what’s Obsidian-specific, which plugins are worth using, and what workflows actually work in practice.

What Makes Obsidian Different

Most Markdown editors convert .md files to HTML for display. Obsidian does that too, but it adds:

  • Bi-directional links between notes via wiki-links
  • Graph view — a visual map of how your notes connect
  • Local-first storage — your files are plain .md files in a folder you control
  • Plugin ecosystem — hundreds of community plugins that extend core functionality
  • Live Preview mode — renders Markdown while you type, like a WYSIWYG editor

This architecture matters for Markdown because some features you’ll use daily in Obsidian won’t render anywhere else.

Standard Markdown in Obsidian

Obsidian supports most of CommonMark and the GFM (GitHub Flavored Markdown) extensions. The following all work as expected:

# Heading 1
## Heading 2

**Bold**, *italic*, ~~strikethrough~~, `inline code`

- Unordered lists
1. Numbered lists

[Links](https://example.com)
![Images](image.png)

| Column A | Column B |
|----------|----------|
| Cell     | Cell     |

Task lists work and render as interactive checkboxes in Reading mode:

- [x] Completed task
- [ ] Pending task

Footnotes are fully supported:

This claim needs a source.[^1]

[^1]: Here is the source.

Math works with $ for inline and $$ for block (no extension required in recent Obsidian versions):

Inline: $E = mc^2$

Block:
$$
\sum_{i=1}^{n} x_i = \frac{n(n+1)}{2}
$$

Obsidian-Specific Markdown Features

These features work in Obsidian but will produce plain text or broken output in GitHub, VS Code, Notion, and most other renderers.

The defining feature of Obsidian. Instead of standard Markdown links, you link between notes with double brackets:

[[Note Title]]
[[Folder/Note Title]]
[[Note Title|Custom display text]]

Clicking a wiki-link opens that note. If the note doesn’t exist, Obsidian creates it — making it trivial to build a connected web of ideas.

Portability warning: Wiki-links render as plain text in GitHub, VS Code, and Notion. If your notes ever need to live outside Obsidian, use standard Markdown links instead.

Callouts

Obsidian supports callout blocks using a syntax based on GitHub’s alert syntax:

> [!NOTE]
> This is a note.

> [!TIP]
> A helpful tip.

> [!WARNING]
> Be careful here.

> [!DANGER]
> This action is destructive.

You can add a custom title:

> [!WARNING] Check your config first
> This replaces the default "Warning" heading.

And make them collapsible with + (open by default) or - (closed by default):

> [!NOTE]+ This is open by default
> Content here.

> [!NOTE]- This is closed by default
> Content here.

Full list of supported types: NOTE, TIP, INFO, SUCCESS, QUESTION, WARNING, FAILURE, DANGER, BUG, EXAMPLE, QUOTE, ABSTRACT.

GitHub supports only a small subset (NOTE, TIP, IMPORTANT, WARNING, CAUTION). Most other tools render these as plain blockquotes.

Embedded Notes

You can embed another note’s content inline:

![[Note Title]]
![[Note Title#Section Heading]]
![[Note Title#^block-id]]

This is powerful for building modular knowledge bases — a hub note can pull in content from many individual notes. Entirely Obsidian-specific.

Tags

Tags work both inline and in YAML frontmatter:

---
tags: [productivity, markdown, writing]
---

This note is also tagged #inline and #writing.

In recent Obsidian versions, nested tags work: #tools/markdown.

Block References

You can create a linkable ID for any paragraph:

This is the paragraph I want to reference. ^my-block-id

Then reference it from another note:

[[Note Title#^my-block-id]]

YAML Frontmatter

Obsidian uses YAML frontmatter heavily. Core properties:

---
title: My Note
date: 2026-05-01
tags: [markdown, obsidian]
aliases: [alternative name, other alias]
---

aliases is Obsidian-specific: it lets you link to a note by any of its aliases. If a note is titled “JavaScript” with aliases: [JS], you can link to it as [[JS]].

From Obsidian 1.4+, frontmatter is displayed in a Properties panel rather than raw YAML. You can define custom property types (text, number, date, list, checkbox) in Settings → Properties.

For a deeper dive, see our YAML frontmatter in Markdown guide.

Essential Plugins

Obsidian’s plugin ecosystem is where it really shines.

Core Plugins Worth Enabling

  • Templates — insert predefined note templates with a hotkey
  • Daily Notes — one note per day for journaling and task tracking
  • Backlinks — sidebar showing all notes that link to the current one
  • Outline — jump between headings without scrolling
  • Tag Pane — browse all tags across your vault

Community Plugins Worth Installing

Dataview — query your vault like a database with SQL-like syntax:

```dataview
TABLE date, tags FROM "Projects" WHERE status = "active" SORT date DESC
```

This turns your notes into a queryable database. One of the most powerful plugins in the ecosystem.

Templater — more powerful templates than the core plugin. Supports dynamic content like current date, prompts, and JavaScript snippets.

Calendar — sidebar calendar showing which days have Daily Notes.

Excalidraw — embed hand-drawn diagrams directly in notes.

Kanban — turn any note into a Trello-style board using Markdown lists.

Advanced Tables — tab-based table editing with auto-formatting (similar to our Markdown Table Formatter tool, but live in the editor).

Linter — auto-formats Markdown on save: consistent heading styles, frontmatter order, whitespace, etc.

Workflows That Work Well in Obsidian

Daily Notes

Enable the Daily Notes core plugin and set a template. A simple template:

---
date: {{date}}
tags: [daily]
---

## Today's Focus
- 

## Notes
- 

## Done
-

Link daily notes to project notes using wiki-links: Working on [[Project Alpha]] today.

Zettelkasten (Atomic Notes)

The Zettelkasten method works naturally in Obsidian:

  1. Each note covers exactly one idea — kept short and self-contained
  2. Notes link to related notes via wiki-links
  3. An index note collects links to related atomic notes
  4. The graph view reveals emergent connections you didn’t plan

PARA Method

Projects, Areas, Resources, Archives — a folder structure for keeping things organized:

📁 Projects/     # Active projects with a deadline
📁 Areas/        # Ongoing responsibilities (health, finance, work)
📁 Resources/    # Reference material organized by topic
📁 Archive/      # Completed or inactive items

Use wiki-links freely within Projects and Areas. Resources serve as reference notes linked from anywhere.

MOCs (Maps of Content)

A Map of Content is an index note linking to many related notes — a navigation layer on top of your atomic notes:

# Markdown MOC

## Core Syntax
- [[Headings in Markdown]]
- [[Markdown Lists]]
- [[Markdown Tables]]

## Advanced
- [[Markdown Callouts]]
- [[Markdown Frontmatter]]
- [[Markdown Math]]

Portability: What to Avoid When Sharing Files

If your Obsidian vault stays private, use every feature freely. If you need to share notes on GitHub, in a team wiki, or in Confluence, avoid:

Feature Portable alternative
[[wiki-links]] Standard [text](path.md) links
![[embedded notes]] Copy content manually
[!CUSTOM] callout types Stick to NOTE, TIP, WARNING (GitHub-compatible)
#^block-id references Use heading references #section-name
Dataview queries Export to a static table

For a full breakdown of what works across platforms, see Markdown across platforms: what works where.

Syncing Obsidian Across Devices

Obsidian Sync (paid, ~$10/month) is the easiest option: end-to-end encrypted, version history included, works on iOS and Android.

Free alternatives:

  • iCloud — works well on macOS/iOS; Windows support is inconsistent
  • Dropbox / Google Drive — store your vault folder inside a synced directory
  • Git — version control your vault with a private repo; use the Git community plugin for in-app commits

If syncing via Git, add these to .gitignore to avoid conflicts:

.obsidian/workspace.json
.obsidian/workspace-mobile.json

Keep .obsidian/plugins/*/manifest.json committed so plugin configs sync across devices.

Obsidian vs Other Markdown Editors

Feature Obsidian VS Code Typora iA Writer
Local file storage ✅ ✅ ✅ ✅
Wiki-links ✅ ❌ ❌ ❌
Graph view ✅ ❌ ❌ ❌
Plugin ecosystem ✅ extensive ✅ extensive limited ❌
WYSIWYG / Live Preview ✅ ❌ ✅ ✅
Free ✅ core app ✅ Paid Paid
Mobile app ✅ ❌ ❌ ✅

Summary

Obsidian is the most capable local Markdown editor for knowledge management, but it has a vocabulary of proprietary extensions you need to understand. The short version:

  • Use wiki-links and callouts freely if notes stay in Obsidian
  • Use standard Markdown links if you need files to work elsewhere
  • Dataview + Templater unlock the most workflow power
  • YAML frontmatter is the bridge between your notes and Dataview queries
  • Sync via Obsidian Sync for simplicity, or Git for version history