Skip to content
All posts
10 min read
markdown
obsidian
pkm
formatting
guide

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

ConceptStandard MarkdownObsidian
File storageVariesPlain .md on disk
Internal links[text](page.md)[[Page]] wikilinks
TagsNot standard#tag and #nested/tag
MetadataOptional YAMLFrontmatter + Properties UI
EmbedsHTML <img>![[note]] transclusion
CalloutsGFM alerts (limited)> [!type] admonitions
GraphNoneBacklinks + 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 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]]

Obsidian matches [[Page Name]] to a file when:

  1. Filename matches (case-insensitive on Windows).
  2. Full path is unique — folder/Page Name.md works as [[Page Name]] if no collision.
  3. Aliases in frontmatter override display names.

Add aliases in YAML:

---
aliases:
  - Alpha
  - Project A
---

Now [[Alpha]] resolves to this note.

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:

FieldPurpose
titleDisplay name (can differ from filename)
dateCreated or published date
tagsStructured taxonomy
aliasesExtra wikilink targets
cssclassesPer-note styling (with Minimal theme etc.)
publishBoolean 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.

SituationPrefer
Internal vault notes[[Wikilink]]
External URLs[label](https://...)
Static site export (Hugo)Markdown links + slug
Open vault in VS CodeBoth 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

![Alt text](./attachments/diagram.png)
![[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

FolderHolds
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

PluginCategoryWhy
DataviewQuerySQL-like queries over frontmatter
TemplaterAutomationAdvanced templates with JS
CalendarNavigationVisual daily note picker
ExcalidrawDiagramsHand-drawn figures in vault
GitSyncCommit/push from Obsidian
LinterQualityEnforce heading caps, spacing
Advanced TablesEditingExcel-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)

  1. Initialize repo in vault root.
  2. .gitignore workspace cache: .obsidian/workspace.json, *.tmp.
  3. Commit .obsidian/plugins/ and community-plugins.json if you want settings portable.
  4. 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

FeatureObsidianNotionGitHub README
Plain .md on disk✅❌✅ (in repo)
Wikilinks✅❌❌
Backlinks graph✅Partial❌
Real-time collab❌✅via PRs
Databasesvia Dataviewnative❌
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.

Quick reference

SyntaxPurpose
[[Note]] [[Note|alias]] [[Note#Heading]]Wikilinks
[[Note#^block]]Block reference link
#tag #nested/tagTags
--- YAML frontmatter ---Metadata
> [!note] > [!tip]+ > [!warning]-Callouts (fold modifiers + / -)
![[file]] ![[note#section]]Embeds
^block-idBlock ID anchor
$inline$ / $$block math$$LaTeX math
```mermaid fenceDiagrams
- [ ] taskGFM 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.