9.3 KiB
9.3 KiB
Obsidian Markdown Syntax Reference
Complete reference for Obsidian-specific markdown syntax, including wiki-links, tags, frontmatter, and extended markdown features.
Wiki-Links
Obsidian's primary linking syntax for internal note connections.
Basic Wiki-Links
[[Note Name]]
Links to a note named "Note Name.md" anywhere in the vault.
Characteristics:
- Case-sensitive
- Extension not required
- Searches entire vault by name
- Creates link even if note doesn't exist (shown in different color in Obsidian)
Wiki-Links with Aliases
[[Actual Note Name|Display Text]]
Display custom text while linking to the actual note.
Examples:
See the [[Project Requirements|requirements]] for details.
Read [[Albert Einstein|Einstein's]] biography.
Check [[2024-01-15|yesterday's notes]].
Wiki-Links to Headings
[[Note Name#Heading]]
[[Note Name#Heading|Custom Text]]
Link to specific section within a note.
Examples:
Review [[Meeting Notes#Action Items]]
See [[API Documentation#Authentication|auth docs]]
Heading Link Rules:
- Heading text must match exactly (case-sensitive)
- Use heading text without the
#prefix - Spaces in headings are preserved
- Works with any heading level
Wiki-Links to Blocks
[[Note Name#^block-id]]
Link to specific block within a note.
Block ID Syntax:
This is a paragraph with an ID. ^block-123
- List item with ID ^item-456
Example:
Reference: [[Research#^key-finding]]
Wiki-Links with Paths
[[folder/subfolder/Note Name]]
Specify path when multiple notes share the same name.
Examples:
[[Work/Projects/Project Plan]]
[[Personal/Projects/Project Plan]]
Embedding Notes
![[Note Name]]
Embed the entire content of another note.
Examples:
![[Meeting Template]]
![[Quote Collection#Favorite Quotes]]
Embedding Images
![[image.png]]
![[image.png|200]]
![[image.png|200x100]]
![[folder/image.png|Custom Alt Text|300]]
Size Specifications:
|width- Set width, maintain aspect ratio|widthxheight- Set both dimensions- Add alt text before dimensions
Tags
Flexible categorization and filtering system.
Basic Tags
#tag
#tag-name
#tag_name
Rules:
- Start with
# - No spaces (use
-or_) - Alphanumeric characters
- Case-sensitive
- Can appear anywhere in note
Examples:
#project #work #important
This note is about #machine-learning concepts.
Status: #in-progress
Nested Tags
#parent/child
#parent/child/grandchild
Creates tag hierarchy.
Examples:
#project/work/client-a
#project/personal/side-hustle
#status/active
#status/archived
In Obsidian UI:
- Tags displayed as hierarchy
- Filter by parent shows all children
- Organize tags logically
Inline Tags
Tags can appear anywhere in text:
Discussed #meeting-notes with team about #q1-planning.
#review-required
Multi-Word Tags
#multi-word-tag
#multi_word_tag
Use hyphens or underscores, not spaces.
Frontmatter (YAML)
Structured metadata at the start of notes.
Basic Frontmatter
---
title: Note Title
author: Author Name
date: 2024-01-15
---
# Note Content
Rules:
- Must be at very start of file
- Enclosed in
---delimiters - YAML syntax
- Key-value pairs
Common Fields
---
title: Document Title
date: 2024-01-15
tags:
- tag1
- tag2
aliases:
- Alternative Name
- Shorthand
author: John Doe
status: draft
---
Array Values
---
tags:
- project
- important
categories: [work, planning]
---
Both syntaxes work (YAML list or inline array).
Nested Objects
---
metadata:
created: 2024-01-15
modified: 2024-01-20
version: 1.2
project:
name: Project Alpha
status: active
team:
- Alice
- Bob
---
Obsidian-Specific Fields
---
aliases:
- Alt Name 1
- Alt Name 2
tags:
- vault-tag
cssclasses:
- custom-theme
- wide-page
---
Special Fields:
aliases- Alternative names for wiki-linkstags- Tags (alternative to inline#tags)cssclasses- Custom CSS classes for styling
Task Lists (Checkboxes)
Extended checkbox syntax beyond standard markdown.
Standard Checkboxes
- [ ] Unchecked task
- [x] Completed task
- [X] Completed task (capital X works too)
Extended Checkbox Types
- [ ] To do
- [x] Done
- [>] Forwarded/Rescheduled
- [<] Scheduled
- [-] Cancelled
- [?] Question
- [!] Important
- [*] Star
- ["] Quote
- [l] Location
- [b] Bookmark
- [i] Information
- [S] Amount/Money
- [I] Idea
- [p] Pro
- [c] Con
- [f] Fire
- [k] Key
- [w] Win
- [u] Up
- [d] Down
Note: Extended types require Obsidian or plugins. Rendered specially in Obsidian UI.
Nested Tasks
- [ ] Parent task
- [ ] Subtask 1
- [x] Subtask 2
- [ ] Subtask 3
- [ ] Sub-subtask
Callouts (Admonitions)
Styled information blocks.
Basic Callout
> [!note]
> This is a note callout.
> [!info]
> This is an info callout.
Callout Types
> [!note]
> Note content
> [!abstract] / [!summary] / [!tldr]
> Summary content
> [!info] / [!todo]
> Information
> [!tip] / [!hint] / [!important]
> Helpful tip
> [!success] / [!check] / [!done]
> Success message
> [!question] / [!help] / [!faq]
> Question content
> [!warning] / [!caution] / [!attention]
> Warning message
> [!failure] / [!fail] / [!missing]
> Error message
> [!danger] / [!error]
> Danger warning
> [!bug]
> Bug report
> [!example]
> Example content
> [!quote] / [!cite]
> Quoted text
Callout with Title
> [!note] Custom Title
> Content goes here.
> [!warning] Important Warning
> This is critical information.
Foldable Callouts
> [!note]- Collapsed by default
> Content hidden initially.
> [!note]+ Expanded by default
> Content visible initially.
Nested Callouts
> [!info] Outer callout
> Information here.
>
> > [!warning] Nested callout
> > Nested warning.
Code Blocks
Basic Code Blocks
```
Plain code block
```
```javascript
console.log("JavaScript code");
```
```python
print("Python code")
```
With Line Numbers
Obsidian doesn't natively support line numbers, but some plugins do.
Tables
Basic Tables
| Column 1 | Column 2 | Column 3 |
| -------- | -------- | -------- |
| Row 1 | Data | Data |
| Row 2 | Data | Data |
Alignment
| Left | Center | Right |
| :--- | :----: | ----: |
| L1 | C1 | R1 |
| L2 | C2 | R2 |
Tables with Links
| Project | Status | Notes |
| ------- | ------ | ----- |
| [[Project A]] | #active | See [[Notes]] |
| [[Project B]] | #done | Complete |
Comments
%%
This is a comment.
Multi-line comments are supported.
%%
Regular text. %% Inline comment %%
Rules:
- Enclosed in
%% - Not rendered in reading view
- Can be inline or multi-line
Footnotes
Here's a sentence with a footnote[^1].
[^1]: This is the footnote content.
Another reference[^note].
[^note]: Named footnotes work too.
Obsidian URI
Link to open notes in Obsidian app:
obsidian://open?vault=VaultName&file=NoteName
[Open Note](obsidian://open?vault=MyVault&file=folder/note)
Combining Syntax
Complex Examples
---
title: Project Plan
tags:
- project
- planning
status: active
---
# [[Projects|Project]]: Mobile App Redesign
## Overview
This project focuses on #ui-ux improvements. See [[Design System]] for details.
## Tasks
- [ ] Review [[Requirements#Functional|functional requirements]]
- [x] Create [[Wireframes]]
- [>] Schedule meeting with #stakeholders
- [ ] Update [[Project Timeline]]
## References
![[Design Principles#Core Values]]
> [!tip] Best Practice
> Always link to [[Style Guide]] when implementing designs.
## Related
- [[Previous Projects#Mobile|Past mobile work]]
- [[Team Members|Team]]
#project/mobile #status/in-progress
Best Practices
- Use wiki-links liberally - Create connections between related notes
- Consistent tag hierarchy - Use nested tags for organization (
#project/work/client) - Frontmatter for metadata - Structure data that's queried frequently
- Aliases for flexibility - Add aliases for common alternative names
- Descriptive link text - Use aliases when natural reading flow matters
- Block links sparingly - For specific references within longer notes
- Comments for drafts - Use
%%for notes to self that shouldn't be published - Callouts for emphasis - Highlight important information visually
Compatibility Notes
- Standard markdown works everywhere
- Wiki-links are Obsidian-specific (convert to regular links for export)
- Extended checkboxes may need plugins outside Obsidian
- Callouts are Obsidian-specific (render as blockquotes elsewhere)
- Frontmatter is standard YAML (works in most markdown processors)
- Comments (
%%) are Obsidian-specific - Tags work in Obsidian; may be ignored elsewhere
See Also
- obsidian-cli Reference - Command-line vault operations
- Note Templates - Ready-to-use note structures