Install, and save the first thing.

The whole point of Shelf is to disappear into the background. The first time you use it should feel ordinary — a keyboard shortcut, a small confirmation, the page is saved. The rest of the manual is for the moments after.

Install

Shelf is preparing its Chrome Web Store submission. Until the listing is live, the rest of this guide assumes you have a working install — either from the upcoming Web Store page or from a dev build. The install page has a one-line email waitlist so we can write you the day it ships.

Once installed (in any Chromium-based browser — Chrome, Edge, Brave, Arc, Vivaldi — running version 114 or later), pin Shelf to the toolbar so the unread counter is easy to spot. Click the puzzle piece icon next to the address bar, find Shelf in the list, click the pin.

You will be asked to allow the following permissions:

• storage — to keep your library in chrome.storage.local on this device.
• activeTab + scripting — to read the title and metadata of the page you save.
• contextMenus — to add a Save to Shelf right-click option.
• alarms + notifications — only used if you turn on the Daily Pick reminder.

Shelf does not run a content script in the background. Capture happens on demand: when you press the shortcut or click Save, the service worker uses chrome.scripting.executeScript to read the page’s title and metadata once, then unloads. There is no always-on presence on <all_urls>, no idle listener on every tab. The full permissions list lives in the privacy policy.

Save the first thing

Open any article you want to come back to. Press Alt + S — or right-click the page and choose Save page to library. The item lands in your library and is reachable from the Shelf popup.

What gets captured:

• Title — document.title as-is.
• URL — the current page URL.
• Excerpt — og:description when it’s longer than 20 characters, otherwise the description meta tag, otherwise nothing.
• Thumbnail URL — og:image (or twitter:image as fallback) when present.
• Hostname — the page’s full host as the browser sees it (e.g. www.nytimes.com, are.na). Dedup logic normalises this internally (lowercases, strips www.) but the saved item keeps the original.
• Reading time — only computed when an <article>, <main>, or [role="main"] element with at least 50 words is found, then word count at 220 wpm.
• Highlight — if you selected text before saving, the selection is captured and shown alongside the item; it is included in every export under a Highlight block.

No request leaves your browser at this point. The item sits in chrome.storage.local, scoped to the Shelf extension, on this device only.

Streak, Daily Pick, and the unread badge

Shelf tracks two reading habits and surfaces a third visual cue:

• Reading streak — every day you mark at least one item as read counts. Miss a day and you’ll see an at-risk state; miss two and Shelf burns one freeze (you get one freeze per ISO week, automatically). Miss three, or two in a week where you’ve already used the freeze, and the streak resets to zero. The longest streak you’ve ever reached stays as a personal record.
• Daily Pick — once a day at 9:00 local time, Shelf surfaces one unread item as a notification. Click it to open the popup.
• Unread badge — the toolbar icon shows an oxblood badge with the count of unread items in your library (99+ past a hundred). It disappears when your inbox is empty.

YouTube transcripts

For YouTube videos, Shelf can attach the captions to the saved item — and every export (Markdown, Obsidian, Logseq, Notion) will include the transcript with clickable timestamps that jump to the exact second.

Because YouTube increasingly blocks direct caption downloads, Shelf reads the transcript from the page’s own Show transcript panel:

1. Open the YouTube tab for the video.
2. Click the … menu under the video, choose Show transcript — the side panel opens.
3. Open the Shelf popup and click transcript on the saved item.

Shelf reads the panel directly. The transcript is stored on the item and emitted in coalesced ~30-second chunks; each chunk links back to the video at the right offset via ?t=Ns.

Find it again

Saves land in your library and appear under All until you assign them to a collection. Click the Shelf icon in the toolbar. The popup opens with your most recent saves at the top. The chip row across the top is the collection picker — an All pill plus one chip per top-level collection you’ve created. Tap a chip and the list narrows to items in that collection; tap deeper to drill into sub-collections, and use the breadcrumb arrow to step back up.

The popup is the quickest way to triage. The longer interface is the full Options page: right-click the toolbar icon and choose Options, or open chrome://extensions and click Details → Extension options on Shelf. That page shows the entire library, the destinations panel, collections management, the import tool, and (when Pro is active) Smart Rules and Library Tools.

Send it somewhere

The default behavior is to keep the save local. To send it onward — to your Notion workspace, to your Obsidian vault, to your Logseq graph, or to a plain Markdown file — you need to configure at least one destination.

Open the Options page, scroll to Destinations, and pick the one you want. Each export target has its own short page in these docs:

• Markdown — the default, simplest case.
• Notion — paste an integration token.
• Obsidian — URL handler, no API.
• Logseq — URL handler, no API.

That’s it. Everything else in the manual is for after — when you want to organize, route, automate, or rescue your library.

Migrating from Pocket?

If you have a Pocket export sitting around — ril_export.html or pocket.csv from the zipped email — drop it into the Options page’s Pocket import section. See the import guide for details.