DocShelf

by Oliver Im
5
4
3
2
1
Score: 51/100

Description

A home for Markdown and HTML notes scattered across projects, with link support for source lines

Reviews

No reviews yet.

Stats

0
stars
437
downloads
0
forks
57
days
9
days
9
days
52
total PRs
0
open PRs
1
closed PRs
51
merged PRs
1
total issues
0
open issues
1
closed issues
102
commits

Latest Version

9 days ago

Changelog

DocShelf for Obsidian 0.10.0: desktop beta

Pin whole projects alongside folders and documents. Right-click a project heading, or focus it and press Shift+F10, then choose Pin project. Its shortcut appears in Pinned above the project list. Selecting the shortcut opens and focuses the original project. Choose Unpin project from either location to remove it.

  • Projects containing only empty registered folders can be pinned. Temporarily absent projects regain their shortcut when they return under the same exact name. Renaming a project creates a different identity.
  • Project, folder, and document pins use one shared set of pin helpers, with independent identities and storage records. Pinning a project does not pin its folders or documents, and unpinning one kind leaves the other kinds intact.
  • Separate device-local storage records and shared cross-window coordination preserve existing pins, including when older app windows update document or folder pins. No shelf or source document changes are needed.
  • DocShelf Web also gains project pin actions and shortcuts, while keeping separate pins for each app and shelf.

Install or update

Use Obsidian's Community plugins settings to check for updates, or open the community listing.

For a fresh manual install, download docshelf-0.10.0.zip, extract it, and copy its docshelf folder into your vault's .obsidian/plugins/ folder, creating the parent folder if necessary. Enable DocShelf in Community plugins afterward.

For a manual update, save or review pending Markdown edits, then disable DocShelf before replacing files. Copy main.js, manifest.json, and styles.css from the ZIP into the existing .obsidian/plugins/docshelf/ folder. Keep data.json and recovery/. Re-enable the plugin afterward. SHA256SUMS covers the ZIP and standalone assets; the three standard install assets have GitHub provenance attestations.

Existing shelves, routes, settings, recovery records, and document and folder pins remain compatible. Pins are device-local reading preferences stored outside the shared shelf and source documents. No migration is required.

Verification and limits

Requires desktop Obsidian 1.13.7 or later. Native runtime tests pass on macOS with Obsidian 1.15.0, including project, folder, and document pin persistence, keyboard actions, empty registrations, and concurrent vault windows. Browser pin interactions, package integrity, and aggregate checks/builds pass. A full 1.13.7 runtime run is not claimed. Windows and Linux remain unverified; mobile is unsupported. The community review notes distinguish intentional plugin capabilities from hosted scanner findings on the independent web app.

README file from

Github

DocShelf

Browse Markdown and HTML documents across your projects.

Latest DocShelf for Obsidian release, including betas Download DocShelf for Obsidian ZIP

https://github.com/user-attachments/assets/c36997fb-03c5-4080-876f-6658b897e660

This showreel was made in one shot with Claude Opus 5.5.

Key features

  • A shelf across projects. Add files or folders where they live, and view their Markdown and HTML in Obsidian or in the browser. Folders are discovered recursively and update automatically.
  • Links to exact passages. Select Markdown source lines and copy a link to that document and line range. Links start with obsidian://docshelf for Obsidian or https://shelf.localhost/ for the web app after local setup.

DocShelf Web Demo

Why DocShelf?

Project notes, design documents, and agent-generated reports belong beside the work they describe. But as they spread across repositories, finding and reading them becomes a chore. DocShelf brings the documents you choose into one shelf, while also providing a way to select the lines, similar to GitHub permalink, to easily discuss the exact content with the agent.

Choose your app

Use either app independently, or point both at the same shelf.

DocShelf Web

Read Markdown, search across your local documents, and link to exact source lines. Runs as a local web app, without opening Obsidian. The web app never edits your originals.

