Paperless-ngx is great at storing, scanning and searching documents. Obsidian is great at connecting ideas. Paperless Sync connects the two: the lease agreement sits next to your moving checklist, the doctor's report links to your health notes, and every invoice from 2024 is one query away.

The PDFs stay in Paperless-ngx. Your vault only gets small, tidy notes like this one:

---
paperless_id: 2
paperless_title: "Electricity bill March 2024"
paperless_url: https://paperless.example.com/documents/2/details
paperless_correspondent: City Power
paperless_document_type: Invoice
paperless_tags:
  - Inbox
  - Home
paperless_created: 2024-03-15
paperless_added: 2024-03-16
paperless_field_amount: EUR84.50
---
[Open in Paperless](https://paperless.example.com/documents/2/details)

Write anything you like below. The plugin never touches it.

✨ What you get

🔍 A taste of what's possible

All invoices, newest first, with the amount from a custom field:

```dataview
TABLE paperless_correspondent AS "From", paperless_created AS "Date", paperless_field_amount AS "Amount"
FROM "Paperless"
WHERE paperless_document_type = "Invoice"
SORT paperless_created DESC
```

Everything still waiting in your inbox:

```dataview
LIST FROM "Paperless" WHERE contains(paperless_tags, "Inbox")
```

The same works without any plugin in a Base: filter on paperless_document_type or paperless_tags and add the columns you want.

🧭 How it works

flowchart LR
    P[("Paperless-ngx")] -- "read-only API" --> S["Paperless Sync<br/>(Obsidian desktop)"]
    S -- "create / update properties" --> V["📁 Your vault<br/>Paperless/"]
    V -- "iCloud, Obsidian Sync, Syncthing…" --> M["📱 Phone & other devices"]

• New document → a new note is created from your file name and note templates.
• Changed document → only the paperless_* properties are updated, plus the document text section if you opted the document in.
• Deleted document → the note stays and gets paperless_missing: true. If the document comes back, the flag goes away.

🚀 Setup

[!NOTE] Paperless Sync runs on Obsidian 1.13.2 or newer on desktop (macOS, Windows, Linux). The notes are ordinary Markdown files, so they still reach your phone with the rest of your vault.

1. Install the plugin and enable it.
2. Get a token: in Paperless-ngx, open My Profile and copy the API token.
3. Connect: in Obsidian, open Settings → Paperless Sync and enter your server address, for example https://paperless.example.com.
4. Store the token: under API token, create a secret that holds it.
5. Click Test connection, then Sync now. 🎉

[!TIP] Use a dedicated Paperless-ngx user with View permission for documents, tags, correspondents, document types, storage paths and custom fields. If one of the lists other than documents isn't readable, the sync still runs and leaves those properties as they are.

[!IMPORTANT] The token lives in Obsidian's secret storage on your device. It is never written to the vault and never synced. Enter it on each device that should sync.

⚙️ Settings

Run Paperless Sync: Sync now from the command palette at any time.

📝 Document text for selected documents

Most paperwork doesn't belong in a vault that is synced to the cloud or read by other tools. So document text stays out unless you opt in per document: set Document text tag, for example to obs-sync, and give that tag to the documents you want in Paperless-ngx. Their notes get a collapsed section at the end:

%% paperless-content start %%
> [!quote]- Document text
> Your payment for March 2024 is EUR 84.50.
%% paperless-content end %%

• The section is updated on every sync, so edits inside it are replaced. Write your own notes above or below it.
• Remove the tag from a document and the next sync removes the section from its note.
• Only tagged documents have their text downloaded.
• If the API user may not read tags, existing sections are left as they are.
• Clearing the setting stops the plugin from touching note text. Sections that already exist stay, so remove the tag from those documents first if you want them gone.

💡 Good to know

Several devices, one vault? Turn on Sync automatically on this device on one device only, for example the computer that is always on. The others get the notes through your vault sync. If two devices create a note for the same new document at the same moment, you may get a duplicate. The sync result names it, and you can delete one of the two.

Limitations

• File names are set when a note is created. If a title changes later, paperless_title is updated but the file keeps its name.
• {{content}} in the note template is filled in once, when the note is created. Use the document text tag for text that stays up to date.
• Links in the note text, such as the default [Open in Paperless]({{url}}), are not rewritten when the server address changes. paperless_url always has the current link.
• Document links in custom fields are written as document IDs.

🔒 Privacy

The plugin talks to exactly one server: the Paperless-ngx instance you configure. It reads document metadata and, for documents you opt in, their text. It contacts no other service and collects no telemetry.

🛠️ Development

npm install
npm run dev        # build in watch mode
npm run validate   # lint, test and build
npm run mock       # mock Paperless-ngx API on http://127.0.0.1:8765, token "dev-token"

Copy main.js and manifest.json to <vault>/.obsidian/plugins/paperless-sync/ to try a build. The mock server serves dev/mock-data.json and rereads it on every request, so you can edit documents while Obsidian is running.

Bug reports and pull requests are welcome. See CONTRIBUTING.md for how to get started.

📜 License

MIT. Not affiliated with Obsidian or Paperless-ngx, just a fan of both.