Paperless Storage

by Johannes Kaindl
5
4
3
2
1
Score: 52/100

Description

Embed documents from your paperless-ngx instance directly in your notes.

Reviews

No reviews yet.

Stats

1
stars
299
downloads
0
forks
105
days
8
days
8
days
0
total PRs
0
open PRs
0
closed PRs
0
merged PRs
0
total issues
0
open issues
0
closed issues
125
commits

Latest Version

9 days ago

Changelog

Changed

  • New and renamed stub files follow the shared file-name rules. A colon followed by a space becomes " — ", * becomes _, " becomes ', ? < > are dropped, \ / | : become -, and # ^ [ ] no longer stay in the name (they broke the embed link ![[…]] that the insert command writes). If the "Filename Sanitizer" plugin is installed, its settings decide instead. Names are still capped at 100 characters. Existing stub files are not renamed; only a new stub, or a rename after a title change, gets the new name.

README file from

Github

Paperless Storage

Embed documents from your paperless-ngx instance directly in your notes — read in the flow of your writing, not through a link.

License: AGPL-3.0 Docs: CC BY-SA 4.0 Release Platform

🇬🇧 English · 🇩🇪 Deutsch

paperless-ngx can generate public share links for a document, but a link like that has no login — anyone who has the URL has the document, and it would sit in plain text in your note (and in your vault's git history). For tax records, contracts, or medical paperwork that's the wrong trade-off. This plugin embeds documents by fetching them with your API token instead, so nothing beyond a small stub file is stored in the vault or shared outside it.

Features

  • Inline PDF embeds — ![[Mietvertrag.paperless]] renders the document right in the note, using Obsidian's own PDF viewer (scrollable, zoomable, no bundled renderer).
  • Insert document command (command palette, while a note is open) opens a search modal over your paperless library and inserts an embed at the cursor.
  • Open in a full pane — clicking a .paperless file in the file explorer opens the document like any other file, not just as an embed.
  • Title synchronization — the Synchronize document titles command renames stub files to match the current document title on the server.
  • Local caching — downloaded PDFs are cached in the vault, so a document stays readable offline once it has been opened; a command clears the cache on demand.
  • API-token auth, not public links — nothing is shared outside your vault and your own paperless instance.

Requirements

  • Obsidian 1.8.7+, desktop and mobile. The plugin uses no Node or Electron API: it fetches over Obsidian's own requestUrl, caches through the vault API, and displays documents in Obsidian's built-in PDF viewer — all of which exist on mobile too.
  • A reachable paperless-ngx instance and an API token for it (created under paperless' own settings).

Install

Community plugins

Settings → Community plugins → Browse → "Paperless Storage" → Install → Enable.

Manual

Download main.js, manifest.json and styles.css from the latest release and copy them into <vault>/.obsidian/plugins/paperless-storage/, then enable the plugin.

BRAT (beta)

Add johannes-kaindl/paperless-storage in BRAT.

From source

git clone https://git.jkaindl.de/jkaindl/paperless-storage
cd paperless-storage && npm install && npm run build
# copy main.js manifest.json styles.css into <vault>/.obsidian/plugins/paperless-storage/

Usage

  1. Open Settings → Paperless Storage and enter your server URL and API token.
  2. Run Paperless Storage: Insert document from the command palette to search your paperless library and insert an embed at the cursor.
  3. The embed downloads and caches the document on first view; after that it renders from the local cache, also offline. When the document was replaced or reprocessed in paperless, the next display fetches the new version on its own (the plugin remembers the document's checksum next to the cached PDF); Clear document cache forces a fresh download.
  4. Click a .paperless file in the file explorer to open it full-pane, exactly like a native file.
  5. Run Synchronize document titles to rename stub files to match their current title on the server.
  6. Clear document cache removes the downloaded PDFs.

What it looks like

A note on renaming

Obsidian shows its own "Update internal links?" confirmation dialog when a .paperless file gets renamed (including via the title-sync command above) — this happens because .paperless is an unregistered file extension, and it happens even with "Always update links" enabled in Obsidian's own settings. If a rename command appears to hang, check for that dialog.

Configuration

Setting Effect Default
Server URL Base URL of your paperless-ngx instance. (empty)
API token Token for that instance, created under paperless' own settings. Stored in Obsidian's keychain on this device (enter it again on each device); Obsidian before 1.11.4 has no keychain, so the token stays in the plugin's data.json there. (empty)
Cache folder Vault folder where downloaded PDFs are cached. _paperless-storage/
Hide cache folder Hides the cache folder in the file explorer (it stays a normal, syncable folder — only the display is suppressed). on
File version Which version of the document to embed and cache — the searchable archive PDF, or the original file. Archive
Default embed height Fixed height (in pixels) for embedded documents; leave empty to let Obsidian size the embed itself. (empty)

How it works

A .paperless stub file (a small JSON file carrying the document ID) is a real file in your vault — it gets backlinks, appears in the graph, and works with autocomplete like any other file. An adapter on Obsidian's (undocumented) embedRegistry renders it: the document bytes are fetched from paperless-ngx using your API token, cached in the vault, and handed to Obsidian's own PDF viewer for display — no PDF renderer is bundled with this plugin. Architecture: AGENTS.md.

Contributing

Issues on GitHub; the canonical source is git.jkaindl.de. This project is test-driven (npm test, npm run gate); see AGENTS.md for the wider development workflow.

Documentation

License

Copyright © 2026 Johannes Kaindl.