Skip to content
fastpad
Sign in
Docs

Markdown and export

One canonical serialization, with block anchors, used by the export, the API, the agent tools and the disk mirror.

The format

CommonMark, with YAML frontmatter for note metadata and a {#blockId} anchor after each block.

markdown
---
title: Retrieval design
types: [Project]
status: active
---

# Retrieval design {#01JB2K7Q9XN4M8YV3TD0FZ5ERW}

Four arms, fused by weighted RRF. {#01JB2K7Q9XN4M8YV3TD0FZ5ESX}

- lexical {#01JB2K7Q9XN4M8YV3TD0FZ5ETY}
- dense {#01JB2K7Q9XN4M8YV3TD0FZ5EUZ}

The anchor is the point. It is what makes a Markdown file a faithful representation of the document rather than a printout of it: the file says which block each paragraph is, so edits made on disk map back exactly.

The disk mirror

bash
fp pull ./notes            # write the mirror
$EDITOR ./notes/…
fp push ./notes --dry-run  # see what would change, offline
fp push ./notes            # send it back

A push is a diff against known identifiers, never a guess: an anchor whose text changed is an edit to that block; an anchor that vanished is a deletion; a paragraph with no anchor is something new.

File names are built from each note’s title after any credential in it is redacted and any URL neutralized, whoever pulls, so a key pasted into a title never becomes the name of a file on disk. The note’s identifier is part of the name, so two notes with the same title are two files.

Published notes

Publishing a note makes it readable at fastpad.ai/n/{id} with no account. The same URL serves HTML to a browser and Markdown to anything that asks for it.

bash
curl -H 'Accept: text/markdown' https://www.fastpad.ai/n/01JB2K…

Only a signed-in person can publish — no agent credential can, because an agent that could publish could exfiltrate a workspace by making it public and reading it back from outside. An unpublished note, a deleted note and a note that never existed are indistinguishable to an anonymous caller.

What round-trips

  • Headings, paragraphs, lists, tasks, quotes, callouts, code fences, dividers.
  • Tables, including cells containing an escaped pipe.
  • Links, mentions and the edges behind them.
  • Note properties, as frontmatter.
  • Block identifiers, on everything.

Attachments are referenced by URL rather than inlined. An export is a directory of text you can read with anything, which is the test this format exists to pass.

Read as Markdown