Zotpress

Zotero to WordPress integration — display your academic references beautifully

Quick Start (30 seconds)

# Clone and install
git clone https://github.com/hyperpolymath/zotpress.git
./zotpress/install.sh /path/to/wp-content/plugins

# Or with Make
make install WP_PLUGINS=/path/to/wp-content/plugins

Then in WordPress:

1. Activate plugin in Plugins menu

2. Add account: Zotpress → Accounts → Enter your Zotero User ID + API Key

3. Use shortcode: [zotpress limit="10"]

Demo

# See usage examples
make demo

# Test API without WordPress
php demo/test-api.php YOUR_USER_ID YOUR_API_KEY

# Or open demo/standalone.html in browser

Common Shortcodes

[zotpress limit="10"]                           # Latest 10 items
[zotpress collection="ABC123"]                  # Specific collection
[zotpress author="Smith" year="2024"]           # Filter by author/year
[zotpress tag="machine-learning"]               # Filter by tag
[zotpress style="chicago-note-bibliography"]    # Chicago style

Compatibility Matrix

Component	Supported Versions	Tested
PHP	8.1, 8.2, 8.3, 8.4
WordPress	6.0, 6.1, 6.2, 6.3, 6.4, 6.5, 6.6, 6.7+
MySQL/MariaDB	MySQL 5.7+, MariaDB 10.3+
Browser (admin)	Chrome 90+, Firefox 90+, Safari 14+, Edge 90+	Modern browsers only
Zotero API	v3 (current)

Minimum Requirements:

• PHP 8.1+ with extensions: curl, json, mbstring, xml

• WordPress 6.0+

• HTTPS enabled (for Zotero API)

---

Overview

Zotpress is a WordPress plugin that bridges the gap between Zotero, the world’s leading open-source reference management software, and WordPress publishing. It enables academics, researchers, students, and writers to display their Zotero libraries directly on WordPress sites via intuitive shortcodes and widgets.

Key Features

Feature	Description
Bibliography Display	Render formatted bibliographies from Zotero libraries, collections, or tags
In-Text Citations	Insert properly formatted in-text citations with automatic bibliography generation
Multiple Citation Styles	Support for thousands of CSL citation styles (APA, MLA, Chicago, Harvard, etc.)
Shortcode System	Flexible [zotpress] and [zotpressInText] shortcodes with extensive parameters
Collection Filtering	Display items from specific Zotero collections
Tag Filtering	Filter references by Zotero tags
Author/Year Filtering	Query by author name or publication year
Download Links	Show attached PDFs and files for download
Abstracts & Notes	Optionally display abstracts and notes from Zotero
Cover Images	Display book covers via Open Library integration
Admin Interface	WordPress admin panel for account management and settings
Widgets	Sidebar and metabox widgets for theme integration
SEO-Friendly	Server-side rendering for search engine indexing
Accessibility	ARIA labels and screen reader support

Architecture

Technology Stack

┌─────────────────────────────────────────────────────────────┐
│                        Zotpress                              │
├─────────────────────────────────────────────────────────────┤
│  Frontend Layer                                              │
│  ├── ReScript (Modern, type-safe)                           │
│  │   ├── DOM bindings & Fetch API                           │
│  │   ├── IntersectionObserver (lazy loading)                │
│  │   └── Accessibility (ARIA, screen reader)                │
│  └── CSS (Custom properties, component-based)               │
├─────────────────────────────────────────────────────────────┤
│  Backend Layer (PHP 8.1+)                                    │
│  ├── lib/admin/     → Admin interface & settings            │
│  ├── lib/request/   → Zotero API integration                │
│  ├── lib/shortcode/ → [zotpress] shortcode handlers         │
│  └── lib/widget/    → WordPress widgets                     │
├─────────────────────────────────────────────────────────────┤
│  External Services                                           │
│  ├── Zotero API (api.zotero.org)                            │
│  └── Open Library API (covers.openlibrary.org)              │
└─────────────────────────────────────────────────────────────┘

Project Structure

zotpress/
├── lib/                    # PHP backend
│   ├── admin/              # Admin interface (12 files)
│   │   ├── admin.php       # Core admin functionality
│   │   ├── admin.accounts.php
│   │   ├── admin.browse.php
│   │   ├── admin.menu.php
│   │   └── ...
│   ├── request/            # API layer (4 files)
│   │   ├── request.class.php
│   │   ├── request.cite.php
│   │   └── ...
│   ├── shortcode/          # Shortcodes (7 files)
│   │   ├── shortcode.php   # Main [zotpress] handler
│   │   ├── shortcode.intext.php
│   │   └── ...
│   └── widget/             # Widgets (3 files)
├── src/
│   ├── rescript/           # Modern frontend
│   │   ├── Zotpress.res    # Main module (~520 lines)
│   │   └── Utils.res       # Utilities
│   ├── js/                 # JavaScript fallback
│   │   └── zotpress.ts
│   └── css/                # Styles
│       ├── variables.css   # Design tokens
│       └── components.css  # Component styles
├── tests/                  # Test suites
├── scripts/                # Build scripts (Deno)
├── docs/                   # Documentation
├── .github/                # CI/CD workflows (13+)
└── [config files]          # composer.json, deno.json, etc.

