Paper College
Maxim Dorogan34 downloadsSync glossary notes and your mindmap from paper.college into your vault, and open papers in a temporary PDF view without saving any files.
- Overview
- Scorecard
- Updates5
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
- Open Settings then Community plugins in Obsidian.
- Turn off Restricted mode if it's on.
- Choose Browse, search for "Paper College", and install it.
- 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.
- Enable the plugin. Open its settings tab, or use the Connect notice shown on first run.
- 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. - On that page, generate a pairing code. It's 8 digits and expires shortly.
- Type the code into the Pairing code field in Obsidian and choose Connect.
- 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.