Markdown is the lingua franca.

Every other destination is built on the same Markdown payload that the Markdown export produces. If you understand this one, you understand Shelf’s data model.

Turn it on

Open the Options page, scroll to Destinations, and toggle Markdown on. There is no further configuration — Markdown export writes through Chrome’s normal download mechanism. The first time you send a save, Chrome may ask whether to allow downloads or to choose a folder.

If you’ve set a default downloads folder, that’s where Shelf writes by default. If you’ve told Chrome to Ask where to save each file, Shelf will respect that — but the prompt every time will quickly feel like friction. Pick a folder.

What gets written

Each saved item becomes a single .md file. The file looks like this:

---
title: "On Marginalia"
url: https://www.theatlantic.com/.../on-marginalia/
hostname: theatlantic.com
saved: 2026-05-11
kind: article
reading_time_min: 11
tags:
  - pkm
  - essay
  - long-form
---

# On Marginalia

[theatlantic.com](https://www.theatlantic.com/.../on-marginalia/) · 11 min read

> A short defence of pencil-marks in books — the argument that annotation is not a defacement of the text but a record of having been there.

## AI summary

- Annotation is a form of intimacy with a text, not its violation.
- Margins record the reader's response in the moment of reading.
- The history of marginalia is the history of how books were actually used.

## Highlight

> A book half-read is twice owned.

The --- block at the top is YAML frontmatter. These are the fields Shelf writes:

Key	Type	Notes
title	string	The raw document.title (escaped for YAML)
url	string	The page URL
hostname	string	The hostname of the URL
saved	string	YYYY-MM-DD (local date the item was saved)
kind	article / video / podcast / page	Inferred from URL pattern + DOM
reading_time_min	number	220 wpm; only present when an <article>/<main>/[role=main] element with ≥50 words was found
ai_backend	nano / groq	Only present when AI inference ran on this item
tags	YAML list	Your tags and AI tags merged into one list

That’s the entire frontmatter. The excerpt, ai_summary, Highlight, and YouTube transcript are emitted as body content, not frontmatter:

• The excerpt (if present) is rendered as a blockquote.
• The AI summary (if present) lives under an ## AI summary heading as a three-bullet list.
• Your text selection at save-time (if present) lives under ## Highlight as a blockquote.
• The transcript (YouTube videos only, fetched on demand) lives under a ## Transcript heading, chunked into ~30-second blocks; each chunk’s timestamp links back to the video at the right offset.

Collection membership is stored separately in chrome.storage.local and is not written into the Markdown frontmatter — your file system folders are the source of truth for “where this lives”, not a YAML field.

How files are named

Single-item exports are named slug-of-title.md. The slug is the title, lowercased, non-alphanumerics collapsed to single hyphens, truncated at 80 characters. Chrome decides the folder based on your Downloads preference.

The Library Tools → Export library ZIP (Pro) prefixes each filename with the save date for chronological sorting: YYYY-MM-DD-title-slug.md. That format is only used inside the ZIP — single-item exports stay plain.

What happens after

Once a .md file is on disk, Shelf forgets about it. Open the file in any editor. Move it. Rename it. Commit it to git. The library it belongs to is the one in your file system, not the one in chrome.storage.local.

To re-import, use Library Tools → Import library in the Options page with a ZIP previously produced by Export library. Re-importing a loose folder of Markdown files isn’t yet supported — the round-trip currently goes through the ZIP archive only.