Open your Obsidian vault

An Obsidian vault is a folder of Markdown files, so Niv opens it as it is. There is nothing to import or export.

Open it

On the first open, choose Select a folder and pick your vault. Later, use File › Open Space….

Your folders stay as they are, and your links keep working.

What carries over

• Notes and folders. Every .md and .markdown file is a note, in the folder it's in.

• Links, including links with other text, links to a heading and links to a block.

• Embeds, which show another note, or one of its headings or blocks, inside this one.

• Callouts, with Obsidian's types, such as note, tip and warning.

• Properties. The YAML block at the top of a note shows as properties. See Writing in a note.

• Templates. If Obsidian has a templates folder set, Niv uses that folder until you choose another. See Templates.

• Daily notes. When you set up your daily note on Home, Niv prefills it from Obsidian's daily notes settings when they're there. See Daily and recurring notes.

The link and embed forms Niv reads:

[[Note]]
[[Note|other text]]
[[Note#Heading]]
[[Note#^block]]
![[Note]]

What Niv leaves alone

• Hidden folders, like .obsidian and .git, and node_modules. Niv doesn't list or sync them.

• Your Obsidian settings and plugins. Niv reads Obsidian's templates and daily notes settings, and doesn't write to them.

Niv keeps its own data for the folder in a hidden .niv folder inside it.

Links stay readable in Obsidian

When Niv writes a link, it writes the note's name, the way Obsidian does. When two notes share a name, it adds the folder:

[[Name]]
[[Folder/Name|Name]]

So the same vault keeps working in Obsidian, and any other tool can follow the links.

When you rename a note in Niv, Niv updates the links that point to it.

Using Obsidian and Niv on the same folder

You can. If the folder syncs with a Space, keep Niv open while you work elsewhere, so it can follow your changes as they happen. If the sidebar doesn't show a change made in another app, right-click an empty spot in the sidebar and choose Refresh.

See When sync asks you something for what Niv does when it can't tell what happened to a file.

Syncing a vault for the first time

If you connect a vault that already has notes to a Space, Niv compares the files with the Space and shows you the plan on Home before it creates anything. See Spaces.