obsidian-zettelkasten

Obsidian Zettelkasten Formatter

Format project documentation, notes, and knowledge as an Obsidian vault using the Zettelkasten method with dense cross-referencing.

Before Starting

1. Read references/obsidian-syntax.md for Obsidian-specific Markdown syntax
2. Read references/zettelkasten-structure.md for note types, linking patterns, and vault organization

Workflow

Phase 1: Analyze Source Material

1. Identify the input: source code, README, docs, conversations, or raw notes
2. Extract distinct concepts — each concept becomes one atomic note
3. Identify relationships between concepts (depends-on, implements, extends, contrasts, related-to)
4. Identify hierarchical groupings for Maps of Content (MOC)

Phase 2: Design Vault Structure

Organize notes into a flat or shallow folder structure:

vault/
├── 00-MOC/                    # Maps of Content (index notes)
│   ├── MOC-Architecture.md
│   └── MOC-API.md
├── concepts/                  # Permanent notes (atomic ideas)
│   ├── dependency-injection.md
│   └── event-driven-architecture.md
├── references/                # Literature notes (source summaries)
│   ├── ref-clean-architecture-martin.md
│   └── ref-rust-book-ch10.md
├── guides/                    # How-to and tutorial notes
│   ├── guide-setup-project.md
│   └── guide-deployment.md
├── decisions/                 # ADRs and design decisions
│   ├── adr-001-database-choice.md
│   └── adr-002-auth-strategy.md
└── templates/                 # Note templates
    ├── tpl-concept.md
    ├── tpl-reference.md
    └── tpl-adr.md

Rules:

• Prefer flat structure over deep nesting — Obsidian search and links make folders optional
• Use prefixes (MOC-, ref-, guide-, adr-, tpl-) only when folders are not used
• Keep file names lowercase-kebab-case, descriptive, without dates in the name
• One idea per note — if a note covers two distinct topics, split it

Phase 3: Write Notes

For each note, follow this structure:

1. Properties (YAML Frontmatter)

Every note MUST start with YAML properties:

---
aliases:
  - DI
  - Inversion of Control
tags:
  - architecture
  - design-pattern
created: 2026-04-10
related:
  - "[[service-locator]]"
  - "[[factory-pattern]]"
status: permanent
---

Required properties:

