Groove Folios releases

Create, manage, and publish beautiful digital literature directly within WordPress — ebooks, newsletters, product catalogs, portfolios, proposals, and more. Groove Folios provides custom themes, access permissions, dynamic previews, and a dedicated folio builder interface powered by the Block Editor.

A "Folio" is a general-purpose multi-page document container; the theme you pick determines whether it reads as an ebook, newsletter, portfolio, proposal, or another format.

• Plugin URI: https://groove.studioen.us/
• Author: StudioEN
• Requires: PHP 7.1+, WordPress 5.9+

Features

• Custom post types for Folios and Folio Pages, organized with a flat Collection Tags taxonomy
• A dedicated Folio editor and Add New Folio flow, with Quick Edit support from the All Folios list
• Multiple built-in themes (Folio Starter, Groove eBook, Groove Newsletter, Groove Magazine, Groove Proposal), each with cover/page/setup templates
• Folio duplication, password-protected folios, custom logo and typeface support
• Configurable Folio URL routing/permalinks
• Collects nothing: no analytics, no telemetry, no phone-home (Settings → Privacy states what the plugin does and does not send)

Requirements

• WordPress 5.9 or later
• PHP 7.1 or later

Development

Frontend assets are built with Vite and Tailwind CSS 4.

npm install
npm run dev    # watch mode
npm run build  # production build

Admin UI is scoped under body.groove and built with Tailwind utility classes and jQuery. See assets/js/groove-main.js for the shared JS entry point.

Imagery (Pexels)

Theme covers and the shared placeholder pool used by sample content are curated once, at build time from Pexels. The plugin makes no Pexels API calls when a folio is rendered or an admin page is loaded.

The photos are not in this repository or in the WordPress.org package: the Pexels licence forbids redistributing unaltered copies, which the GPL requires. Only credits.json is committed, and the JPEGs are gitignored. A site, including one running a fresh checkout, fetches its own copy from images.pexels.com when an administrator presses Download Photos on Settings → Imagery. That download needs no API key: it uses the src_url the curator records for each photo in credits.json. See Groove\Pexels\Library for where photos resolve from.

Supplying the API key

Get a free key at https://www.pexels.com/api/. It is read from the first of these that is set:

// wp-config.php
define('GROOVE_PEXELS_API_KEY', 'your-key-here');

# or, for local development
printf %s "your-key-here" > .pexels-key

Never commit the key. The plugin never prints or renders it — the settings screen and the CLI only ever show the source and a masked value such as ••••••••1234.

Running the curation script

php bin/curate-pexels.php --help          # usage
php bin/curate-pexels.php --dry-run       # resolve everything, download nothing
php bin/curate-pexels.php                 # curate every slot
php bin/curate-pexels.php --theme=groove-proposal
php bin/curate-pexels.php --covers-only
php bin/curate-pexels.php --slots=ph-workspace,ph-reading --force
php bin/curate-pexels.php --wp=/path/to/wordpress

The script bootstraps WordPress itself (locating wp-load.php automatically, or via --wp=), is safely re-runnable — existing files are skipped unless --force is passed — and exits non-zero if any slot fails. Downloaded files land in themes/<theme>/assets/images/theme-cover.jpg and assets/images/pexels/, with attribution recorded in assets/images/pexels/credits.json.

Attribution

The Pexels licence requires a prominent link to Pexels and credit to the photographer wherever an image is used. Settings → Imagery lists every curated image with its photographer, the photographer's Pexels profile, and the photo page, alongside the required "Photos provided by Pexels" link. Do not remove these.

Project Structure

Theme development

Folio themes are self-contained packages under themes/. themes/README.md is the authoritative spec — read it before writing or editing one.

php bin/check-theme-contract.php                        # every theme
php bin/check-theme-contract.php --theme=groove-ebook   # one theme
php bin/check-theme-contract.php --dir=/path/to/theme   # a package you are about to zip
php bin/check-theme-contract.php --strict               # non-zero exit on warnings, for CI

The checker reads CSS as text and tokenises PHP rather than executing it, so it runs on a bare checkout with no WordPress installed.

Lint theme PHP before it reaches a server. Themes are loaded while the plugin file is still being included, so a broken theme file can white-screen the whole site — wp-admin included, which is where you would have gone to remove it. The contract checker tokenises and will not catch a syntax error the compiler rejects, so run php -l as well, and install packaged themes through Groove → Themes rather than unzipping into wp-content/groove-themes/ by hand. themes/README.md §13 sets out exactly which failures are recoverable and which are not.

Testing

There is no PHP unit-test suite. Two things are automated:

php bin/check-theme-contract.php --strict       # theme conformance
php bin/check-theme-contract-selftest.php       # the checker's own test suite

folio-embed-regression-checklist.md documents the manual regression checklist for folio-page embed rendering (Spotify, YouTube, X/Twitter) — run it whenever folio page or theme rendering changes.

Changelog

See CHANGELOG.md for release history.

License

GPLv2 or later — see LICENSE. Third-party components are listed in readme.txt.