Overview

Caspira manages a directory of Markdown files — your vault — and adds one thing: awareness of how notes relate to each other. It does this by resolving [[wiki-links]] at read time, without modifying your files.

Core concepts

The vault

A vault is any directory containing .md files. Run caspira init in the root to create a .caspira/ config directory. The vault can contain subdirectories at any depth; links resolve across all of them.

Wiki-links

Write [[note-name]] to link to another note. Caspira finds the file by stem — [[meeting-notes]] resolves to any meeting-notes.md in the vault, regardless of which subfolder it lives in. If two files share a stem, Caspira warns you and uses the closer one.

You can also use display text: [[meeting-notes|our last sync]] renders the link as "our last sync" in tools that support it.

The graph

Run caspira graph to print an ASCII adjacency list of every note and the notes it links to. Pipe to fzf to jump to a note by connection:

$ caspira graph | fzf | awk '{print $1}' | xargs $EDITOR

Templates

Place .md files in .caspira/templates/. Variables use {date}, {title}, and {author} syntax. Run:

$ caspira new --template meeting "Q1 planning"

This creates meetings/q1-planning.md (or wherever new.default_dir points in your config) with the template filled in.

Quick start

# 1. Install
cargo install caspira

# 2. Create a vault
mkdir notes && cd notes
caspira init

# 3. Write your first note
echo "# Hello\n\nSee also [[second-note]]." > first-note.md
echo "# Second\n\nLinked from [[first-note]]." > second-note.md

# 4. Check links
caspira check
# ✓  2 notes, 2 links, 0 broken

# 5. View graph
caspira graph
# first-note  → second-note
# second-note → first-note

Next: detailed installation instructions →