DocShelf for Obsidian 0.6.0 (desktop beta)

DocShelf for Obsidian 0.6.0 — desktop beta

Clear a folder or project's unread documents in one action.

• Right-click a folder or project and choose Mark all as read, directly above Remove from shelf…. The action includes documents in collapsed subfolders, leaves other groups unread, and is disabled when everything in the group is already read.
• Documents that arrive later still become unread. Read state stays on your device, and the action does not open documents or change their source files or the shared shelf.
• DocShelf Web includes the same menu action, including on static sites where shelf removal is unavailable. Its read state remains separate from Obsidian's.

Install or update

Use Obsidian's Community plugins settings to check for updates, or open the community listing. For a manual install, download docshelf-0.6.0.zip, extract it, and copy its docshelf folder into <vault>/.obsidian/plugins/. To update an existing installation, save or review pending Markdown edits, disable DocShelf, and replace the plugin files while preserving 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 shelf files, routes, settings, read state, and recovery records remain compatible; no migration is required. Update your web checkout separately to use the web menu action.

Verification and limits

Requires desktop Obsidian 1.13.7 or later. Local runtime checks target macOS with Obsidian 1.13.7. Windows, Linux, and later Obsidian versions remain unverified; mobile is unsupported.

Verification covers the aggregate tests, type and lint checks, builds, package checks, and the packaged runtime suite in a disposable vault. The bulk-read checks exercise nested and collapsed folders, project boundaries, persistence, disabled actions, and later arrivals. Browser checks also cover keyboard navigation, static hosting, and read state shared between tabs.

DocShelf for Obsidian 0.5.0 (desktop beta)

DocShelf for Obsidian 0.5.0 — desktop beta

Cite source lines directly from rendered HTML reports.

• Select report text or right-click a block to highlight its source lines and copy a file.html:line-range reference. A copy button follows the highlighted selection as the report scrolls, and the view actions switch between the report and its selected source lines.
• Report selections stay current after reloads and script-driven DOM changes. Clipboard actions validate the current selection and the injected button's placement; report scripts remain isolated from Obsidian's privileged environment, but the report DOM itself remains untrusted.
• Report drags avoid activating the sidebar and forward releases outside the report even when the pointer immediately moves. Drifting double- and triple-clicks stop at the last block above the pointer.
• An unset workspace root now defaults to your home directory. Explicit workspace settings still apply, and containment errors identify the requested path, resolved target, and allowed roots. Every source still requires registration and containment checks.
• Contributors can replace an existing local plugin installation with npm run install:local. It stages files and retains rollback copies before replacement, preserves settings and recovery drafts, and reloads only a vault Obsidian already has open.

Install or update

Open the community listing for the installation link and current scorecard. For a manual install, download docshelf-0.5.0.zip, extract it, and copy its docshelf folder into <vault>/.obsidian/plugins/. To update an existing installation, save or review pending Markdown edits, disable DocShelf, and replace the plugin files while preserving 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 shelf files, routes, settings, read state, and recovery records remain compatible; no migration is required. Set an explicit workspace root if you want to retain a narrower default boundary.

Verification and limits

Requires desktop Obsidian 1.13.7 or later. Local runtime checks target macOS with Obsidian 1.13.7. Windows, Linux, and later Obsidian versions remain unverified; mobile is unsupported. Automated CDP input does not reproduce Electron's stray host events, so the runtime suite injects the relevant host event explicitly and unit tests cover delayed release ordering.

The aggregate tests, type and lint checks, builds, and package checks pass. The complete packaged 0.5.0 runtime suite passed in a disposable vault with no renderer errors. Regression tests exercise immediate movement after an outside release, delayed guest notification, failed installer copies and replacements, rollback failure, and preservation of private settings and recovery files.

DocShelf for Obsidian 0.4.1 (desktop beta)

DocShelf for Obsidian 0.4.1 — desktop beta

Fix a stacked context menu when you right-click a source reference twice.