• tags — at least one tag per note, use nested tags for hierarchy (#architecture/patterns)
• created — date in YYYY-MM-DD format

Recommended properties:

• aliases — alternative names for autocomplete and linking
• related — explicit links to related notes (quoted wikilinks)
• status — one of: fleeting, literature, permanent, moc

2. Title and Content

# Dependency Injection

Dependency injection is a technique where an object receives its dependencies
from external sources rather than creating them internally.

## Core Principle

The consumer declares *what* it needs; the injector decides *how* to provide it.
This inverts the control flow — hence the alias ==Inversion of Control==.

## Relationship to Other Patterns

- Contrasts with [[service-locator]] — DI pushes dependencies, service locator pulls them
- Often implemented via [[factory-pattern]] or a DI container
- Enables [[testability]] by allowing mock injection

## In Rust

Rust achieves DI through trait objects and generics rather than runtime reflection:

> [!example] Trait-based DI in Rust
> ```rust
> trait Repository: Send + Sync {
>     fn find(&self, id: u64) -> Option<Entity>;
> }
>
> struct Service<R: Repository> {
>     repo: R,
> }
> ```

> [!tip] When to use
> Prefer generic parameters over `dyn Trait` when the concrete type is known at compile time.

## See Also

- [[MOC-Architecture]] — parent map
- [[clean-architecture]] — broader architectural context

3. Linking Rules

Apply these rules to every note:

• Link on first mention: When a concept appears for the first time in a note, wrap it in [[wikilink]]. Do not link every occurrence — only the first
• Use display text for readability: [[dependency-injection|DI]] when the full name is verbose
• Link to headings: [[note#Heading]] when referencing a specific section
• Link to blocks: [[note#^block-id]] for precise paragraph references
• Backlinks are automatic: Obsidian tracks incoming links — no need to manually add "referenced by" sections
• Embed when context helps: Use ![[note]] or ![[note#Section]] to inline content from another note

Phase 4: Create Maps of Content

MOC notes are index pages that organize related concepts. Every vault needs at least one top-level MOC.

---
aliases:
  - Architecture Overview
tags:
  - moc
  - architecture
created: 2026-04-10
status: moc
---

# Architecture

> [!abstract] Overview
> This map organizes architectural concepts, patterns, and decisions
> used in the project.

## Patterns

- [[dependency-injection]] — decoupling components via external wiring
- [[event-driven-architecture]] — async communication between services
- [[cqrs]] — separating read and write models

## Decisions

- [[adr-001-database-choice]] — why we chose PostgreSQL
- [[adr-002-auth-strategy]] — JWT vs session-based auth

## Principles

- [[clean-architecture]] — layered boundaries
- [[solid-principles]] — SOLID in Rust context

## Related Maps

- [[MOC-API]] — API design and endpoints
- [[MOC-Testing]] — testing strategy and patterns

Rules:

• MOC notes contain primarily links and brief descriptions — no long-form content
• Each link has a short em-dash description (— why/what)
• Group links under semantic headings
• Link between MOCs to form a navigable graph

Phase 5: Review and Cross-Reference

1. Orphan check: Every note must have at least one incoming link (except top-level MOC)
2. Tag consistency: Use the same tag vocabulary across notes — check for typos and near-duplicates
3. Link density: Each permanent note should link to 2-5 other notes minimum
4. Alias coverage: Add aliases for acronyms, abbreviations, and alternative names
5. Callout usage: Use callouts for warnings, tips, examples — not as primary content

Note Types

Type	Purpose	Status	Template
Permanent	Atomic concept in your own words	permanent	tpl-concept.md
Literature	Summary of a source (book, article, doc)	literature	tpl-reference.md
MOC	Index linking related notes	moc	—
Fleeting	Quick capture, to be processed	fleeting	—
ADR	Architecture Decision Record	permanent	tpl-adr.md
Guide	Step-by-step how-to	permanent	tpl-guide.md

Callout Quick Reference

Use Obsidian callouts for structured asides:

Type	Use for
> [!note]	General supplementary information
> [!tip]	Best practices, recommendations
> [!warning]	Pitfalls, common mistakes
> [!example]	Code examples, usage demonstrations
> [!abstract]	Summaries, TL;DR at top of MOCs
> [!question]	Open questions, FAQ entries
> [!danger]	Critical issues, breaking changes
> [!quote]	Direct quotations from sources
> [!info]	Contextual background
> [!bug]	Known issues

Foldable callouts: > [!tip]- (collapsed) or > [!tip]+ (expanded by default).

Nested callouts: use additional > levels.

Quality Checklist

• Every note has YAML properties with at least tags and created
• Every note has exactly one # H1 title
• Atomic: each note covers one concept
• First mention of each concept is a [[wikilink]]
• No orphan notes (except top-level MOC)
• Each permanent note links to 2-5 other notes
• MOC exists for each major topic area
• Tags use consistent vocabulary with nested hierarchy
• Aliases added for acronyms and alternative names
• Callouts used appropriately (not as primary content)
• No raw URLs — all external links use [text](url) format
• Code blocks have language annotations

Anti-Patterns to Avoid

• Folder-first organization: Do not create deep folder hierarchies. Links and tags replace folders in Zettelkasten
• Hub notes with no links out: MOC notes must link to actual content, not just exist as placeholders
• Copy-pasting source material: Literature notes should be rewritten in your own words with links to permanent notes
• Overlapping notes: If two notes say the same thing, merge them and add an alias
• Inline tags only: Always add tags to YAML properties, not just inline #tag — properties enable structured search
• Linking everything: Not every word needs a link. Link concepts, not common words
• Date-based file names: Use descriptive names. Dates go in created property