Installation

Quick Install (Recommended)

git clone https://github.com/hyperpolymath/zotpress.git
cd zotpress
./install.sh /path/to/wp-content/plugins

Or with Make:

make install WP_PLUGINS=/path/to/wp-content/plugins

From WordPress Plugin Directory

1. Go to Plugins → Add New in WordPress admin
2. Search for "Zotpress"
3. Click Install Now, then Activate

Manual Installation

# Clone from any mirror
git clone https://github.com/hyperpolymath/zotpress.git
git clone https://gitlab.com/hyperpolymath/zotpress.git
git clone https://codeberg.org/hyperpolymath/zotpress.git

# Install (symlink for dev, --copy for production)
./install.sh /path/to/wp-content/plugins
./install.sh /path/to/wp-content/plugins --copy

Development Setup

# Install dependencies
composer install              # PHP tools (testing, linting)
deno cache deno.json          # JS tools (auto-cached)

# Build assets
make build                    # Or: deno task build

# Watch mode
make dev                      # Or: deno task dev

# Run tests
composer test && deno test

Usage

Basic Shortcode

Display your entire Zotero library:

[zotpress userid="123456"]

Filter by Collection

[zotpress userid="123456" collection="ABC123"]

Filter by Tags

[zotpress userid="123456" tags="machine-learning,neural-networks"]

Filter by Author and Year

[zotpress userid="123456" author="Smith" year="2023,2024"]

In-Text Citations with Bibliography

According to [zotpressInText item="ABC123"], the results show...

Another study [zotpressInText items="DEF456,GHI789"] confirmed this.

[zotpressInTextBib]

Full Shortcode Parameters

Parameter	Default	Description
userid / user_id	-	Zotero user/group ID
nickname	-	Account nickname (alternative to userid)
collection / collections	-	Collection key(s), comma-separated
item / items	-	Specific item key(s)
tag / tags	-	Filter by tag(s)
author / authors	-	Filter by author name(s)
year / years	-	Filter by year(s)
itemtype	all	Filter by item type (book, journalArticle, etc.)
style	apa	Citation style (CSL style name)
limit	50	Maximum items to display
sortby	default	Sort field (date, title, creator)
order	asc	Sort direction (asc/desc)
title	no	Show year headers
showimage	no	Display cover images (yes/openlib)
showtags	no	Display item tags
download / downloadable	no	Show download links for attachments
notes	no	Display notes
abstract / abstracts	no	Display abstracts
cite / citeable	no	Show copy citation button
target	no	Open links in new tab
highlight	-	Highlight specific items

Mirrors

This repository is mirrored across multiple forges for resilience:

Platform	URL	Status
GitHub (primary)	https://github.com/hyperpolymath/zotpress	✓ Primary
GitLab	https://gitlab.com/hyperpolymath/zotpress	✓ Mirror
Codeberg	https://codeberg.org/hyperpolymath/zotpress	✓ Mirror
Bitbucket	https://bitbucket.org/hyperpolymath/zotpress	✓ Mirror

Development

Build Commands

# Build all assets
deno task build

# Watch mode (development)
deno task dev

# Run PHP tests
composer test

# Run JavaScript tests
deno test

# Static analysis
composer analyse    # PHPStan
composer psalm      # Psalm

# Code formatting
composer format
deno fmt

Architecture Decisions

Key decisions documented in META.scm:

• ReScript over TypeScript — Type-sound, cleaner JS output, RSR policy compliance

• Deno over Node.js/npm — Secure defaults, no dependency hell

• PHP 8.1+ minimum — Modern features, better static analysis

• AGPL-3.0 licensing — Strong copyleft for network services

Contributing

See CONTRIBUTING.md for guidelines.

Key points:

• Follow language policy (ReScript, not TypeScript; Deno, not npm)

• Run tests before submitting PRs

• Add SPDX license headers to new files

• Sign commits if possible

Security

See SECURITY.md for:

• Vulnerability reporting process

• Supported versions

• Security measures

License

Licensed under AGPL-3.0-or-later with optional Palimpsest-0.5 philosophical overlay.

See LICENSE for full terms.

Citation

To cite Zotpress in academic work:

@software{zotpress_2025,
  author = {Jewell, Jonathan D.A.},
  title = {Zotpress: Zotero to WordPress Integration},
  year = {2025},
  url = {https://github.com/hyperpolymath/zotpress},
  license = {AGPL-3.0-or-later}
}

See docs/CITATIONS.adoc for more formats.

Acknowledgments

• The Zotero team for their excellent API

• WordPress community

• All contributors and users

Metadata

• Domain: Academic publishing, reference management

• Framework: RSR (Rhodium Standard Repository)

• Status: Active development (75% to v8.0 stable)

• Dublin Core: .well-known/dc.xml