• Right-clicking a selected source range or a line button while its DocShelf menu is still open now replaces that menu instead of opening a second one beside it. This applies across split panes. Other menus that are open at the time, such as Obsidian's editor menu, may still need to be closed separately.

Install or update

Open the community listing for the installation link and current scorecard. For a manual install, download docshelf-0.4.1.zip, extract it, and copy its docshelf folder into <vault>/.obsidian/plugins/. To update an existing installation, save or review pending Markdown edits, disable DocShelf, and replace the plugin files while preserving 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 shelf files, routes, settings, read state, and recovery records remain compatible; no migration is required.

Verification and limits

Requires desktop Obsidian 1.13.7 or later. Local runtime checks target macOS with Obsidian 1.13.7. Windows, Linux, and later Obsidian versions remain unverified; mobile is unsupported.

The aggregate tests, type and lint checks, builds, and package checks pass. The runtime suite has a new check that right-clicks a reference while its menu is open; it fails without this fix and passes with it. The complete packaged 0.4.1 runtime suite passed in a disposable vault with no renderer errors; other local runs still fail intermittently at unrelated timing-sensitive steps.

DocShelf for Obsidian 0.4.0 (desktop beta)

DocShelf for Obsidian 0.4.0 — desktop beta

See at a glance which documents are new or were changed by an agent since you last read them.

• Documents that arrive on the shelf are unread until you open them, like new mail: the name is bold with a dot, and each folder and project containing it shows a dot. This covers files that appear in watched folders and registrations made elsewhere, such as by an agent or in DocShelf Web. Everything already on the shelf when the plugin first loads it, and anything you add with Add…, starts as read.
• When an agent announces an edit to a registered document, for example after you give it feedback, the document turns unread again. Your own edits never do. A document shown in a focused Obsidian window, including a split pane, stays read because you saw it change.
• Agents announce edits by appending to an event log beside the shelf, shelf.local.events.jsonl for shelf.local.json. A Claude Code hook can do this automatically after every edit; other agents follow a one-line instruction. See agent edits and the event log for the hook, the instruction, and the format.

Read state stays on your device, per vault and shelf, and is never written to the shelf file. DocShelf Web keeps its own read state per browser, so opening a document in one app does not mark it read in the other. The web app reads the same event log through its local watcher; update the checkout and restart the watcher to enable it. DocShelf Web and the Obsidian plugin are updated separately.

Install or update

Open the community listing for the installation link and current scorecard. For a manual install, download docshelf-0.4.0.zip, extract it, and copy its docshelf folder into <vault>/.obsidian/plugins/. To update an existing installation, save or review pending Markdown edits, disable DocShelf, and replace the plugin files while preserving 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 shelf files, routes, settings, and recovery records remain compatible; no migration is required. After the update, everything already on the shelf starts as read, and the plugin begins at the current end of the event log, so earlier announcements are not replayed.

Verification and limits

Requires desktop Obsidian 1.13.7 or later. Local runtime checks target macOS with Obsidian 1.13.7. Windows, Linux, and later Obsidian versions remain unverified; mobile is unsupported. The runtime test suite now refuses to run on Windows, or on Linux with XDG_RUNTIME_DIR set, because it cannot isolate Obsidian's command-line socket there.

The aggregate tests, type and lint checks, builds, and package checks pass. The complete packaged 0.4.0 runtime suite passed in a disposable vault, including fresh installation, preservation of settings and recovery files during plugin replacement, arrival of new documents, and an announced edit to the open document, with no renderer errors. Other local runs failed intermittently at timing-sensitive steps, such as a shelf refresh or a table context menu that opened twice; the same steps also fail intermittently without this release's changes.

DocShelf for Obsidian 0.3.0 (desktop beta)

DocShelf for Obsidian 0.3.0 — desktop beta

Browse registered folders as a collapsible tree and remove a folder or an entire project from the shelf without deleting its original files.

