VerseDB for WordPress is free and open source under the GPL. The code is on GitHub. The plugin has been submitted to the WordPress.org plugin directory; once it is listed, you can install it from Plugins → Add New Plugin in WordPress.
Install the VerseDB plugin ZIP and activate it, then open Settings → VerseDB in WordPress. The plugin connects one VerseDB account to your personal website.
Connect your account#
Choose Connect to VerseDB. On VerseDB, check the requesting site's address and approve the read-only connection. You return to WordPress, where the connection shows your account. Your WordPress site needs HTTPS; localhost is supported for development.
If OAuth is unavailable, open My Apps, create a personal access token with read:public and read:showcase, and paste it under Use a personal access token instead. Choose Test and save connection. Keep the token private.
The connection lets your WordPress server retrieve display data. It cannot change your VerseDB collection or account. Only the blocks you place publish data on your website.
Add a display#
Search for VerseDB in the block inserter on a page, post or block widget area. Choose a display:
| Block | Shows |
|---|---|
| Profile | Username, avatar, biography, banner and optional level, XP and contributions |
| Collection | Public copies from your collection |
| Wishlist | Comics on your wishlist |
| Pull List | Series on your pull list |
| Currently Reading | Unfinished comics from the VerseDB reader and completion percentages |
| Recently Read | Your recorded comic reads |
| Reading Goal | Your annual target and progress |
| Public Lists | Your public lists |
| List | Items from one public, published list you own; enter its list ID |
| Reading Stats Pro | Annual reading counts and streaks from the Pro service |
| Reading Calendar Pro | Daily reading counts from the Pro service |
New displays need a background refresh. After it finishes, use Refresh preview in the editor. Publish the page or post to show it to readers.
Use the block's display controls for grid or list layout, columns, cover size, spacing and item count. Profile controls include avatar size, biography, banner and statistics. Reading displays with a year setting use the current year when it is blank. Gutenberg supplies color, typography, spacing and alignment controls; the plugin inherits your theme's fonts and colors.
Collection filters include status, format, condition, graded copies, publisher and series IDs, read status, review state and search. Pro also supplies signed-copy, grade-range, grading-company, genre, creator and character filters. The Reading Stats and Reading Calendar blocks are available with VerseDB Pro; they are hidden from the block inserter for free accounts. No separate plugin subscription is needed. The plugin follows the connected account's eligibility; after a confirmed Pro lapse, Pro displays stop appearing.
Classic editors and page builders#
Use the matching shortcodes: [versedb_profile], [versedb_collection], [versedb_wishlist], [versedb_pull_list], [versedb_reading], [versedb_currently_reading], [versedb_reading_goal], [versedb_lists], [versedb_list], [versedb_reading_stats] and [versedb_reading_calendar].
For example, [versedb_collection layout="list" limit="12"] shows a list, and [versedb_list list_id="123"] selects a public list. Shortcodes share the block renderer. Add blocks in WordPress's widget editor for a sidebar or footer; the plugin has no separate legacy widget.
Privacy and refreshing#
Currently Reading shows up to 50 unfinished books from the reader's first result page. Standard comic displays show up to 100 items.
Your WordPress server caches display fields and refreshes hourly in small batches. Public page rendering uses that cache, so visitors do not wait for API requests. The connection shares your member API allowance with other apps.
Email, birth date, location, purchase prices, notes, storage locations, loans and collection value are excluded from public output and the display cache. Collection copies must be public; individual lists must be public, published and yours. Explicit covers are blurred unless you change the block's setting. In Settings → VerseDB, the Display credit sidebar toggle controls the “Powered by VerseDB” link below displays. It is off by default; turn it on and choose Save preferences if you want to show the link. An existing saved preference is preserved.
Disconnect removes credentials, cached data and scheduled refreshes from WordPress. To revoke service access too, delete the site's token in My Apps.
A block is empty or its preview has no items#
Connect your account first, then allow its display to refresh. A new block or changed filter creates a new display query. Choose Refresh now in Settings → VerseDB, allow the background job to finish, then choose Refresh preview in the editor.
Check the selected filters and item count. Collection blocks include public copies only. The List block needs a list ID, and the list must be public, published and owned by the connected member. Pro statistics, calendar and collection filters require current Pro eligibility. Recently Read shows recorded reads. Currently Reading shows unfinished books from the VerseDB reader; completed or unavailable books are excluded.
An empty public block renders no content. The editor shows a message to help you resolve an uncached or unavailable display.
Currently Reading caches up to 50 unfinished books. Each standard comic display caches up to 100 items from the first API result page. Your site can cache up to 100 distinct queries. If you need a different selection, adjust its filters rather than adding many duplicate blocks.
Check or clear the cache#
In Settings → VerseDB, the Cache status card shows when the account was last refreshed, the next scheduled refresh, and counts of up-to-date displays, displays awaiting refresh, displays not cached yet and displays with access errors. Counts cover enabled display queries; different filters can create separate cached displays. Data is stored in your WordPress database. Reload the settings page to see the latest status.
Choose Clear cache to remove cached profile and display data. Your account stays connected, preferences are preserved, and enabled displays are queued for refresh. Disabled display queries are removed. Public displays can be empty until rebuilding finishes. Clearing does not bypass API retry delays or fix expired credentials; reconnect when required.
Data is stale#
WordPress refreshes the cache hourly in small batches. WP-Cron normally runs when the site receives traffic. On a quiet site, ask your host to schedule WordPress cron regularly.
Refresh now queues work; it does not make the next visitor wait for a VerseDB request. If your member account hits an API rate limit, the plugin waits before trying again. The allowance is shared with your other apps. Avoid repeatedly reconnecting to work around it.
During a service outage, the last successful cache remains available. Check the connection status in WordPress and try again after the service recovers.
A token expired or the connection needs attention#
Choose Reconnect to VerseDB in Settings → VerseDB. Check the site address on the consent screen before approving. If you use a pasted token, create a replacement in My Apps with read:public and read:showcase, then use Test and save connection.
OAuth supplies an expiry date. A pasted token's expiry may be unknown to WordPress; check its date in My Apps. Expired or revoked credentials do not erase the last successful display cache.
If a site migration changes its WordPress salts, the saved credential may no longer decrypt. Reconnect on the migrated site. An HTTPS site is required for OAuth, apart from localhost development.
Pro displays disappeared#
The plugin checks the connected account's Pro status on successful account refreshes. If Pro expires, the yearly statistics and calendar stop rendering, and Pro collection filters disappear. Cached Pro data does not keep those displays available. Other displays and local styling controls remain available.
Contact support#
Email [email protected] with your WordPress and PHP versions, plugin version, theme, affected block and the status message shown in Settings → VerseDB. Do not send tokens, passwords or private account data.