DocShelf Web at shelf.localhost, displaying Markdown with selected source lines

DocShelf for Obsidian

Bring project documents into Obsidian without copying them into your vault. Edit local Markdown in the native editor, with changes saved to the original file, with conflict checks and recovery.

DocShelf in Obsidian with source lines 13–15 selected, followed by a terminal prompt referencing those lines

Browse HTML in either app

Open HTML reports alongside your Markdown notes. Reports keep their own layout, styling, and interactive elements; both apps display them without editing the source file.

The same HTML report displayed side by side in DocShelf Web (left) and DocShelf for Obsidian (right)

Web screenshot · Obsidian screenshot

Get started

Packaged Obsidian builds install without Git, Node.js, or the web app; see Install the Obsidian plugin. To build from source or run the web app, install Git and Node.js 24 or newer and clone DocShelf beside the projects you want to catalog:

mkdir -p ~/workspace
cd ~/workspace
git clone https://github.com/oliver-im/docshelf.git
cd docshelf
npm ci

Then follow the setup for your app.

Set up the web app

On macOS:

npm run setup

Open https://shelf.localhost/ when setup finishes. Your first shelf includes this README. Choose a document in the sidebar or use search to find a passage. DocShelf starts automatically when you log in; setup asks before administrator access or certificate trust changes.

For a foreground server on other platforms or without automatic startup, use npm run watch. See the web app setup guide for the address, first-shelf setup, and troubleshooting. The web app requires a filesystem with symbolic-link support; Windows is not yet verified.

Install the Obsidian plugin

Requires desktop Obsidian 1.13.7 or later. Open the community listing for the installation link and current review scorecard. The full packaged runtime suite for this desktop beta passes on macOS with Obsidian 1.14.5; earlier focused shared-read checks cover Obsidian 1.13.7. Windows and Linux are not yet verified.

Download DocShelf for Obsidian ZIP · Release notes

For manual installation, extract the ZIP and copy its docshelf folder into <vault>/.obsidian/plugins/. Enable DocShelf in Community plugins.

To produce that ZIP from this checkout:

npm run package:obsidian

The ZIP is written to packages/obsidian/dist/release/docshelf-X.Y.Z.zip, using the plugin version. You can also install the folder at packages/obsidian/dist/docshelf/ directly. When updating, disable DocShelf and copy the new files into the existing plugin folder, preserving data.json and recovery/.

Open DocShelf: Open shelf from the command palette and use Add… to choose a project, then files, folders, or a mixture. Right-clicking a project or document uses that project directly. On macOS, click Add in the picker to register the selection immediately. To use an existing shelf, choose it in DocShelf: Configure shelf. See adding files and folders for recursive discovery and the shared shelf format.

DocShelf reads explicitly registered files outside the vault so documents can remain in their project folders. Local Markdown edits save to the originals; settings and private recovery copies stay in the plugin directory. Interactive HTML runs through an isolated viewer and a token-protected loopback server. Reports and Markdown images may load HTTPS resources; GitHub Markdown uses raw.githubusercontent.com, and published Claude Artifacts use claude.ai and resources loaded by that page. There is no telemetry or account requirement. See file access and network disclosure.

Add documents with your agent

Install the very lightweight docshelf skill to add the documents to DocShelf easily:

npx skills add oliver-im/docshelf --skill docshelf -g

After creating a report or note, ask your agent:

Add this report to DocShelf.

The skill registers the original file, preserves existing shelf entries, checks the result, and returns links for your configured apps. It can also return a source-line reference for a specific passage.

When an agent later edits a document for you, it can mark the document unread in both apps. A Claude Code hook does this after every edit Claude makes, and other agents can run the same command. See agent edits and the event log.

To register documents manually, follow the web app registration guide or Obsidian registration guide.

Guides

License

MIT. Themes adapt Tokyo Night for Obsidian; the optional HTML theme also includes matcha.css. See the third-party notices.