Skip to content
LydieDevelopers
Menu

Documents and Markdown

How pages, bodies, properties, links and the trash work, and how to edit a body safely while people are typing in it.

View as Markdown

Everything in a workspace is a document: notes, pages, database rows. Documents form a tree.

The document

Field What it holds
id A ULID. You may choose it when you create the document, or let Lydie make one.
parentId The parent document, or null at the top level.
title 1 to 255 characters.
properties Typed frontmatter: strings, numbers, booleans, null or lists of strings.
sortKey Its place among its siblings. Use afterId or beforeId instead of setting it.
createdBy, updatedBy Who made the change: a user id, or agent:<app>:<id>:<user id> for an agent.
deletedAt Set while the document is in the trash.

The body is not part of the document. Get a document returns both, and includeBody=false leaves the body out.

A new top-level page goes to your private section unless you pass teamspaceId. Subpages always live in their parent’s space.

Bodies are Markdown

A body is Lydie Markdown: CommonMark with GitHub’s tables, task lists, strikethrough, autolinks and footnotes, plus Obsidian’s syntax.

Syntax Meaning
[[Note]], [[Note|alias]] A link to another document by title
[[Note#Heading]], [[Note#^block-id]] A link to a heading or a block
![[image.png]], ![[Note]] An embedded file or document
text ^block-id A block id that links can point at
> [!note] Title A callout
==text==, %%comment%%, #tag, $x$ Highlight, comment, tag, math

Frontmatter is not part of the body. Read and write it as properties.

Edit a body

Update a document body takes one of two inputs:

  • markdown replaces the whole body.
  • edits is a list of exact replacements, { "oldStr": "…", "newStr": "…" }, matched against the Markdown you read. Set replaceAll: true to change every match.

Prefer edits. They touch only what you change, so they do not undo what someone typed after you read the page. An edit that does not match exactly once is skipped and listed in warnings with the code no_match or ambiguous_match. The rest still apply.

Each read returns a version. Send it back as expectedVersion and the write fails with 409 conflict if the body changed since you read it. Read again and retry.

Writes merge into the live document. Someone with the page open sees your change appear.

Properties

Set document properties merges set into the existing properties and removes the keys in unset:

JSON
{ "set": { "status": "done", "tags": ["docs"] }, "unset": ["due"] }

Lydie indexes every link in every body. Use these to follow them:

Search documents searches titles and bodies. Every word must match, as a prefix. Snippets wrap matches in <mark></mark>.

Delete, restore, purge

Deleting moves a document and its subpages to the trash, and restoring brings them back. Purging deletes a trashed document for good, along with its body. Links to it become unresolved. Purging cannot be undone.