---
name: obsidian-markdown
component: obsidian
description: >-
  Obsidian-flavored markdown conventions for vault notes. Covers wikilinks,
  tags, frontmatter, callouts, embeds, and when to use each linking style.
type: utility
trigger-patterns:
  - vault note creation
  - markdown formatting
  - linking
category: conventions
tags:
  - obsidian
  - markdown
  - wikilinks
  - frontmatter
---

# Obsidian Markdown

Conventions for writing Obsidian-flavored markdown in vault notes.

## Wikilinks

Internal links between vault notes use double-bracket syntax:

```markdown
[[Note Name]]
[[Note Name|Display Text]]
[[Folder/Subfolder/Note Name]]
[[Note Name#Heading]]
[[Note Name#Heading|Display Text]]
```

- Wikilinks are vault-relative and resolve by note title, not file path
- If multiple notes share a name, use the full path: `[[Folder/Note Name]]`
- Heading links use `#` to target a specific section

## Standard Markdown Links

Use standard markdown links for external URLs only:

```markdown
[Display text](https://example.com)
```

**Rule:** Wikilinks for vault-internal references. Standard links for external URLs.

## Tags

### Inline Tags

Place tags anywhere in note body text:

```markdown
This note covers #authentication and #security patterns.
```

### Frontmatter Tags

Declare tags in YAML frontmatter for structured filtering:

```yaml
---
tags:
  - gmd
  - phase-04
  - decision
---
```

Both inline and frontmatter tags appear in Obsidian's tag pane and are searchable.

## Frontmatter

YAML metadata between `---` delimiters at the top of every note:

```yaml
---
title: Phase 04 Context
tags:
  - gmd
  - phase-04
created: 2026-04-10
synced_from: .planning/phases/04-design-planning-workflows/04-CONTEXT.md
synced_at: 2026-04-10T06:30:00Z
---
```

Rules:
- Frontmatter must be the very first content in the file (no blank lines before `---`)
- Values follow YAML syntax (strings, lists, dates)
- Obsidian recognizes `tags`, `aliases`, `cssclasses` as special fields
- Custom fields (like `synced_from`) are valid and queryable via Dataview

## Callouts

Styled admonitions using blockquote syntax:

```markdown
> [!note]
> Important information about this topic.

> [!warning]
> This approach has known limitations.

> [!tip]
> Use this pattern for better results.

> [!question]
> Open question that needs resolution.

> [!example]
> Concrete example demonstrating the concept.
```

Available types: `note`, `abstract`, `info`, `tip`, `success`, `question`, `warning`, `failure`, `danger`, `bug`, `example`, `quote`.

### Foldable Callouts

```markdown
> [!note]- Click to expand
> This content is collapsed by default.

> [!note]+ Expanded by default
> This content shows initially but can be collapsed.
```

## Embeds (Transclusion)

Embed the full content of another note inline:

```markdown
![[Note Name]]
![[Note Name#Specific Heading]]
```

Embeds render the referenced content directly in the current note. Useful for:
- Reusing shared context across multiple notes
- Embedding phase summaries into project overview notes
- Including decision logs in relevant phase notes

## When to Use This Skill

- Creating vault notes from synced `.planning/` artifacts
- Writing MOC (Map of Content) index notes
- Formatting research notes, decision logs, or summaries for vault consumption
- Any markdown destined for an Obsidian vault
