zotLook

Documentation

What zotLook is, what it needs, and how to install it: preview Zotero attachments with the Space key on macOS, Linux and Windows.

zotLook is a plugin for the open-source reference manager Zotero. It previews the attachment of the selected Zotero item when you press Space, the way a file manager does. zotLook carries no viewer of its own; it drives the preview the system already has:

Whatever those can show, zotLook can therefore show as well. And if you extend a preview program with plugins, you extend what zotLook can do with it.

Beyond that, Ctrl+Shift+Space builds a contact sheet of a PDF: a grid of every page, its column count adjustable. That helps most with long documents such as books, because the system’s preview will show you every page but only one or two at a time. The contact sheet zotLook builds is shown by the system preview — and a click on a page opens it in Zotero’s reader. Building one can take a few seconds; a progress indicator names the page zotLook is currently rendering.

What sets zotLook apart, besides previewing on every platform, is that Zotero’s annotations become part of the preview — in the system’s preview as well as on the contact sheet. Zotero keeps annotations in its database rather than in the file, so a preview would normally show the document without them. The feature can be switched off in zotLook if you would rather see the file as it is stored.

The contact sheet under GNOME Sushi on Linux, showing a PDF whose sixteen pages reproduce the zotLook logo

The sheet’s two menus, on macOS: the contents from the PDF’s outline, the annotations from Zotero, each entry bringing its page to the middle of the sheet, and a click on the page handing over to the reader.

What you need

Zotero Zotero 10 — the version zotLook is developed and tested against. On older ones, see below.
macOS macOS 12 (Monterey) or later. Nothing to install, Quick Look is part of the system.
Linux GNOME Sushi. On Debian and Ubuntu: sudo apt install gnome-sushi.
Windows QuickLook. The Store and website versions work alike.

Older versions of Zotero

zotLook still installs on Zotero 7 and later, and may well work there, but it has been neither developed nor tested on 7, 8 or 9, so nothing about them is claimed. Reading Zotero’s own sources says this much:

  • Everything else the plugin calls is there in 7.0.0 already — zotero://open-pdf?cfi=, PreferencePanes.register, PDFWorker.export, getMainWindows.
  • EPUB.mjs, which the EPUB preview and the EPUB page overview are built on, first appears in Zotero 8. Below that, nothing to do with EPUB can work.
  • Whether Zotero 7 keeps its bundled pdf.js where the contact sheet looks for it, I could not check.

If you run zotLook on an older Zotero — successfully or not — please say so. Reports are welcome and will be noted here.

Install

  1. Download the latest .xpi from the releases page.
  2. In Zotero: Tools → Add-ons.
  3. Gear icon → Install Add-on From File…
  4. Pick the file you downloaded, then restart Zotero.

From then on Zotero checks for new versions itself and updates the plugin without being asked.

Note

zotLook installs beside Guillaume Chapron’s Zotero7QuickLook rather than over it — the two carry different plugin IDs. If you have both, disable one, or the Space key will be claimed twice.

Getting started with zotLook

Select an item and press Space. If the item is a parent rather than an attachment, zotLook picks one of its attachments — a PDF before an EPUB, and an EPUB before anything else. You can change that order. Press Space again, or Escape, to dismiss the preview.

Shift+Space previews the item’s notes instead, rendered as a page.

Ctrl+Shift+Space builds a contact sheet: every page of a PDF as a thumbnail in a scrollable grid. Clicking a page opens it in Zotero’s reader at that page. A button in each corner opens the document’s contents and its annotations, and an entry brings its page to the middle of the sheet. On a long document the sheet takes a few seconds and says so while it works.

An EPUB gets one too, where it can. A reflowable book has no pages of its own, but one published beside a print edition usually carries that edition’s pagination along with it — and where it does, zotLook cuts the book at those marks and shows it a page at a time, each tile linking back into the reader. A book carrying none says so rather than showing arbitrary slices.

If the file is stored in the cloud and not on this machine, zotLook downloads it first rather than reporting that it is missing.

How the annotations get into the preview

zotLook exports a copy of the PDF with your highlights, notes, areas and ink drawn in, and previews that copy rather than the stored file. An EPUB needs no export: zotLook reads the position Zotero stores for each annotation and marks the passage in the page it builds from the book anyway. Highlights appear in their colour, underlines as underlines.

Attachments that carry no annotations are recognised before any work starts, and an export is reused until you add or change an annotation. Once made, it costs nothing more as long as nothing changes.

If you would rather see the file as it is stored, the annotations can be kept out of the preview under Settings.

But Zotero already has a preview

It does, and zotLook does not replace it. The item pane shows the attachment with its annotations on it, and needs nothing else installed at all. For what is this? it is the right answer.

For looking at a document more closely it is only so much use, and was probably never meant to be more.

  • It shows a single thumbnail, moved through with two buttons or the arrow keys.
  • The thumbnail is no wider than the item pane, its height following the page’s proportions. There is no setting for either.
  • Nothing in it can be clicked, selected or copied — web snapshots are the exception, and there selection is switched off instead.
  • Zotero’s own preview currently (Zotero 10) handles four formats only: PDF, EPUB, web snapshot, image — video and audio are marked in the source as still to come.

zotLook sets out to complement it on exactly those points: looking at something properly without opening it.

  • Far larger — and as large as you like. The preview windows of all three systems can be dragged to any size, and what they show scales with them.
  • Independent of the item pane, which does not have to be open for it.
  • All of it at once. Ctrl+Shift+Space builds a contact sheet: a compact overview of every page of a PDF. Where a book carries a printed pagination, the same holds for an EPUB.
  • To the passage you want in a couple of moves. An EPUB preview keeps its contents and its annotations behind a button each, above the text; Zotero’s preview knows only forward and back.
  • From the overview into the reader. Opening the reader at the page you were looking at is a feature of Zotero’s preview — there for a PDF only. zotLook reproduces it in its own: a click on a page opens it in the reader, for an EPUB as well.
  • A document, not a picture. What the system’s preview program allows — selecting text, copying it, scrolling — is thereby available for Zotero attachments too.
  • Broad support for file formats: whatever the system’s preview can show, zotLook can show. Platforms describes what each system manages on its own — and that can be extended considerably.
  • One key, and gone again. Space to look, Space or Escape to dismiss. No tab is opened and none has to be closed.

So zotLook and Zotero’s own preview answer different questions — what is this? and let me actually look at it — and sit well side by side.

Where to go next

  • What it does — every shortcut and what it previews
  • Settings — shortcuts, which attachment wins, the contact sheet
  • Platforms — what each system needs and what it can show