• Keep explicitly registered folders visible when they contain no documents, with a muted “No documents” label. Their project stays visible, and newly discovered documents appear in the same folder.
• Preserve registered folder boundaries while compacting other single-folder chains. Unregistered empty descendants stay out of the tree.
• Reorder sibling folders and documents within their containing folder, with saved collapse state and stable folder identities as documents appear or disappear.
• Remove folders and projects through their existing context menus. Confirmations show the affected documents and registrations, protect unsaved drafts, and revalidate the shelf before applying the change. Removed subfolders receive exclusions so their documents do not return through a parent registration.

The corresponding web app improvements are available from the updated checkout, including consistent project grouping when a hand-edited shelf contains surrounding whitespace in project names. DocShelf Web and the Obsidian plugin are updated separately.

Install or update

Open the community listing for the installation link and current scorecard. For a manual install, download docshelf-0.3.0.zip, extract it, and copy its docshelf folder into <vault>/.obsidian/plugins/. To update an existing installation, save or review pending Markdown edits, disable DocShelf, and replace the plugin files while preserving 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 shelf files, routes, settings, and recovery records remain compatible; no migration is required. Folder and project removal changes registrations and exclusions, never the original source files.

Verification and limits

Requires desktop Obsidian 1.13.7 or later. Local runtime checks target macOS with Obsidian 1.13.7 and Electron 34.2.0. Windows, Linux, and Obsidian 1.14.2 remain unverified; mobile is unsupported.

The aggregate tests, type and lint checks, builds, and package checks pass. The complete packaged 0.3.0 runtime suite passed in a disposable vault, including fresh installation, preservation of settings and recovery files during plugin replacement, and the new folder lifecycle. Earlier local runs intermittently reported illegal access renderer errors, also seen on the earlier branch revision; the successful packaged run reported none.

DocShelf for Obsidian 0.2.3 (desktop beta)

DocShelf for Obsidian 0.2.3 — desktop beta

This maintenance release addresses repository findings from Obsidian's review and improves contributor verification. The independent web app now has strict browser JavaScript type checking and typed lint checks, explicit DOM and library types, and validated message payloads. Its reader also tolerates malformed outline fragments and incomplete table markup. The installation guides link to the community listing, and a contributing guide explains setup and required checks.

The plugin's runtime behavior, supported sources, shelf format, settings, and recovery records are unchanged. The review notes distinguish the fixes from intentional filesystem, clipboard, release-attachment, and CSS capabilities, plus scanner findings on code outside the plugin. Local verification does not predict the next hosted review's warning count.

Install or update

Open the community listing for the installation link and current scorecard. For a manual install, download docshelf-0.2.3.zip, extract it, and copy the docshelf folder into <vault>/.obsidian/plugins/. To update manually, save or review pending Markdown edits, disable DocShelf, and replace the plugin files while preserving data.json and recovery/. Re-enable the plugin afterward. SHA256SUMS covers the ZIP and standalone assets; the three install assets have GitHub provenance attestations.

Requires desktop Obsidian 1.13.7 or later. Runtime verification targets macOS with Obsidian 1.13.7 and Electron 34.2.0. Windows, Linux, and Obsidian 1.14.2 remain unverified; mobile is unsupported.

DocShelf for Obsidian 0.2.2 (desktop beta)

DocShelf for Obsidian 0.2.2 — desktop beta

This patch resolves the remaining source-code error found by Obsidian's hosted review of 0.2.1. The HTML viewer now creates its Electron webview through Obsidian's typed element helper, without a forbidden lint exception. Each guest stays detached until its sandbox and private session are configured. Local HTML guests also receive a navigation guard before attachment; remote Claude Artifact guests do not use that local-document guard.

Shelf files, settings, recovery records, and document behavior remain compatible. The review notes explain the retained capability and CSS advisories.

Install or update

Download docshelf-0.2.2.zip, extract it, and copy the docshelf folder into <vault>/.obsidian/plugins/ for a fresh installation. To update, save or review pending Markdown edits, disable DocShelf, and replace the plugin files while preserving data.json and recovery/. Re-enable the plugin afterward. SHA256SUMS covers the ZIP and standalone assets; the three install assets have GitHub provenance attestations.

