Paper College

An Obsidian plugin for paper.college. It copies your glossary notes and your mindmap from your paper.college account into your vault as Markdown and Canvas files, and opens the papers themselves in a temporary PDF view.

Sync runs in one direction only: from paper.college into the vault. The plugin never uploads note content, and PDFs are never written to your vault or to your computer.

Required disclosures

Please read this section before installing. It covers the things Obsidian's Developer policies require plugin authors to disclose.

An account is required

The plugin does nothing on its own. You need a paper.college account, and you have to pair the vault with that account before any command works. There is no offline or local-only mode. Glossary terms and the mindmap are created on paper.college; this plugin only copies them down.

Network use

The plugin is not usable offline and makes network requests to the site configured in Paper URL (default https://paper.college). All requests go through Obsidian's own requestUrl API. These are the only requests it makes:

When	Request	What is sent	Why
You submit a pairing code	POST /api/obsidian/pairing/exchange	The 8-digit pairing code and the name of the current vault	Trades the short-lived code for a device token so the vault can authenticate later
You run a sync	GET /api/obsidian/sync	The device token, as an Authorization: Bearer header	Downloads your glossary terms, paper titles, and mindmap
You open a paper	GET /api/papers/<paperId>/file	The device token and the paper's id	Asks for a short-lived signed download URL for that PDF
Immediately after the above	GET <signed storage URL>	Nothing beyond the signed URL itself	Downloads the PDF bytes into memory so they can be drawn on screen

Nothing else is contacted. The plugin does not talk to any third-party service, ad network, or update server.

Two related notes. Choosing Connect opens https://paper.college/settings#obsidian in your normal web browser so you can generate a pairing code; that page is a website visit, not a plugin request. And the Paper URL setting only accepts https:// addresses, with one exception: http:// is accepted when the host is exactly localhost, so that people developing paper.college can point the plugin at a local server. It is not meant to be changed otherwise.

What leaves your vault

The name of your vault, sent once during pairing so you can tell your devices apart in paper.college settings. That is the only vault-derived data the plugin ever transmits.

The plugin does not read, index, or upload the content of your notes. Sync is strictly one-way, server to vault: nothing in your vault is sent back to paper.college, and edits you make to synced notes are never pushed anywhere.

No telemetry

There is none. The plugin contains no analytics, no usage tracking, and no error or crash reporting. The requests in the table above are the complete list.

How your device token is stored

After pairing, the plugin saves your device token with Obsidian's standard saveData() mechanism. It lands in plain text in:

<vault>/.obsidian/plugins/paper-college/data.json

This is the only storage Obsidian offers plugins; there is no encrypted secret store available. It has a consequence worth understanding: the token is a file inside your vault, so it travels with anything that copies your vault. Obsidian Sync, iCloud, Dropbox, Git, and ordinary backups will all carry it. Anyone who can read that file can read your papers and glossary on paper.college until the token is revoked.

If you don't want that, either don't pair vaults you sync to places you don't control, or revoke the token when you're done with a device.

Revoking access, and a limitation you should know about

To fully revoke a device, go to Settings on paper.college, find the vault in the device list, and choose Disconnect. That revokes the token server-side, and it stops working everywhere.

The plugin's own Disconnect button and the Disconnect command do not do this. They only clear the token and account details from this vault's local settings. The token stays valid on the server, so any copy of data.json made beforehand still works. This is a known bug, a fix is tracked, and it has not shipped yet. Until it does, treat the in-app Disconnect as "stop using this vault", and use the paper.college settings page whenever you actually need the token dead.

Desktop only

The manifest sets isDesktopOnly: true. The plugin is not tested on Obsidian mobile and is not supported there.

Installation

From the community plugin directory

1. Open Settings then Community plugins in Obsidian.
2. Turn off Restricted mode if it's on.
3. Choose Browse, search for "Paper College", and install it.
4. Enable the plugin.

Manually

Download main.js, manifest.json, and styles.css from the latest release and put all three in:

<vault>/.obsidian/plugins/paper-college/

Then reload Obsidian and enable the plugin under Community plugins.

Setup

Pairing links one vault to one paper.college account.

1. Enable the plugin. Open its settings tab, or use the Connect notice shown on first run.
2. Choose Connect. Your browser opens https://paper.college/settings#obsidian. If it doesn't open, the settings tab shows the link with a Copy button.
3. On that page, generate a pairing code. It's 8 digits and expires shortly.
4. Type the code into the Pairing code field in Obsidian and choose Connect.
5. Once it says you're connected, choose Sync now.

The first sync creates a Paper folder in your vault:

Paper/
  Glossary/      one Markdown note per glossary term
  Papers/        one Markdown note per paper, linking to its terms
  Mindmap.canvas your mindmap, as an Obsidian Canvas file

If you have no glossary terms yet, you get a Paper/Glossary.md placeholder instead of the Glossary notes.

Every note the plugin writes carries paper_sync: true in its frontmatter. Later syncs replace only files that carry that marker, so notes you wrote yourself are never overwritten, even if they sit in the same folder. If you edit a synced note in place, the next sync will overwrite your edits.

Commands

All of these appear in the command palette under "Paper College".

Command	What it does
Connect	Starts pairing, or opens settings if the vault is already paired
Sync glossary and mindmap	Downloads your glossary, paper notes, and mindmap
Open paper PDF…	Lists papers from the last sync and opens the one you pick
Open Paper folder	Opens Mindmap.canvas in the configured folder
Disconnect	Clears this vault's stored token, after a confirmation

There is also a ribbon icon that syncs, and a status bar item showing when the last sync happened. Selecting the status bar item opens the plugin's settings.

Inside a synced note or the mindmap Canvas, selecting a paper link opens that paper in the PDF view rather than in your browser.

Reading papers

Papers open in a Paper PDF tab. The plugin fetches a short-lived signed URL, downloads the PDF into memory, and draws the pages. The bytes are discarded when the tab closes.

There is deliberately no Save, Download, or Add-to-vault control: the PDF is never written to your vault or your filesystem. If you want the file itself, use Open in Paper in the tab toolbar to open the paper on paper.college.

The view needs a network connection. Signed URLs expire, so a tab left open for a long time refreshes its URL in the background. Your synced notes remain readable offline; only the PDF view does not.

Settings

Setting	Description
Connection	Pair the vault, view which account it's connected as, sync, disconnect, or replace the pairing with a different one
Vault folder	Folder that receives synced notes and the mindmap. Defaults to Paper. No PDFs are saved here
Sync now	Runs a sync immediately
Sync on startup	Sync once when Obsidian starts. Off by default
Paper URL	The site to talk to. Defaults to https://paper.college. Only change this if you are developing paper.college locally

Development

Requires Node.js 18 or later.

git clone https://github.com/Angroys/paper-college-obsidian.git
cd paper-college-obsidian
npm install

Build once, for a release:

npm run build

Or watch and rebuild while you work:

npm run dev

To test against a local paper.college instance, set Paper URL to http://localhost:3000.

The quickest way to try changes is to clone into <vault>/.obsidian/plugins/paper-college/ directly, run npm run dev, and reload Obsidian after each rebuild.

Support

Bug reports and questions go to GitHub issues. When reporting a sync or connection problem, please include your Obsidian version, your operating system, and what the status bar showed.

Please do not paste the contents of data.json into an issue. It contains your device token.

License

MIT. See LICENSE.

This plugin bundles PDF.js (Apache License 2.0) to render papers.