Obsidian vaults.

An Obsidian vault is a folder of markdown files, so Paperkites opens one as it is. Point Paperkites at the folder with :vault, such as :vault ~/Documents/Obsidian, and your links, embeds, callouts and queries work as written. Nothing is converted or moved.

Opening a vault

Switching vaults copies and moves nothing (see Your files). As it reads the folder, Paperkites gives each note that has no id: line one in its front matter, keeping the file's modified time. Everything else in a note stays byte for byte.

Paperkites skips hidden folders. It doesn't read .obsidian/, where Obsidian keeps its settings, plugins and themes, and it doesn't show it among your folders. Since Obsidian's settings aren't read, files you drop into a note go to attachments/, wherever Obsidian puts them (see Images and files).

Links

A link finds its note the way Obsidian finds it, trying each of these in turn:

1. By path: the path in the vault ([[Folder/Note]], [[Note.md]]), the end of one ([[Sub/Note]] finds Folder/Sub/Note.md), or the file name ([[Note]]). When two files match, the shorter path wins.
2. By title: a note's # heading.
3. By alias: a name listed under aliases: (or alias:) in its front matter.

Case doesn't matter. Backlinks, link counts and the graph all count links found this way.

Embeds

![[…]] embeds a note or a file. While the caret is elsewhere, it's drawn in place.

A file named on its own, such as photo.png, is found anywhere in the vault, as Obsidian finds it. Embedded notes nest two deep; past that, or for a note that embeds itself, the embed is a link. An embed whose note isn't there stays as written.

An image alone on its line is drawn at its size. Inside a sentence, it's the height of the text, so an embedded SVG can be an icon.

Callouts

A quote that starts with [!type] is a callout, drawn as a tinted panel with the type's icon and its title.

> [!tip] Low tide
> The causeway is open two hours either side.

> [!warning]- Spoilers
> Hidden until you open it.

A + or - after the ] makes it foldable, starting open or closed, with a button at the end of its title. Folding is only how you're looking at it: nothing is written to the file. With no title, the type is the title.

Types are case-insensitive. A type Obsidian doesn't know looks like a note.

Highlights, comments and block ids

While you write in a block, its comments and block ids show, dimmed. A tag, link or todo inside a comment doesn't count as one.

A line that's only a block id, under a list, quote or table, gives that block its id, and is hidden too.

Footnotes

The tide tables are from the harbour office.[^1]
Or write one inline.^[Like this.]

[^1]: Printed every October.

References become small numbers, counted in the order they first appear in the note. Hover a number to read its footnote.

Task statuses

Besides the seven todo states, a box can hold any other single character, such as [?] or [*]. Paperkites reads it as a todo that's checked, as Obsidian does. Ticking it sets it back to open. Task markers beyond [ ] and [x] come with Pro; without it, those lines are plain text.

HTML

HTML in a note is drawn safely. Paperkites keeps the tags notes use for text and structure, such as <kbd>, <u>, <mark>, <sup>, <br>, tables, lists and <details>, which still opens and closes.

• Dropped: scripts, styles, forms and anything that loads, with everything inside them. No style, class or event handler survives.
• Links keep only http, https and mailto addresses.
• Images come from your vault only, never from the web.
• An <iframe> is never loaded. It becomes a card with a button that opens its page in your browser.
• A tag Paperkites doesn't know is unwrapped to its text.

Queries

Three kinds of query block show what they find while the caret is elsewhere, and update as your notes change. They read notes only: fragments, area, project and todo files, and locked notes are left out.

A block Paperkites can't read shows one line saying why, above its source. It never shows results for a query it only half understood.

Search: ```query

Obsidian's embedded search. The block lists the notes it finds, by file name, with how often each matches.

```query
tag:#garden "raised bed" -path:archive
```

• Every word, or "quoted phrase", must match. OR offers either, - leaves out what follows, and ( ) groups.
• file:, path:, content:, tag:, and [prop] or [prop:value] for front matter.
• line:( ), block:( ), section:( ): all of it on one line, in one paragraph, or under one heading.
• task:, task-todo:, task-done:: in a todo's text.
• match-case: and ignore-case:.

Regular expressions aren't supported: /\d{4}/ is searched for as the text between the slashes.

Dataview: ```dataview

The part of Dataview's query language most notes use:

```dataview
TABLE status, due FROM #project and "Work"
WHERE status != "done"
SORT due ASC
LIMIT 10
```

• Queries: LIST and TABLE (with AS "Name" for a column), each with or without WITHOUT ID, and TASK.
• FROM: #tag, "folder", [[Note]] (the notes linking to it) and outgoing([[Note]]), joined with and or or, - to leave out, ( ) to group.
• WHERE, SORT (ASC or DESC) and LIMIT.
• In a TASK query, WHERE reads each todo: completed, checked, status, text, line, due (its @date), then its note's fields.

GROUP BY, FLATTEN and CALENDAR aren't supported, and the block says so.

DataviewJS is never run. A ```dataviewjs block is JavaScript, and stays code, labelled Dataview JS · not run in Paperkites.

Bases: ```base and .base files

Obsidian Bases, as a ```base block or an embedded .base file.

```base
filters:
  and:
    - file.hasTag("book")
    - status != "done"
views:
  - type: table
    name: Reading
    order: [file.name, author, status]
    sort:
      - property: author
        direction: ASC
    limit: 20
```

• Filters at the top and in each view: a statement, or and:, or: and not: lists of them, nested.
• Views of type: table (columns from order:), cards and list, each with name, limit and sort. properties names the columns.
• Left out, and said so under the results: formulas (their columns are empty), summaries and groupBy. A view of another type is drawn as a list.

Expressions

Dataview's WHERE and a base's filters share one set of expressions:

• Fields: file.name, status, note.status and the like.
• Values: "text", 3, true, [[Note]], date(today), dur(1 week).
• Operators: = or ==, !=, <, >, <=, >=, + and - on numbers and dates, and or &&, or or ||, and !.
• Functions: contains, icontains, econtains, startswith, endswith, lower, upper, length, date, dur, today, now, number, string.
• Methods: hasTag, inFolder, hasLink, hasProperty, contains, containsAll, containsAny, startsWith, endsWith, lower, upper, isEmpty, toString.

Anything else is refused when the block is read.

Front matter tags

Tags in front matter count like tags written in the text. Paperkites reads them as Obsidian does: tags: or tag:, as a list or as names split by commas or spaces, each with or without its #.

---
tags: [garden, "#garden/soil"]
aliases: [Allotment]
---

Renaming a tag everywhere (⌃r, see Finding things) renames it in front matter too.