Requires desktop Obsidian 1.13.7 or later. Runtime verification targets macOS with Obsidian 1.13.7 and Electron 34.2.0. Windows, Linux, and Obsidian 1.14.2 remain unverified; mobile is unsupported.

DocShelf for Obsidian 0.2.1 (desktop beta)

DocShelf for Obsidian 0.2.1 — desktop beta

This patch improves settings discovery and addresses the actionable findings from Obsidian's automated community review. Existing shelf files, settings, and recovery records remain compatible.

Changes

• DocShelf settings now appear in Obsidian's settings search. Shelf changes still use Save and reload; the vault's readable-line-length preference still applies immediately.
• Strengthen types at parsing and desktop API boundaries, and use the appropriate window for view timers and animation callbacks.
• Make the plugin build discoverable from the repository root and generate GitHub provenance attestations for the three standard install assets.
• Add repeatable lint checks for the review's type, API, and DOM safety findings. The same repository also sanitizes DocShelf Web's Mermaid output while preserving diagram labels and source fallbacks.

The review notes explain retained filesystem access, lock-owner process checks, user-triggered clipboard writes, and optional release attachments. The plugin's containment, recovery, and isolated HTML viewer protections remain in place.

Install or update

Download docshelf-0.2.1.zip, extract it, and copy the docshelf folder into <vault>/.obsidian/plugins/ for a fresh installation. To update, save or review pending Markdown edits, disable DocShelf, and replace the plugin files while preserving data.json and recovery/. Re-enable the plugin afterward. SHA256SUMS covers the ZIP and standalone assets; dependency licenses are included in the ZIP and embedded in main.js.

Requires desktop Obsidian 1.13.7 or later. Runtime verification targets macOS with Obsidian 1.13.7 and Electron 34.2.0. Windows, Linux, and Obsidian 1.14.2 remain unverified; mobile is unsupported. Community review status is shown in the directory after publication and scanning.

DocShelf for Obsidian 0.2.0 (desktop beta)

DocShelf for Obsidian 0.2.0 — desktop beta

This release lets you add files and whole folders from inside Obsidian, remove documents from the shelf without touching the originals, and recognize documents in the sidebar by their filenames.

New

• Add files and folders. Use the shelf's + button, DocShelf: Add…, or right-click. Choose or create a project, then pick files, folders, or a mixture. On macOS a combined picker adds the selection immediately; other desktop platforms accept paths in a form. See Add files and folders.
• Folders stay current. Registered folders are scanned recursively, including subfolders created later. New documents appear, edits refresh open views and search, and deleted documents leave the shelf. Hidden folders, common generated trees such as node_modules and dist, and descendant symlinks are skipped, and every document must stay inside the selected folder and the workspace root.
• Remove from shelf. Right-click a document and choose Remove from shelf…. Only the shelf changes; the original file or remote document is untouched. A document removed from a watched folder is excluded by its exact path so it does not reappear. An open unsaved draft is kept and blocked from saving back.
• Filename-first sidebar rows. Rows show the source filename, followed by the document's title in muted text when the title says more than the filename. Claude Artifacts keep their title. Reset to alphabetical sorts by filename, and search now matches filenames.

Migration

Existing version 1 shelves keep working without changes. Adding the first folder upgrades the shelf file to version 2, which DocShelf for Obsidian 0.1.0 and older DocShelf Web checkouts reject rather than silently omitting folder contents. If Obsidian and DocShelf Web share a shelf, update both before adding a folder.

Update a local installation

Save or review pending Markdown edits and disable DocShelf before copying the new files into the existing plugin directory. Preserve data.json and recovery/; do not replace or delete the whole directory. Re-enable the plugin after copying.

To install fresh, download docshelf-0.2.0.zip from this release's assets, extract it, and copy the docshelf folder into <vault>/.obsidian/plugins/. SHA256SUMS lists the checksums of the ZIP and standalone assets.

