A migration guide

Pocket to Obsidian,
in Markdown.

Pocket's archive becomes one Markdown note per saved item, all in your Obsidian vault. Two paths: automated via Shelf (5 minutes) or manual via a Python script (15-20 minutes). No Obsidian plugin required.

Step 1 — Get your Pocket archive

Same as for any Pocket migration: getpocket.com/export → HTML format → download the .html file. It's the source of truth for the rest.

Step 2 — Pick a folder in your vault

In your Obsidian vault, create a dedicated folder. Suggestions:

Library/ — clean, future-proof, treats this as your reading record (not just "Pocket import")
Reading/ — works if you already think of your vault in BASB / PARA terms
00 — Inbox/ — if you sort everything later

Whatever you pick, commit. Renaming folders later means breaking internal links. The folder is the destination for everything you import (and everything you save going forward).

Step 3 — Path A: Automated via Shelf (5 minutes)

Shelf writes one .md file per saved item into your default Obsidian vault via the obsidian:// URL handler. No plugin install required — the handler is part of Obsidian itself since v0.13.

Install Shelf (Chrome Web Store, coming soon — waitlist).
Open Shelf Options → Destinations → tick "Obsidian".
Confirm your default vault name (Obsidian's chooser will pop up the first time a save lands).
Go to Library Tools → Import from Pocket → drop the .html file.
Wait. About 1,200 items/minute. Each becomes one .md note at the root of your vault (subfolder picker comes in v0.2).

Step 3 — Path B: Manual via Python script (15-20 min)

If you want full control over filenames, folder structure, or you don't want to install an extension, a small Python script does the job. Rough sketch:

Use BeautifulSoup to parse ril_export.html. Each <a> in the doc is one saved item.
Extract: href (URL), text (title), time_added (unix timestamp), tags (comma-separated string).
For each item, write a .md file named YYYY-MM-DD — slug-of-title.md into your vault folder.
The file body: frontmatter (see schema below) + a single line linking back to the source URL.

Total time including writing the script: 15-30 minutes for someone comfortable in Python. For 2,000 saves the script runs in ~20 seconds.

Recommended frontmatter schema

Obsidian indexes frontmatter as searchable properties. Use this schema and your library becomes Dataview-queryable from day one.

---
title: "Notes on Marginalia"
url: https://theatlantic.com/notes-on-marginalia
hostname: theatlantic.com
saved: 2024-03-08
kind: article
tags:
  - essay
  - reading
  - pkm
imported_from: pocket
---

[Read on theatlantic.com](https://theatlantic.com/notes-on-marginalia)

Why this exact set:

title as YAML string lets Obsidian show it as the note title without the H1 line wrapping
url as plain YAML — Dataview picks it up
hostname separates "where" from "what" for source-aware queries
saved in YYYY-MM-DD lets you query "all items from 2024-03"
kind categorises articles vs videos vs podcasts
tags as YAML list (not comma-separated) so Obsidian's tag pane picks them up
imported_from distinguishes Pocket migration items from items saved natively later

Use Dataview to query your migrated library

Once frontmatter is consistent, you can run queries like:

```dataview
TABLE WITHOUT ID
  file.link AS Article,
  hostname AS Source,
  saved AS "Saved at"
FROM "Library"
WHERE imported_from = "pocket"
SORT saved DESC
LIMIT 50
```

Or "every article tagged #essay, grouped by year":

```dataview
TABLE WITHOUT ID file.link, saved
FROM "Library"
WHERE contains(tags, "essay")
SORT saved DESC
```

What does not migrate

Same as the Notion migration page: Pocket's HTML export gives you URL, title, tags, time_added, and read state. It does not include annotations, highlights, the cached article text, or the AI-generated tags from Premium.

What you preserve is enough to rebuild the library structure. The article text comes from re-fetching (Obsidian + Web Clipper community plugin can re-clip them later if you want full text offline).

After migration: saving from the web going forward

One option: use the Obsidian Web Clipper official extension. Free, well-built, one-shot save → .md file in your chosen folder. No library layer; each save is just a file.

Other option: Shelf writes the same Markdown file and maintains a searchable library inside the extension (with tags, collections, AI auto-tag, YouTube transcripts). Press Alt+S → file appears in your vault → same save also visible inside the extension popup for retrieval.

The Markdown file is the source of truth either way. Use whichever tool fits the rest of your workflow.

Try the migration

Shelf migrates Pocket archives into Obsidian vaults at ~1,200 items per minute. Launches on the Chrome Web Store soon — leave your email and I'll write once when it's live.

One email · No marketing · Unsubscribe in any client

Pocket to Obsidian,in Markdown.