Visual Formatting

All content written to Obsidian should follow these rules. Visuals > prose. Always.

Format Selection — What to Use When

Content type	Format	Why
Process, flow, workflow	`mermaid` diagram	Shows sequence and branching visually
Comparing options, structured data	Table	Scannable rows > bullet lists
Key insight that must stand out	Callout (color = meaning)	Color-coded boxes pop visually
Long reference, occasional access	Foldable callout `[!info]-`	Progressive disclosure — collapsed by default
Critical term or value	`==highlight==`	Draws eye to the key thing
Important phrase in a paragraph	`bold`	Layer 2 emphasis
Actionable items	`- [ ]` checkboxes	NEVER inside callouts (rendering bug)
Reusing content across notes	`![[Note#Section]]` embed	See related content in place — no context switching
Rejected option or old approach	`~~strikethrough~~`	Visual “considered but not chosen” signal
Internal meta-notes	`%%comment%%`	Hidden in reading view — keeps notes visually clean
Connecting notes	`[[wikilinks]]`	Group in `## Related` section
Architecture decision	ADR format	TL;DR → Problem → Options table → Decision
Everything else	Short paragraphs (1-2 sentences)	`---` between major sections

Note Structure

Every note should follow this skeleton:

YAML frontmatter — type, status, tags
> [!abstract] TL;DR — one-sentence summary at top (Layer 4)
Emoji headings — instant visual categorization
Visual content — diagrams, tables, callouts
## Related — wikilinks to connected notes

Frontmatter Template

---
type: bug | feature | reference | daily | decision | cheatsheet
status: active | resolved | archived | in-progress
tags: []
created: YYYY-MM-DD
related: []
---

Headings — Emoji Prefixes

H1 (#): Document title only (one per file)
H2 (##): Major sections — Status, Today’s Work, Meetings, Notes, Root Cause, Fix/Options, Key Files, Related
H3 (###): Subsections — Completed, In Progress, Blocked

Callout Types (Color = Semantic Meaning)

Callout	Color	Use for
`[!abstract]`	Teal	TL;DR summary — put at top of every note
`[!tip]`	Cyan	Best practices, recommendations
`[!warning]`	Orange	Gotchas, risks, things that can go wrong
`[!danger]`	Red	Blockers, critical issues, breaking changes
`[!question]`	Yellow	Open decisions needing input
`[!info]`	Blue	Context, background, explanations
`[!success]`	Green	Completed items, confirmations
`[!bug]`	Red	Bug reports
`[!example]`	Purple	Code examples, scenarios
`[!failure]`	Red	What went wrong, post-mortems
`[!quote]`	Gray	Citations, references
`[!todo]`	Blue	Actionable items

Foldable: [!info]- collapsed, [!info]+ expanded. Use for long code or reference that clutters the note.

Mermaid Diagrams

Use instead of writing paragraphs about processes:

flowchart LR / flowchart TB — workflows, data flows, decision trees
sequenceDiagram — request/response, multi-actor interactions
graph TD — architecture, dependency relationships
gantt — timelines, project schedules
pie — proportions, status breakdowns

Obsidian-specific gotchas:

Gotcha	Wrong	Right
Line breaks in node labels	`["Text\nMore"]` — renders literal `\n`	`["Text<br/>More"]` — actual line break
Dark theme colors	`fill:#22c55e,color:#fff` — bright green, white text washes out	`fill:#4ade80,color:#052e16` — softer green, dark text for contrast
Node text readability	High-saturation fills with white text	Use lighter fills with dark text (e.g., `color:#052e16` on green, `color:#172554` on blue)

Dark-theme-safe color palette:

Meaning	Fill	Stroke	Text
Done / success	`#4ade80`	`#22c55e`	`#052e16`
In progress	`#60a5fa`	`#3b82f6`	`#172554`
Warning / open	`#fbbf24`	`#f59e0b`	`#451a03`
Blocked / error	`#f87171`	`#ef4444`	`#450a0a`
Neutral	`#94a3b8`	`#64748b`	`#0f172a`
Accent / purple	`#c084fc`	`#a855f7`	`#3b0764`

Progressive Summarization (Layers)

Each time you revisit a note, compress it one layer:

Layer	Action	Obsidian syntax
1	Capture raw	Daily note / paste
2	Bold key sentences	`bold`
3	Highlight critical terms	`==highlight==`
4	Executive summary	`> [!abstract]` at top
5	Create deliverable	Separate linked note

Embeds (Transclusion)

Pull content from other notes inline — no duplication, always up-to-date:

![[Note]] — embed entire note
![[Note#Section]] — embed a specific heading section
![[Note#^block-id]] — embed a single block/paragraph

Use embeds to pull key diagrams, decisions, or root causes into daily notes. Ideal for referencing a mermaid diagram or ADR summary without copy-pasting.

Standard Elements

Tasks: - [ ] unchecked, - [x] completed — OUTSIDE callouts
Links: Wikilinks [[Note]] for internal, [text](url) for external
Embeds: ![[Note#Section]] to transclude content inline (see above)
Strikethrough: ~~text~~ for rejected options, old approaches, superseded decisions
Comments: %%hidden text%% invisible in reading view — use for internal meta-notes, TODOs for yourself
Code blocks: Always specify language, use foldable [!example]- for long blocks
Tags: #meeting, #technical, #bug, #architecture
Whitespace: --- between major sections for visual breathing room

ADR Format (Architecture Decisions / Bug Reports)

> [!abstract] TL;DR
> One sentence: what was decided/found and why

## Status
## Problem / Goal
## Root Cause (if bug)
## Options Considered (table)
## Decision
## Key Files
## Related