Compatibility

Requires desktop Obsidian 1.13.7 or later. Runtime verification covers macOS, Obsidian 1.13.7, and Electron 34.2.0. Windows, Linux, and Obsidian 1.14.2 are not yet verified. Mobile is unsupported. The plugin is not yet listed in Obsidian's community directory. The 0.1.0 release notes describe the file access and network boundaries, which are unchanged.

Feedback

Report problems in GitHub Issues, including your OS and Obsidian version and a small reproducible example. Remove private paths and document contents before sharing logs or recovery files. Use the security policy for sensitive reports.

v0.1.0

DocShelf Web brings the HTML reports and Markdown notes scattered across your projects into one local site while keeping their source files in place. This is its first announced early release.

Included

• Explicit registration of local HTML and Markdown files and recursive folders, grouped by project, with production full-text search and automatic rebuilding after source changes.
• Add… from the header or a right-click: enter file or folder paths, choose a project, preview the discovered documents, and add them. Remove from shelf… changes only the shelf; originals stay untouched.
• Markdown reading in light and dark themes, including tables, highlighted code, Mermaid diagrams, a page outline, and source-line range links.
• Local HTML reports in an opaque sandbox, with interactive scripts but no access to DocShelf's storage, page, or local actions.
• Browser imports for public GitHub Markdown and published Claude Artifacts.
• A resizable sidebar and document actions for opening, copying links, viewing remote sources, and revealing registered local files in Finder on macOS.
• A portable Node.js watcher, an optional macOS login service at https://shelf.localhost/, and an agent skill for registering completed documents.
• A shared shelf with DocShelf for Obsidian, which is released separately.

Install or upgrade

Use Node.js 24 or newer and a filesystem with symbolic-link support. Follow the installation instructions.

Existing checkouts should stop the watcher, update, run npm ci, and restart it. Keep shelf.local.json. If you use the macOS login service, uninstall it before updating and reinstall it afterward with the same address, port, and DOCSHELF_WORKSPACE settings. Normal macOS setup uses https://shelf.localhost/; keep --direct when reinstalling a direct-port setup. See the upgrade guide.

Legacy artifacts.local.json remains supported with a deprecation warning. Rename it only when shelf.local.json does not already exist; otherwise merge the entries you want to keep.

Shelf format

Existing version 1 shelves keep working. Adding the first folder upgrades the shelf to version 2, which older checkouts and DocShelf for Obsidian 0.1.0 reject rather than silently omitting folder contents. If both apps share a shelf, update both before adding a folder. See adding files and folders.

DocShelf for Obsidian

The Obsidian plugin is versioned and released separately with plain X.Y.Z tags. Install the latest plugin ZIP from the releases page rather than from this web release. Both apps can use a shelf at the web checkout root; keep its sources relative and its routes lowercase. Obsidian's GitHub registrations and absolute source paths are not supported in a shared web shelf. See shared setup and limits.

Early-release limits

Full-text search covers registered local documents. Browser-imported Markdown is fetched again on reload and is not available offline, and import bookmarks depend on that browser's saved source links. Private GitHub files and arbitrary remote pages are unsupported. Claude embeds require the owner to allow the DocShelf origin.

Adding and removing documents, live rebuilding, and Finder actions require the loopback watcher; static hosting supports browsing and public-document imports only. Keep the default loopback binding for a personal shelf. See the security policy for the containment and isolation boundaries.

CI covers Ubuntu, and local verification has covered macOS. Windows and a broad browser compatibility matrix have not yet been verified. During 0.x, breaking changes will be called out with migration guidance in minor-release notes.

What's Changed

• Prefer Google Chrome over snap Chromium in the HTML isolation test by @oliver-im in #21
• Refresh Obsidian README screenshots for filename-first rows by @oliver-im in #22
• Update DocShelf Web 0.1.0 notes and security policy by @oliver-im in #23
• Release DocShelf Web v0.1.0 by @oliver-im in #24

Full Changelog: 0.2.0...v0.1.0