datasette-paper

Collaborative document editor for Datasette. ProseMirror frontend, SQLite-backed storage in Datasette's internal database, real-time collaboration over SSE.

Rich text with tables and task lists, wiki-style links between papers, images (paste, drag-and-drop, or insert from the toolbar), and per-paper sharing:

Insert an image by pasting, dropping a file, or using the toolbar's image button — which offers a paste area or a file upload with a live preview:

And a paper index listing everyone's papers with author and last-edited time:

Drop inline #tags anywhere in a paper's body — type # for an autocomplete of existing tags. Clicking a tag opens a results page listing every paper whose body mentions it:

Installation

Install in the same environment as Datasette:

datasette install datasette-paper

Quickstart

datasette --internal papers.db \
  -s permissions.datasette-paper-list true \
  -s permissions.datasette-paper-create true \
  -s permissions.datasette-paper-view true \
  -s permissions.datasette-paper-edit true

No user database is required — papers live in Datasette's internal database.

Pass --internal <path> to persist papers across restarts. Without it, Datasette uses an ephemeral tempfile for the internal DB that is deleted when the process exits. The plugin emits a startup warning when it detects this, so you don't lose your papers to a forgotten flag.

Permissions

Four actions gate access. The view/edit actions are per-paper; list/create are global.

The plugin registers a permission_resources_sql hook that resolves per-paper view/edit grants from the _datasette_paper_doc.created_by column (owners) and the _datasette_paper_share table (explicit grants

• link-visibility levels).

Sharing

Each paper has one of three visibility levels:

• private — only the owner and explicitly-shared actors can access.
• link-view — any authenticated actor with the link can view.
• link-edit — any authenticated actor with the link can view and edit.

Plus per-actor share rows that grant a specific actor a viewer or editor role on a single paper.

The owner is whoever created the paper (created_by, captured from the actor cookie at create time). Only the owner can change visibility or mutate shares.

Profile integration

When datasette-user-profiles is installed, each person's profile page grows a Papers section (registered via its datasette_user_profile_sections hook). It lists the papers that actor created plus the ones they've recently edited, newest activity first, each badged Created / Edited. The list is filtered to the papers the viewer is allowed to see — a paper you can't open never shows up on someone else's profile. The section is populated from GET /-/paper/api/profile/<actor>/docs.

Papers as data

Paper data lives in Datasette's internal database under tables prefixed with _datasette_paper_:

• _datasette_paper_doc — one row per paper (id, name, visibility, created_by).
• _datasette_paper_step — append-only log of ProseMirror steps.
• _datasette_paper_snapshot — periodic full-document snapshots.
• _datasette_paper_share — per-actor view/edit grants.

Wire protocol

JSON API rooted at /-/paper/api/... — no per-database segment. List/create docs, bootstrap a paper, post step batches, stream updates over SSE, manage shares, render markdown / extract tasks. See CLAUDE.md for the full endpoint table.

Frontend stack

Vite + Svelte 5 + ProseMirror. Bundle outputs to datasette_paper/static/.

Development

npm install --prefix frontend
just frontend          # build the bundle
just dev               # run datasette with the plugin + permissions granted
just dev-with-hmr      # vite dev server + watchexec restart
just shots             # regenerate docs/screenshots/*.png (used in this README)

just shots is self-contained: it builds the bundle, boots a throwaway Datasette with seeded papers, drives Playwright to capture each surface, and tears the server down. The PNGs are committed, so re-run and commit when the UI changes (the diff shows what changed). Pass shot names to regenerate a subset, e.g. just shots editor tables.

Run the test layers:

just test              # backend pytest
just test-frontend     # vitest
just test-e2e          # playwright (requires built bundle)

Always invoke Python with uv run --prerelease=allow … — datasette is on a >=1a23 pre-release pin.