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:

The link graph turns those [[wiki links]] into an interactive map of the workspace — force-directed and zoomable, with nodes colored by tag / state / kind (the legend doubles as a filter), sized by connections or recency, and a metadata panel for the selected paper. Every paper also gets a doc-centred ego view from its sidebar: just that paper's neighbourhood, sliceable to an adjustable link depth:

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:

Drop an inline date anywhere — type /date (or press Cmd/Ctrl-;) for today, or /today / /tomorrow / /yesterday. Each renders a compact calendar chip that round-trips through markdown and can carry a time + timezone (shown in each reader's own zone). A date inside an unchecked task tints overdue (red) or due today (amber); checking the box clears it. Click a chip to edit it in plain language (next fri 3pm, 7/20) and pick a display format:

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.

The same integration adds a TODOs section listing that person's open assigned tasks (see Task assignment below), viewer-filtered the same way.

Task assignment

A @mention inside a task item assigns it to that person; a date atom inside the item is its due date. It's pure interpretation of the document — no task ids, no assignment records, no extra editor UI. Assignment inherits down a task's subtree (a sub-task with no mention of its own takes the parent's assignee), and the first date atom wins as the due date.

The dedicated /-/paper/todos page collects a person's assigned tasks across every paper the viewer can see, bucketed by due date in the viewer's timezone — Overdue / Today / This week / Later / No due date — with a status toggle for open / done / all. It's read-only: each row links into its paper, where you check the box. Both this page and the profile TODOs section are fed by GET /-/paper/api/profile/<actor>/todos, viewer-filtered so you only ever see tasks in papers you're allowed to open.

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.