Obsidian Stats logoObsidian Stats

Paperless Storage

by Johannes Kaindl
5
4
3
2
1
Score: 51/100
Install Code

Description

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

Reviews

No reviews yet.

Stats

1
stars
129
downloads
0
forks
58
days
0
days
0
days
0
total PRs
0
open PRs
0
closed PRs
0
merged PRs
0
total issues
0
open issues
0
closed issues
98
commits

Latest Version

0.3.2
18 hours ago

Changelog

Added

  • The GitHub release now also carries a ready-to-unpack paperless-storage.zip (the plugin folder with main.js, manifest.json and styles.css) and a checksums.sha256 file. For a manual install, download the zip and unpack it into .obsidian/plugins/ instead of creating the folder and saving three files by hand.

Changed

  • Internal design notes moved out of the repository; the user documentation is unchanged.
See all version on GitHub

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. To fetch a newer version, run Clear document cache.
  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. (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.

Sponsors