Zotero Voyant Export

License & Philosophy

This project must declare MPL-2.0-or-later for platform/tooling compatibility.

Philosophy: Palimpsest. The Palimpsest-MPL (PMPL) text is provided in license/PMPL-1.0.txt, and the canonical source is the palimpsest-license repository.

Export your Zotero collections to Voyant for text analysis.

[Voyant](http://voyant-tools.org/) is "a web-based text analysis and reading environment" that lets you visualize the content of a text corpus. [Zotero](https://www.zotero.org/) is a "a free, easy-to-use tool to help you collect, organize, cite, and share your research sources." This extension helps those with preexisting Zotero collections get a new view on their data via Voyant.

Version 2.1 - Zotero 7-8 Compatible

This version has been completely rewritten for Zotero 7-8 compatibility using modern tooling based on the [zoterho-template](https://gitlab.com/extensions-library/zotero/zoterho-template) architecture:

• ReScript for type-safe code compilation to JavaScript

• Deno as the runtime environment (no npm dependencies)

• Just for task automation (optional)

• web-ext for extension development and packaging

• WebExtension Manifest v2 for Zotero 7 compatibility

Modern Best Practices

This extension implements production-grade best practices:

• Accessibility: WCAG 2.1 compliant with full keyboard navigation, ARIA labels, and screen reader support

• Error Recovery: Automatic retry logic with exponential backoff for transient failures

• Performance: Optimized for large collections with progress tracking and memory management

• Security: Strict Content Security Policy (CSP) preventing XSS and code injection

• Self-Healing: Defensive programming with graceful degradation for edge cases

• Dark Mode: Automatic theme detection via prefers-color-scheme

• High Contrast: Enhanced visibility for users with visual impairments

• Reduced Motion: Respects prefers-reduced-motion for vestibular disorders

Requirements

• Zotero 7.0 or higher (compatible with Zotero 8.0+)

• A collection containing full texts (as PDFs, HTML snapshots, etc.)

Installation

Download the latest XPI from the releases page. Then open Zotero and select Tools menu → Add-ons. Click the gear icon in the upper right and select "Install Add-On From File…​"; open the XPI file you just saved.

Usage

Right-click on the collection you wish to analyze. Select "Export Collection to Voyant…​" and choose a save location for the corpus as a zip file.

Keyboard Navigation: You can also activate the menu item via keyboard: - Navigate to the collection with arrow keys - Press Alt+V (or use Tab to focus the menu) - Press Enter or Space to activate

Upload the resulting zip to [voyant-tools.org](http://voyant-tools.org) (or to [your local Voyant server][local-voyant] — for collections larger than a handful of documents, you’ll probably want to host locally). You should then be able to see your corpus in the default Voyant view.

Performance Notes

• Small collections (<50 items): Export completes in under 1 second

• Medium collections (50-100 items): Progress logged to debug console

• Large collections (100+ items): Automatic optimizations and periodic progress updates

• Collections with missing attachments are handled gracefully with informative logging

Development

Prerequisites

This project uses a minimal, modern toolchain:

1. Deno (v1.40+): https://deno.land/ bash curl -fsSL https://deno.land/install.sh | sh

2. Just command runner (optional): https://github.com/casey/just bash # macOS/Linux curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s — --to ~/.local/bin

   Note: Just is optional. You can use `deno task` commands directly if you prefer.

Setup

# Clone the repository
git clone https://github.com/Hyperpolymath/zotero-voyant-export.git
cd zotero-voyant-export

# Build the extension
deno task rescript:build

# Or use Just if installed
just build

Build Commands

Using Deno directly:

deno task rescript:build    # Build ReScript to JavaScript
deno task ext:build         # Create XPI package

Or using Just (if installed):

just                # List all available commands
just rebuild        # Clean build from scratch
just dev            # Development mode (rebuild + watch)
just build          # Build ReScript to JavaScript
just watch          # Watch mode for development
just package        # Create XPI package for distribution
just run            # Test in Firefox
just clean          # Clean build artifacts

Project Structure

├── src/                    # ReScript source files
│   ├── background.res      # Main entry point & initialization
│   ├── Firefox.res         # Complete Firefox/XPCOM type bindings
│   ├── Zotero.res          # Type-safe Zotero API bindings
│   ├── Exporter.res        # Collection export with error recovery
│   ├── Format.res          # MODS & Dublin Core XML generation
│   ├── UI.res              # Accessible menu items & file picker
│   ├── ErrorRecovery.res   # Retry logic & self-healing utilities
│   └── Performance.res     # Performance monitoring & optimization
│
├── ui/                     # UI assets
│   ├── icon.png            # Extension icon (64x64)
│   └── styles.css          # Accessible, modern styles
│
├── manifest.json           # WebExtension manifest (committed)
├── deno.json               # Deno configuration (committed)
├── rescript.json           # ReScript compiler config (committed)
├── justfile                # Task automation (optional)
└── README.adoc             # This file

# Generated files (.gitignored):
└── src/**/*.mjs            # Compiled JavaScript from .res files

How It Works

1. ReScript Compilation: Type-safe ReScript (.res) compiles to JavaScript (.mjs)

   • Deno runs ReScript compiler via npm: imports

   • In-source build: .mjs files generated alongside .res files

   • Full type safety eliminates runtime errors

2. Extension Loading: Zotero loads the extension via manifest.json

   • background.mjs executes on startup

   • Accessible context menu added to collections

   • Export functionality triggered by user action

3. Error Recovery: All operations wrapped in retry logic

   • Exponential backoff: 1s → 2s → 4s delays

   • File validation before operations

   • Graceful degradation for missing attachments

   • Detailed error logging for debugging

4. Performance Tracking: Large collections handled efficiently

   • Progress logging every 10 items

   • Memory management for datasets >100 items

   • Duration and throughput metrics

   • Success/failure reporting

Development Workflow

# 1. Make changes to ReScript files in src/
vim src/Exporter.res

# 2. Rebuild
deno task rescript:build   # or: just build

# 3. Test in Zotero
# Install the extension by loading manifest.json in Zotero
# Tools > Developer > Load Unpacked Extension

# 4. Create production build
deno task ext:build        # or: just package

Configuration Management

All project configuration is committed directly to the repository:

• manifest.json: WebExtension manifest with CSP and permissions

• deno.json: Deno tasks for running ReScript and web-ext

• rescript.json: ReScript compiler configuration

To modify configuration: 1. Edit the JSON file directly 2. Rebuild with deno task rescript:build 3. Test the changes in Zotero

Tech Stack

• [ReScript](https://rescript-lang.org/): Type-safe language compiling to JavaScript

• [Deno](https://deno.land/): Secure runtime for JavaScript/TypeScript

• [Just](https://github.com/casey/just): Optional command runner and task automation

• [web-ext](https://github.com/mozilla/web-ext): Firefox extension development tool

Architecture Highlights

Type Safety: Only 3 unavoidable %raw() blocks in the entire codebase - All Firefox/XPCOM APIs properly typed in Firefox.res - No {..} open object types or Obj.magic unsafe casts - Full end-to-end type safety from ReScript to JavaScript

Error Recovery: Production-grade resilience - Retry with exponential backoff (3 attempts, 1s → 2s → 4s) - File validation before all operations - Directory auto-creation with validation - Graceful handling of missing attachments

Accessibility: WCAG 2.1 Level AA compliance - Full keyboard navigation (Tab, Enter, Space) - ARIA labels and roles for screen readers - High contrast mode support - Dark mode via prefers-color-scheme - Reduced motion for vestibular disorders - Alt+V shortcut key

Performance: Optimized for large datasets - Progress logging every 10 items - Memory management for >100 item collections - Duration and throughput metrics - Disk space validation

Security: Defense in depth - Strict Content Security Policy (CSP) - No external script loading - All resources self-contained - Input validation on all file operations

Credits

This project’s architecture is based on the [zoterho-template](https://gitlab.com/extensions-library/zotero/zoterho-template) by the Zotero community, which provides a production-ready framework for building modern Zotero 7 extensions.

Original extension concept and implementation by Cora Johnson-Roberson.

[local-voyant]: http://docs.voyant-tools.org/resources/run-your-own/voyant-server/

LICENSE

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.