OBSIDIAN MARKDOWN

Use valid Obsidian-flavored Markdown for canonical project notes. Prefer readable notes first, then Obsidian-native structure.

Core rules

Keep a small frontmatter block at the top of canonical notes.
Use [[wikilinks]] for vault-internal references and Markdown links only for external URLs.
Use readable headings and short sections; avoid turning notes into raw dumps.
Prefer Markdown tables only when the comparison is truly tabular.
Keep system files and generated tables deterministic; keep human notes readable.

Use frontmatter for stable metadata such as:

---
type: knowledge
status: active
created: 2026-04-24
updated: 2026-04-24
tags:
  - research
  - active
aliases:
  - Alternative Note Name
---

Prefer simple scalar or list properties. Do not over-model note metadata unless the workflow needs it.

Common forms:

[[Note Name]]
[[Folder/Note Name]]
[[Note Name|Display Text]]
[[Note Name#Heading]]
[[Note Name#^block-id]]

Use folder-qualified links when note names are ambiguous. Prefer links to canonical notes over duplicate notes.

Use embeds when the reader benefits from inline context, not just because the syntax exists.

![[Note Name]]
![[Note Name#Heading]]
![[image.png|300]]
![[document.pdf#page=3]]

Avoid large embed chains that make notes hard to scan.

Use callouts to highlight information that benefits from visual separation:

> [!note]
> Supporting detail.

> [!warning] Risk
> This assumption may break under domain shift.

Common types: note, info, tip, warning, question, success, failure, quote, example.

Use tables for:

Avoid tables for long prose or nested content.

Use tags sparingly and consistently.
Use aliases when a note has a common alternate name or paper title variant.
Do not rely on tags as the only navigation mechanism when wikilinks and index notes are clearer.