Developer guide

Vibemap Plugin Developer Guide

A technical reference for teams building on the Vibemap WordPress plugin. It covers how Vibemap data becomes WordPress posts, what you can configure, and where you can hook in.

  • Plugin 4.4.3
  • PHP 7.4+
  • WordPress 5.0+, tested to 7.1.2
  • Single-site only
  • Composer package vibemap/vibemap-sync

How it works

The plugin copies places and events from the Vibemap platform into your WordPress database as custom posts. It then renders them with a set of Gutenberg blocks (also available as shortcodes and Elementor widgets).

Keep three things in mind:

  • Vibemap is the source of truth. Each synced post is a local copy of one Vibemap record. The sync overwrites the copy whenever the Vibemap record changes. See Editing synced content.
  • Blocks read your local posts, not the live API. Maps, grids, carousels and single pages query the plugin's own /wp-json/vibemap/v1/* routes, which read vibemap_place and vibemap_event posts. Your site keeps rendering if the Vibemap API is down, and SEO, search and caching all work on local data. The one exception is personalized recommendations (the My List block and the carousel's recommendations source), which call Vibemap live.
  • What gets synced is decided in Vibemap. In Lists mode, the plugin syncs the lists your organization curates in Vibemap. To change what appears on the site, edit the list in Vibemap.
LayerWhat it isWhere
ContentCPTs vibemap_place and vibemap_event, 8 taxonomies, about 150 registered meta keys (all exposed over REST)Data model
SyncBackground jobs on Action Scheduler that pull from api.vibemap.com/v0.3, create, update and delete posts, and handle imagesThe sync
Presentation19 dynamic blocks, backed by a React component bundle, plus page templates for single, archive and search viewsBlocks, Shortcode Reference, Templates
ConfigSite-wide defaults that flow into every block, with overrides per post type and per blockSettings cascade
IntegrationREST routes, webhooks, filters/actions, and WP-CLIREST, Hooks, CLI

What's new

This section summarizes the newest releases. Every release, with the changes you need to act on, is in the Changelog.

4.5.0 (November 17, 2026): 16 changes to review

See which cards visitors saw and where they clicked — Embeds and plugin blocks now report cards seen (item_impressions: a card counts once per page view after a second half on screen, and item_count adds up to cards seen), Load More, and Facebook, Instagram and X link clicks. Every item click says where it came from (source: a grid card, map pin, list row, carousel slide or calendar entry) and its position_in_list, so map pin clicks no longer look like card clicks. Ticket and event link clicks (event_link_clicked) now send the destination's host (outbound_host) and link type instead of the full address, which can carry personal details: if your Tag Manager reads url from that event, read outbound_host instead. The Embeds analytics guide explains how to count cards seen and ticket clicks.

Embed SEO helper for sites that use the Vibemap embed script — The helper prints your embed's events and places into your page's own HTML, as structured data and as a listing that shows in the embed's spot until the live embed loads. It also gives each event-details page its own canonical and share (Open Graph) URL under Yoast, Rank Math, All in One SEO, SEOPress or The SEO Framework, keeps the empty event-details page out of search results, and publishes a sitemap of every item page, so search engines and AI assistants that skip JavaScript can read them. It counts AI crawler visits to those pages, shown on its settings page or, with the Vibemap plugin, under Vibemap → AI Crawlers. Install it, map your calendar and event-details pages under Settings → Vibemap Embed SEO, then clear your page cache.

Form instructions and custom CSS are limited to safe formatting — The Add Event and Add Place forms now show instructions and your theme's intro message with basic formatting only: paragraphs, line breaks, bold, italic, underline, lists, headings (h3 to h6) and http, https or mailto links. Other tags are dropped and their text kept; images, frames, forms and scripts are removed. Custom CSS on the forms and the offer-update page can no longer import style sheets or load images or fonts from a URL. If your form instructions use other markup, rewrite them with these tags.

Ended events keep their page for six months, then redirect — An event that has ended no longer disappears: its page stays up with a "This event has ended" notice that links to the next date, the venue or your events page, so links and search results keep working. It leaves your event lists, search, sitemap and term counts as before. After six months the event is removed and its address redirects to the series, the venue or your events archive instead of showing "page not found". On sites that get Vibemap updates by webhook, an event taken down after it ends is removed straight away. Event lists your theme, a page builder or a widget builds (an Elementor Loop Grid, say) leave ended events out too, on the page and when a visitor loads more. To list them there, turn on Show ended events in theme and page-builder lists under Vibemap → Template Settings → Events. Developers can keep ended events in one list with 'vibemap_exclude_past' => false, and change the six months with the vibemap_past_event_retention_days filter.

Extra rows in a map's phone panel are now opt-in — On phones, the panel that slides up over the map shows one list of everything by default, and featured items no longer add a Featured row above it. To bring the Featured row back, or to add Ongoing events or Top 3 categories rows, open the map in the Hub map builder, go to On phones → Sliding panel and pick them under Extra rows.

Vibemap's styles load only where Vibemap content appears — The shared Vibemap stylesheets (about 420 KB with the map styles), the notification and dialog helpers, and with them jQuery, used to load on every page of your site. They now load only where a Vibemap block, shortcode, widget or Event/Place page appears, and the map styles only where a map can show. Analytics loading is unchanged. If your theme or custom code relies on Vibemap's styles or helpers elsewhere, add add_filter('vibemap_force_load_assets', '__return_true'); to restore the old behaviour.

Calendar files and subscribable calendars for your events, and an events RSS feed in date order — Every event page now offers an .ics file, and the events archive, each event category and each shared list can be subscribed to in Google Calendar, Apple Calendar or Outlook, with times in the venue's time zone and repeating events kept as a series. The event page's Add to Calendar menu downloads that file, so Apple Calendar and Outlook get the right time wherever the visitor is. The events RSS feed now lists upcoming events by date, each series once, with every event's date and place. If you send new-event emails from the RSS feed, turn off Settings → AI search & discovery → Events RSS feed to keep the newest-published order.

Tonight, today, this weekend and this week pages for your events — Your site now has /event/tonight/, /event/today/, /event/this-weekend/ and /event/this-week/, plus the same four under each event category and neighborhood, so people and AI assistants searching "things to do this weekend" land on your domain. Each page lists the events in that window with an intro sentence, links to every event, and its own title, description and sitemap entry; past events never show. They are on by default: turn them off or rewrite the intros in Settings → Vibemap → Date landing pages. If a full-page cache keeps pages longer than an hour, shorten it for these pages, since tonight's list changes through the evening.

Recurring events get a series page search engines can index, and each date its own listing — A recurring event's series now has its own address, such as /event-series/open-mic/, with its own title, schedule and upcoming dates in its description and structured data, under Yoast, Rank Math and other SEO plugins too, and it appears in the sitemap: WordPress's own, or Yoast's or Rank Math's events sitemap. Each date keeps its own page, now with its date in the page title, so search results tell the dates apart. Links to the old /event-series/?vibemap_id= address redirect to the new one; update menus, buttons or custom code that build that address so visitors skip the redirect.

Event and place listings arrive with their cards in the page — The Events grid, Combo, Card Carousel and Taxonomy Archive blocks now send their first page of cards in the page's HTML: each title links to its page on your site, with dates and photo, plus the category, venue and address when the cards show them. Search engines and AI assistants that don't run JavaScript can read and follow them, and visitors see real cards instead of a loading placeholder. A Combo that opens on its calendar starts with a list of upcoming events by day, and a Combo with a boundary sends only the places and events inside it, as the live map shows. Past events stay out, as they do in the live listing. The interactive listing now sits inside .vibemap-react-root, so theme CSS that reaches it with a child selector (.wp-block-vibemap-native-events > div) needs a descendant selector. A full-page cache now holds these cards too: keep its lifetime for event pages to an hour or less so search engines see current events.

AI assistants and search engines find your events and places faster — Your site now serves an llms.txt that lists your event and place archives, events on now and coming up, the Tonight and This Weekend date pages, recurring events' series pages, places, categories, Vibemap pages, feeds and sitemap. Every event and place page also has a Markdown copy at its address plus .md, and Bing and other IndexNow search engines hear within minutes when an event or place is published, changed or removed. All three are on for every site, including sites that already run the plugin once they update. To turn one off, untick it under Vibemap → Vibemap Settings → AI search & discovery. Staging sites, local sites and sites set to discourage search engines never notify IndexNow.

Event and place pages get a meta description and sharing tags — Single event and place pages now carry a description that leads with the date and venue, so search results and AI answers show when and where. With Yoast, Rank Math, SEOPress or The SEO Framework, a description you write in that plugin still wins; otherwise this one replaces the plugin's excerpt-based description and its Open Graph and Twitter descriptions, so link previews show the date and venue too. All in One SEO keeps its own unless it has none. Without an SEO plugin, the page also gets Open Graph and Twitter tags for link previews. Synced events and places get an excerpt from their description as they next sync, and an excerpt you edit is never overwritten. If your theme already prints its own description or sharing tags, turn this off under Settings → Features → Meta Description & Social Tags.

Richer search data for events and places, in the right currency — Event pages now tell search engines the full venue address, the performers, the organizer's website, the ticket link, and whether the event is postponed, rescheduled or moved online, with the event photo cropped to the three shapes Google asks for. Place pages name what the place is, such as a restaurant, bar, museum, park or hotel, and list their opening hours. Prices carry the currency of the venue's country instead of always US dollars, and a price is left out rather than shown in a currency that might be wrong. If your events are mostly outside the country your site language names, set the currency under Settings → Features → Currency for Prices.

Search engines see your site as the publisher, and what each archive lists — Event and place pages now name your site as their publisher and carry breadcrumbs (Home › Events › the page), and event and place archives list the events and places they show, so search engines and AI assistants can read them. With Yoast SEO or Rank Math this joins their structured data instead of adding a second copy. If you turned off Settings → Features → Emit Structured Data (schema.org) because Yoast or Rank Math already printed schema, you can turn it back on.

Event, place and series pages arrive with their content in the page — The title, dates, venue address, description, hero photo and a short "Event details" summary (when, where, cost, tickets) are now in the page's HTML. Search engines and AI assistants that don't run JavaScript can read them, visitors see the real page instead of a loading placeholder, and the hero photo loads first. Canceled events now say so on their page. The block's interactive layout now sits one level deeper, inside .vibemap-react-root: if your theme styles it with a child selector such as .wp-block-vibemap-single-event > div, switch to a descendant selector.

Dates, addresses and card titles are marked up for search engines — Event dates and times on cards, detail pages, the calendar and offers now carry machine-readable dates with the venue's time zone, venue and place addresses are marked as addresses, and card titles are third-level headings (they were fourth-level), so each page keeps a single main heading. Nothing looks different. If your site's custom CSS styles card titles through an h4 selector, change it to .sing-card .title.

  • Day of the week on date badges
  • See whether AI crawlers can reach your site
  • The Add Event form shows up sooner
  • Load More counted in the map view's list
  • Map and list cards are real links search engines can follow
  • Card photos download once, and off-screen ones wait
  • Past events no longer crowd the Vibemap Events screen
  • The first cards' photos and the detail-page photo load first
  • Map detail panels mark their dates and addresses
  • A lighter analytics script on every page
  • Lists that hide ongoing events load faster on large sites
  • Search, shared-list and My List pages stay out of search results
  • Event cards show your theme's colours from the first paint
  • Pages with several Vibemap blocks load less JavaScript
  • Event dates, venue addresses and the main photo are marked up for search engines
  • Text shows while a map theme's font loads
  • Maps show in the block editor on WordPress 7.1
  • Event lists no longer wait on Vibemap for venue details
  • The block editor's event picker works on sites with thousands of events
  • Changing an event's venue now sticks
  • Add to Calendar saves the right time wherever the visitor is
  • Names with apostrophes and ampersands read correctly everywhere on a card
  • Add Event Form honors its submit-button position and dialog setting
  • Add Place form sends tags, vibes and categories intact
  • An expired event Edit link explains itself instead of opening a blank form
  • The suggested end time sticks, and imported venues match more reliably
  • All-day events stay on their own day for every visitor
  • An event with no end time keeps a blank end
  • Events with no end time show only their start
  • A map that fails to draw shows a proper retry panel
  • Every listing without a photo shows the same artwork
  • Calendar-first Combos go straight from the event list to the month grid
  • Back returns to the card you opened in a Combo's grid
  • Event cards show times in the event's time zone
  • Event grids and carousels no longer jump when the live version takes over
  • Events without a photo no longer get a gradient as their featured image
  • Search results page no longer lists every filter pill
  • The map's filter panel scrolls on phones
  • The submission limit message gives the right wait
  • The Taxonomy Archive block honours "Items shown initially"
  • Vibemap no longer loads Google Fonts on every page
  • Phone-width grids, maps and carousels open on their phone layout
  • Venue checks read street names like Stevens Creek correctly
  • Analytics keep links to the page, not their query strings
  • Descriptions can no longer run scripts

Full 4.5.0 notes

4.4.5 (November 5, 2026): nothing to act on
  • Places syncs no longer lose their first page on WP Engine

Full 4.4.5 notes

4.4.4 (November 5, 2026): 1 change to review

Events with no end date stay on the calendar — When Vibemap sent an event without an end date, as it does for open-ended series, the sync blanked vibemap_event_end_date and every events query then hid the event. The sync now fills in an end (a series' last listed or next occurrence, otherwise start plus 3 hours; 23:59 that day for all-day and "times vary" events), records it in _vibemap_event_end_date_filled, and never sends it back to Vibemap through write-back. Events blanked by earlier versions are repaired on the next sync.

  • Events can say "Times vary" instead of a start time
  • My List works fully with analytics off, for editors and on staging
  • "Only show passed-in taxonomies" works on Places and Combo blocks
  • Syncs no longer skip their first page on hosts with a persistent object cache
  • Single event pages show the right dates in the When card

Full 4.4.4 notes

Install & updates

Requirements

  • PHP 7.4 or later. The plugin bundles its PHP dependencies in vendor/, so you don't need to run composer install inside the plugin folder.
  • WordPress 5.0 or later, tested up to 7.1.2.
  • Single site only. On multisite, activate, configure and uninstall the plugin separately on each site. A network uninstall leaves scheduled jobs and keys behind on the other sites.
  • Action Scheduler ships in the plugin. If another plugin such as WooCommerce already loads Action Scheduler, the Vibemap plugin reuses that copy.
  • Hosts that kill long-running loopback requests (WP Engine and similar): run syncs with WP-CLI from system cron.

Option A: zip upload

Upload vibemap-<version>.zip under Plugins → Add New → Upload. The zip's top-level folder is vibemap-plugin/. Release zips are built only from stable tags, and development dependencies are removed.

Option B: built-in auto-updater

Once installed, the plugin updates itself through WordPress's normal update screens. It does not come from wordpress.org.

  • Update feed: https://vibemap.sfo3.digitaloceanspaces.com/plugin/vibemap-update.json. The plugin caches the feed for 8 hours, and caches a failed fetch for 15 minutes.
  • Check now: click the Check for Updates link on the plugin's row in Plugins. It clears the cache and checks immediately.
  • Background updates: the WordPress "Enable auto-updates" toggle works, and so does wp plugin update.
  • Any folder name: the updater keeps whatever folder name the plugin is installed under, so a Composer install in vibemap-sync/ stays active after an update.
  • Pre-release builds never appear in the feed. Vibemap shares those as separate zips for testing.

Option C: Composer (Private Packagist)

If you manage WordPress with Composer (for example Bedrock), require the plugin from Vibemap's Private Packagist repository. The package is vibemap/vibemap-sync, type wordpress-plugin. Stable versions come from release tags, so constraints like ^4.2 work as usual.

{
  "repositories": [
    {
      "type": "composer",
      "url": "https://repo.packagist.com/vibemap/",
      "only": ["vibemap/vibemap-sync"]
    }
  ],
  "require": {
    "composer/installers": "^2.0",
    "vibemap/vibemap-sync": "^4.2"
  },
  "extra": {
    "installer-paths": {
      "wp-content/plugins/{$name}/": ["type:wordpress-plugin"]
    }
  },
  "config": {
    "allow-plugins": { "composer/installers": true }
  }
}

Private Packagist needs credentials. Ask Vibemap for a token, then store it in your Composer auth rather than in composer.json:

composer config --global --auth http-basic.repo.packagist.com token <YOUR_TOKEN>
  • With the installer-paths above, the plugin installs to wp-content/plugins/vibemap-sync/. On Bedrock, use your usual web/app/plugins/{$name}/ path.
  • The plugin registers Action Scheduler inside its own vendor/ directory, so your project does not need a separate Action Scheduler install.
  • You can keep Composer and the auto-updater together. If you would rather Composer be the only thing that changes plugin code, turn off auto-updates for the plugin in WordPress.

On activation

  • Place and event sync are turned on. If you had turned either one off before, that choice is kept.
  • The sync mode is set to Lists on a new install, or Legacy if an API key is already stored.
  • The first sync is scheduled for 03:00 site time.
  • Rewrite rules are flushed on the next request.

Connecting & configuration

Connect your organization (Lists mode)

Lists is the recommended mode for all new installs. The site is tied to one Vibemap organization and syncs lists that organization curates.

  1. Enter the organization slug

    Go to Vibemap → Vibemap Settings → Organization & Lists, enter the slug (for example yerba-buena), and click Fetch Organization.

  2. The plugin pulls your org profile

    It stores the organization's lists, its theme (brand colors and fonts), and its boundary (center point and polygon). Changing to a different organization resets which lists are selected.

  3. Choose lists

    Tick the place lists and event lists to sync. Every list must load, and each must be the right type, or the whole sync stops before writing anything.

  4. Optional: events-only sites

    Turn on Events only and the places sync imports only the venues of your selected event lists instead of place lists.

  5. Save, then sync

    Run the first sync from Vibemap → Dashboard or with wp vibemap sync all. After that, a daily job at 02:00 refreshes the organization's list catalog. The boundary and theme are only refreshed when you click Fetch Organization again.

Lists mode doesn't need an API key to read data. You only need a key for write-back and notification emails (see constants below).

Legacy mode

Legacy mode builds its own query instead of using curated lists. It takes a location slug (the boundary comes from Vibemap), a radius or boundary search, and a taxonomy filter (editorial category with * wildcards, category, vibes or tags). It also supports an optional secondary query that syncs a second set of items in the same run. The Category, Vibes and Tags filters each take one term already synced into the site. A Category filter goes to Vibemap as the category's unique slug; if it matches no Vibemap category, or several, that sync stops and an admin notice names it until you pick a category in Vibemap Settings. Legacy mode requires an API key. It is kept for existing installs; use Lists mode for new builds.

wp-config constants

ConstantDefaultEffect
VIBEMAP_API_KEYPlugin defaultYour Vibemap API key, sent as Authorization: Api-Key …. Vibemap supplies it. Needed for Legacy mode, write-back and notification emails. Set it in wp-config.php, because the settings screen has no field for the key.
VIBEMAP_EMAIL_API_KEY''Optional separate key used only for Add Event Form notification emails, so it can be revoked on its own. If unset, the main key is used.
VIBEMAP_RECAPTCHA_SITE_KEY''reCAPTCHA v3 site key for the Add Event Form, supplied by Vibemap. Empty loads no reCAPTCHA script. The vibemap_recaptcha_site_key filter overrides it.
VIBEMAP_DISABLE_API_CACHEunsetTruthy turns off the REST response cache. WP_DEBUG does not turn it off. See Caching.
VIBEMAP_TRUST_PROXYunsetTruthy makes email rate limiting use CF-Connecting-IP, X-Real-IP or X-Forwarded-For instead of REMOTE_ADDR. Set it behind a CDN or load balancer.
VIBEMAP_SYNC_PROBEunsetTruthy turns on verbose sync diagnostics, written to wp-content/uploads/vibemap-sync-probe.log. Only use it while debugging.
VIBEMAP_SENTRY_DSNunsetSentry DSN for the plugin's error reports. The plugin ships with none, so nothing is sent until one is set. '' turns reporting off. See Error reports.
EMPTY_TRASH_DAYS (core)30Must not be 0. With the trash disabled, cleanup, closed-place removal and webhook deletes refuse to run, because a removal would be permanent. See Removal.

Admin screens

ScreenWhat's there
Dashboard ?page=vibemapPlace and event totals, sync health, a card per sync type (Sync now, force, resume, cancel), a "Run pending tasks" button for Action Scheduler, and Sync History: the last 10 syncs plus single-item webhook syncs.
Vibemap Settings ?page=vibemap-settingsSync mode, organization and lists, theme, sync on/off, interval, write-back, prevent removal, page size, Appearance (global map style, placeholder images), URL slugs, Features, Featured Images, Performance, and Webhook key.
Template Settings ?page=vibemap-templatesTabs for Events, Places, Archives and Global. These set what single pages and archives show, and the site-wide block defaults. See Settings cascade.
Maintenance Tools ?page=vibemap-maintenanceMedia overview, image review, orphan cleanup, and a Data Management tab with Clear API cache, Dedupe events, Repair venues, Backfill coordinates, Featured URL migration, and the destructive Clear all events / places, which keep posts authored in WordPress.
Sync ResultsLog for a single sync, reached from "View Results" in the Dashboard history.
AI Crawlers ?page=vibemap-ai-crawlers"Can AI crawlers reach this site?": robots.txt and firewall checks for each AI crawler, and their visits to Vibemap pages over the last 30 days. See AI crawler access.

Every Vibemap admin screen requires the manage_options capability.

Key site-wide options

You can read all of these with get_option(), and most of them through the core /wp/v2/settings REST route.

OptionDefaultEffect
vibemap_sync_modelistslists or legacy
vibemap_organization_slug—The connected organization
vibemap_selected_{places|events}_lists[]JSON array of list UUIDs
vibemap_enable_{places|events}_synconTurns the scheduled sync for that type on or off
vibemap_{places|events}_sync_interval24Hours between syncs: 1, 2, 3, 4, 6, 8, 12, 24 or 48
vibemap_enable_{place|event}_api_writeoffSend WordPress edits back to Vibemap. See Write-back.
vibemap_{places|events}_prevent_removaloffKeep posts that are no longer in the feed
vibemap_{places|events}_per_pageAPI defaultItems per sync page. Lists mode defaults to 50; Legacy events default to 500.
vibemap_{places|events}_single_slugplace / eventPermalink base for the post type. After changing it, re-save Settings → Permalinks. If another plugin already owns the slug, the plugin uses vm-place / vm-event instead, flushes rewrites and notes it in Settings.
vibemap_{events|places}_featured_modefeatured_urlfeatured_url serves images from the ImageKit CDN; sideload downloads them into the Media Library. See Images.
vibemap_emit_schemaonOutput JSON-LD on event and place pages and their archives. With Yoast SEO or Rank Math it joins their graph. Turn it off only if another plugin already outputs Event or LocalBusiness schema. See Schema & SEO.
vibemap_emit_meta_tagsonMeta Description & Social Tags. A meta description on single pages, and Open Graph tags when no SEO plugin is active. See Schema & SEO.
vibemap_currency''Currency for Prices. The currency event prices in JSON-LD are in when the event itself doesn't say: an ISO 4217 code such as CAD, or empty to follow the site language (en_GB → GBP). See Schema & SEO.
vibemap_enable_llms_txtonServe /llms.txt. See AI search & discovery.
vibemap_enable_markdown_alternatesonOffer a Markdown copy of each event and place page
vibemap_enable_indexnowonNotify IndexNow search engines when events and places are published, changed or removed
vibemap_enable_ics_feedsonServe iCalendar (.ics) files for events, the events archive, event terms and shared lists. See Calendar and event feeds.
vibemap_enable_event_rssonList upcoming events in the events RSS and Atom feeds by date, one per series, with ev: dates and places. Off, the feeds list events newest-published first, as core does.
vibemap_enable_analyticsonLoad Vibemap's usage analytics. See Analytics.
vibemap_enable_search_overrideoffRedirect /?s= to /vibemap-search/
vibemap_enable_bookmarksoffTurn on the legacy "My List" bookmarks (label, icon and color are also options)
vibemap_hide_taxonomies_by_defaultoffHide newly created terms from the frontend
vibemap_enable_remember_map_stateoffRestore map position, scroll and selection when a visitor comes back
vibemap_parallel_page_loadingoffBlocks fetch the remaining result pages in parallel. Concurrency is set by vibemap_parallel_page_concurrency (1–8, default 4).
vibemap_wp_internal_api_per_page_limit100Maximum page size for the plugin's own REST routes (up to 500)
vibemap_webhook_api_key—Turns webhooks on when set. Never exposed over REST. See Webhooks.
vibemap_enable_audit_logonKeep an append-only log of every write to a Vibemap post
vibemap_enable_error_reportingonSend Error Reports. Lets the plugin report its own errors once a DSN is set. See Error reports.

The sync

A sync is a chain of background jobs on Action Scheduler (group vibemap-sync). Places and events sync independently. Only one sync of each type can run at a time; starting a second one fails with "already in progress".

What starts a sync

  • Schedule: every vibemap_{type}_sync_interval hours, with the first run at 03:00 site time. The schedule is only active while that type's sync is turned on. The plugin re-registers missing schedules (at most once an hour) and reschedules when you change settings.
  • Dashboard: Sync now. Tick Force to rewrite every item even if it hasn't changed.
  • WP-CLI: wp vibemap sync events|places|all. It runs in the CLI process, so a web request timeout can't interrupt it. See WP-CLI.
  • Webhook: POST …/webhook/trigger-sync starts a full sync, or syncs one item against your lists when you pass id; …/webhook/sync-item refreshes one item. See Webhooks.
  • Editor: saving a recurring event in the editor queues a full event sync about 60 seconds later. Repeated saves within 30 seconds only queue one sync.

The pipeline

  1. Fetch

    In Lists mode, the plugin loads each selected list (GET /lists/{id}/) and runs that list's saved search. In Legacy mode it queries /search/events/ (future events only, from today in site time) and /places/ using your location and taxonomy filters.

  2. Process one page per job

    Each page runs as its own Action Scheduler job, about 5 seconds apart. Each item is matched to an existing post or created as a new one. Then its title, content, meta and terms are written and its images are queued.

  3. Advance

    The chain moves to the next page, then the next list, then the secondary query (Legacy mode only).

  4. Cleanup

    Only after every page has loaded: synced posts that were not in this run's feed are moved to the trash. This step has safety gates (see Removal). It runs in resumable batches of 250 posts or 25 seconds, whichever comes first.

  5. Dedupe (events only)

    Duplicate occurrence posts are merged, and the extra copies go to the trash.

  6. Record

    Totals are recorded (added, updated, removed, skipped, errors), along with a log file and a history entry.

Resilience

  • Retries: temporary API errors (5xx, 429, timeouts, connection resets, malformed responses) are retried 3 times, after 10, 30 and 90 seconds. A 2xx response that isn't valid JSON counts as an error. The sync never treats it as "zero results", so it can't wipe your posts.
  • Crashes: if a batch dies from a PHP fatal, running out of memory or being killed, it is requeued up to 3 times. A watchdog checks every 5 minutes and restarts a stalled chain. After that the sync is marked failed, keeps its progress, and can be resumed from the Dashboard.
  • Stale locks: the sync lock is only cleared when it is more than 6 hours old and no Action Scheduler jobs are pending or running.
  • Item errors: a failure on one item is counted and logged, and the sync moves on to the next item.

How an API item is matched to a post

TypeIdentityNotes
Placevibemap_place_id = API UUIDIf a place is renamed in Vibemap (new slug, same ID), the post's slug is updated to match.
Eventvibemap_event_slug = API slugEvery occurrence of a series shares the same API id, so the slug identifies a single occurrence. Matching tries the post slug, then the slug meta, then the ID plus start minute. If nothing matches, the event is treated as rescheduled: same ID, same calendar day and same slug stem, with only the time changed. In that case the existing post is updated rather than duplicated.

Only posts that are published, pending, draft, private or scheduled are matched. A post you trash stays removed: it is marked _vibemap_sync_suppressed, the sync doesn't re-create its item while the post is in the Trash, and WordPress's scheduled trash emptying skips it. Restore the post to resume syncing. A post that cleanup trashed is restored and relinked if its item comes back into the feed.

What gets written

  • name → post_title, description → post_content, slug → post_name. post_modified is set to the API's updated_at, and the post author is set to 0.
  • Status. Events and places follow the Hub's moderation state: Approved is publish (shown), Pending is pending (hidden until someone approves or disapproves it), and a Disapproved item is removed (trashed) on the next sync, unless the post was authored in WordPress; if EMPTY_TRASH_DAYS is 0 it becomes a draft instead. The status is set again on every update; a post whose item hasn't changed in Vibemap keeps its status until a Force sync.
  • All API properties become meta. Each property is stored as vibemap_{event|place}_<key>. Arrays are joined into comma-separated strings, except hours, links and updates, which are stored as JSON. A property sent as null clears its meta. A property missing from the response leaves the existing meta alone.
  • Terms. Categories, vibes, tags and neighborhoods are written to their taxonomies. Categories are matched by Vibemap's unique slug and keep their parent/child structure. An empty list in the API clears the terms. If a category fails to resolve, the existing terms are kept.
  • Venue. An event is linked to a local place post (vibemap_event_venue_post_id) only when the place ID and slug both match. Otherwise the event stores a copy of the venue's name, address and coordinates.
  • Skipped items. Items without an ID or slug, and events without a start date, are skipped. A place marked closed in Vibemap is trashed, unless it was authored in WordPress or EMPTY_TRASH_DAYS is 0.

Recurring events

Vibemap sends a recurring or ongoing event as one item per occurrence. Each occurrence has its own start date and a slug with a date suffix (stem_YYYY-MM-DD-HH-mm), and each becomes one WordPress post. The plugin does not expand RRULEs during the sync. It stores the rule in vibemap_event_recurrence and the dates in vibemap_event_recurrence_occurrences for display.

Changes to a single occurrence (a different title, time, or a cancellation) arrive as instance overrides, stored in vibemap_event_instance_*, vibemap_event_has_instance_override and vibemap_event_is_canceled. A cancelled occurrence stays as a post and is flagged as cancelled; it is not deleted. In block lists, occurrences in a back-to-back run are collapsed into one card unless you turn collapseConsecutiveRuns off.

Dedupe runs after each event sync. It groups posts first by ID plus start minute, then by ID plus date plus slug stem (to catch reschedules). It keeps one post per group, preferring the post with slug meta, then published over unpublished, then the most recently updated. The other posts go to the trash, and their list memberships move to the post that was kept. When dedupe runs on its own, it stops if it would trash more than 35% of events, and it never trashes drafts or private posts.

Removal & safety gates

Cleanup moves posts to the trash

A synced post that doesn't appear in a completed run's feed is moved to the trash. Only posts that have a Vibemap ID are candidates, and cleanup never removes Pending posts or posts authored in WordPress. An event leaves listings 90 minutes after it ends (see pastEventWindowMinutes) but stays published for six months, marked as ended; then cleanup trashes it and its address redirects (see Past events).

Cleanup runs only when all of these are true:

  • The trash is on: EMPTY_TRASH_DAYS isn't 0. Otherwise every removal would be permanent, so cleanup skips the run and an admin notice says how to fix it.
  • Every page of every list loaded, and at least one item was processed.
  • The number of items processed is within tolerance of the number the API reported: the larger of 2 items or 0.5%. You can change it with the filter vibemap_completeness_tolerance.
  • Prevent removal is off for that type.
  • Deletion cap: if a run would delete at least 10 posts and more than 10% of that type (past events and dropped dates of live series not counted), cleanup stops and waits for an admin. A notice on every admin screen links to the posts it would remove, and the Dashboard offers Run cleanup anyway (removes up to N) and Discard sync results. The filters vibemap_deletion_cap_min and vibemap_deletion_cap_ratio change the thresholds.
  • Occurrence ceiling (events): if a run would trash more than 250 dropped dates of series still in the feed, cleanup stops the same way. Change it with vibemap_churn_removal_max.

Before trashing an event whose whole series left the feed, cleanup asks Vibemap (GET /events/{id}/) and removes it only if Vibemap reports it disapproved or gone. It checks up to 100 events or 20 seconds per run and keeps the rest until the next run. An ended event still inside its six months is kept without asking, so that budget goes to current events. The per-save webhook does ask: when it finds an ended event in no feed, it calls GET /events/{id}/ once and trashes the event if Vibemap reports it disapproved or gone, so a takedown after the event ends does not stay up for six months.

Other removals: places closed in Vibemap, webhook delete calls and dedupe losers all go to the trash, so they can be restored. If EMPTY_TRASH_DAYS is 0, closed places and webhook deletes are refused instead.

Past events

An ended event keeps its page, so links and search results that point at it keep working. Its end date (or its start date when it has no end) decides.

  • Listings: it leaves every list once the site's past-events window passes (90 minutes unless pastEventWindowMinutes or pastEventCutoffDateTime says otherwise): the blocks, the public read routes, /wp/v2/vibemap_event, the events archive and its feed, taxonomy archives, search, Query Loop blocks, previous/next links and term counts. A block whose past-events window is wider still shows what that window allows.
  • Theme and page-builder lists: an event list your theme, a page builder or a widget builds leaves it out too: a WP_Query or get_posts() in a template, Elementor's Posts and Loop Grid, a Bricks, Divi or Beaver Builder query loop. Its "load more" pages agree with the first. Show ended events in theme and page-builder lists under Vibemap → Template Settings → Events → Past Events (off by default) lists them again.
  • Its page: stays published and answers 200 with a "This event has ended" notice linking to the next date, the venue or the events archive. The notice is an aside.vibemap-event-ended-notice before the event block, the body gets the class vibemap-event-ended, and the JSON-LD keeps the event's dates but drops the offer.
  • Sitemaps: ended events leave the core, Yoast and Rank Math sitemaps. A sitemap lists pages worth a fresh crawl; an ended page stays indexable for the visitors and links it already has.
  • Vibemap Events screen: always opens on Upcoming, in its usual start-date order. Past (newest first) and Any date sit next to the status links, and the status counts (All, Approved, Pending, Disapproved) count only the view's dates, so each number is the rows its link lists; the trash keeps its full count, and Mine shows none outside Any date. Counts are cached for five minutes and refreshed whenever an event is saved, trashed, deleted or re-dated. A pick lasts while you page, filter or search, never past the next visit (?vibemap_when=past or all links straight to one). A search from Upcoming, the trash and the sync-review lists show every date; a search from Past or Any date stays there.
  • After six months: sync cleanup trashes it. Its address then redirects with a 301 to the series page when the series has an upcoming date, else to the venue, else to the events archive. With no archive it answers 404. Redirects last a year, kept in a small capped store, and restoring the post from the trash removes its redirect.

Change the six months with vibemap_past_event_retention_days (0 removes ended events as soon as they leave the past-events window, the old behavior).

The theme-list rule applies to a query that can return events (a post_type of vibemap_event or any, or a search or event-taxonomy query with no post_type) and lists published posts while a page renders for a visitor: a front-end page, that page's AJAX or REST requests (their referer, or the _wp_http_referer field wp_nonce_field() adds, is a page on the site), block previews in the editor (/wp/v2/block-renderer) and Elementor's editor widget renders. It leaves alone wp-admin, WP-CLI, cron, XML-RPC, Vibemap's own REST routes, queries that name their posts (p, name, pagename, page_id, title, post__in, post_name__in), previews, and queries for drafts, the trash or any status. Such a list leaves out ended events. Each ended event carries the internal vibemap_event_state term, and lists exclude them with one short, index-only subquery, so the query stays small and fast however many events have ended. Until the one-time background backfill after the update finishes, up to 1,000 ended ids go in as post__not_in and larger sites use an equivalent SQL condition. The filter vibemap_past_event_marker turns the marker off. Pages that list no events run no extra query.

Per query, 'vibemap_exclude_past' => false keeps ended events in, and true (or a Y-m-d\TH:i:s floor) drops them where the rule would not, whatever the setting. Both work with WP_Query and get_posts(). A query that sets neither goes to the vibemap_exclude_past_events filter. The rule cannot see two kinds of request; pass true there: a REST or AJAX request with no referer from a page on the site (a server-to-server call, a browser that strips the Referer header), and an editor preview that renders through wp-admin AJAX other than Elementor's.

Images

The featured image is the Vibemap image marked is_featured, or the first image if none is marked. The remaining images are stored as a JSON list in vibemap_{type}_images. How the featured image is stored depends on the mode:

ModeHow it works
featured_url (default)Nothing is downloaded. The ImageKit URL and its metadata (width, height, blurhash, focal point, alt) are stored in _vibemap_featured_* meta. A file-less "virtual" attachment is set as _thumbnail_id. Core functions such as the_post_thumbnail() and wp_get_attachment_image_src() return CDN URLs with a srcset, and so do Yoast, Rank Math and The SEO Framework og:image. Sizes are resized by ImageKit on the fly. The srcset widths come from vibemap_featured_srcset_widths.
sideloadThe image is downloaded into the Media Library, with duplicates detected by blurhash, then source URL. You can force this mode for a single post with the meta box (_vibemap_featured_use_sideload). Images from hosts other than ImageKit always use this mode.
The sync replaces featured images

When Vibemap has an image for an item, the sync puts it back, even over one you uploaded in WordPress. To change an image for good, change it in Vibemap.

To switch an existing site between modes, use Maintenance Tools → Data Management or wp vibemap featured-url migrate. The REST field vibemap_featured_image returns {url,width,height,alt,focal,blurhash,sizes,srcset} in either mode.

Seeing what happened

WhereWhat
Dashboard → Sync HistoryThe last 10 syncs with totals, including runs whose cleanup was blocked or skipped, plus single-item webhook syncs (option vibemap_item_sync_history, newest 50) with the reason when nothing changed. Removed is split into past events, stale occurrences and items gone upstream. Click through to the per-item log in Sync Results.
uploads/vibemap_sync_logs/One log file per sync plus a separate image log, blocked from web access and trimmed to about 60 MB. Files from the old wp-content/vibemap_sync_logs/ are moved here once. If uploads isn't writable, no log files are kept and Sync Results says so. The vibemap_log_basedir filter changes the base folder.
uploads/vibemap_audit_logs/audit-YYYY-MM.jsonlAppend-only record of every create, update, trash, untrash and delete on a Vibemap post, with who did it and how (sync, cli, cron, editor or admin). Kept for 12 months. Content is stored as a length and hash, not the text. Controlled by vibemap_enable_audit_log and the filter vibemap_audit_log_enabled.
Post metavibemap_api_sync_status, vibemap_api_sync_time and vibemap_api_sync_error on each post. The status is synced, success or error, or an outcome: submitted_for_review, approval_rejected, exists_unlinked, match_pending, series_repull_failed, suppressed_locally, unapproved, unapprove_ignored or unapprove_failed. The editor sidebar shows each as a plain label.
Tools → Scheduled ActionsAction Scheduler's own screen. Filter by the vibemap-sync group.

Editing synced content

Every post in the Vibemap post types is either synced (created by the sync) or local (created by a person). The plugin records this in _vibemap_origin.

Synced posts are overwritten

Edits to synced posts last only until the next upstream change

The sync only updates a post when the item's updated_at in Vibemap is newer than the copy's. When it does update, it overwrites the title, content, slug, status, every meta field in the payload, and the terms. Edits you made in WordPress survive only until the item changes in Vibemap, or until someone runs a Force sync.

Make content changes in Vibemap, or turn on write-back so WordPress edits are sent there.

The sync also writes a plain-text excerpt from the description, up to 500 characters, which SEO plugins use as the summary. The excerpt is the exception to the rule above: once you edit it, the sync leaves it alone. It compares the excerpt with what it last wrote, kept in _vibemap_synced_excerpt. Cards use only an excerpt you wrote: the plugin's REST routes send excerpt empty while it is still the sync's copy, so cards keep the description's formatting.

To add site-only data to a synced post, store it in your own meta keys (anything outside the vibemap_ and _vibemap_ prefixes). The sync never touches those.

Local posts are protected

Posts created in the editor are marked local. The sync never overwrites a local post, and cleanup never removes one. If a Vibemap item collides with one (for example, the same slug), the sync skips it and flags the post as Sync blocked. The flag shows as a post state in the list, as an admin notice with a count, and in the editor sidebar. From the sidebar an editor can:

  • Keep WordPress: link the post to the Vibemap item and send the WordPress version to Vibemap.
  • Link only: connect the two without copying either way.
  • Keep Vibemap: replace the post with the Vibemap version, which turns it into a synced post.
  • Unlink: keep the post local and stop the warnings. This removes its Vibemap ID and marks it as opted out.

The same actions are available as REST routes under /vibemap/v1/link/*; see REST. The action vibemap_sync_block_changed fires whenever a block is recorded or cleared.

Once a local post gets a Vibemap ID (for example after Keep WordPress or Link only), cleanup treats it like any other synced post. If the item later drops out of the feed, the post is moved to the trash.

Write-back (WordPress → Vibemap)

Write-back is off by default. Turn it on for each type with vibemap_enable_{place|event}_api_write (labelled Send changes back to Vibemap). When it's on:

  • Saving or publishing a post sends it to the Vibemap API. Write-back requires an API key.
  • Place categories are sent as slugs. A field that was blank at the last pull and is still blank isn't sent, so write-back can't blank fields you never had. After an upgrade to 4.2.1, the first push for each existing place sends only fields that have a value.
  • Status maps to is_approved: Approved sends true, Pending sends null, Disapproved sends false.
  • Trashing a place or a one-off event yourself disapproves it in Vibemap (is_approved=false). Trashing one date of a recurring event removes only that date from your site and sends nothing, unless the post's _vibemap_trash_scope is series. Removals made by the sync are not sent back. Restoring a post from the trash syncs the status again.
  • A new place that matches an existing Vibemap place isn't created twice. The editor opens Is this the same place?: link it, choosing per field whether your value or Vibemap's wins, or create a separate place.
  • Writes made by the sync itself are never sent back. You can detect them in your own code with VibeMap_Sync::is_api_sync_active().

Data model

Post types

Post typePermalinkArchiveSupports
vibemap_place/place/{slug} (option vibemap_places_single_slug; /vm-place/ if another plugin owns place)On unless vibemap_enable_places_archive is offtitle, editor, excerpt, thumbnail, custom-fields, revisions
vibemap_event/event/{slug} (option vibemap_events_single_slug; /vm-event/ if another plugin owns event)On unless vibemap_enable_events_archive is offsame

Both post types are show_in_rest and always open in the block editor. The plugin ships no template for the post-type archive pages (/place/, /event/), so your theme's archive template renders them. In the event and place admin screens, Published reads Approved, Draft reads Disapproved (the Drafts filter reads Disapproved / Draft), and Pending stays Pending. Row and bulk actions offer Approve, Set to Pending and Disapprove.

Turning single pages off. You can turn off single pages per post type (vibemap_enable_{places|events}_single) and all taxonomy archives (vibemap_enable_taxonomy_archives). When a page type is off, its URLs return 404, its links come back empty on the frontend, it is removed from core sitemaps and site search, and cards stop linking to single pages. Use this for sites where the map is the whole experience.

Taxonomies

TaxonomyPost typeHierarchicalRewrite
vibemap_place_categoryplaceyesplace-category
vibemap_event_categoryeventyesevent-category
vibemap_place_vibesplacenoplace-vibe
vibemap_event_vibeseventnoevent-vibe
vibemap_place_tagsplacenoplace-tag
vibemap_event_tagseventnoevent-tag
vibemap_place_neighborhoodplacenoneighborhood
vibemap_event_neighborhoodeventnoevent-neighborhood

Taxonomy archives are public only when both the post type's archive and the global taxonomy-archives option are on. Otherwise the taxonomy has no rewrite rules.

Term meta (all taxonomies, in REST): color, text_color, icon, display_name, order (higher numbers sort first), vibemap_tag_type, hide_from_frontend. New event tags whose Vibemap type isn't event_category are created with hide_from_frontend on. The sync never changes that flag on terms that already exist, so your choices stick. To change it in bulk, use the Hide from frontend / Show on frontend bulk actions on any Vibemap taxonomy screen.

Post meta

All meta is registered with show_in_rest. Array and object values are stored as JSON strings. The keys below are the ones you are most likely to use; any other property Vibemap sends also appears as vibemap_{type}_<property>.

Place meta vibemap_place_*
KeyContents
vibemap_place_idVibemap UUID (identity)
_latitude, _longitudeCoordinates
_address, _city, _neighborhoodLocation text
_telephone, _url, _priceContact and price
_opening_hours (JSON), _display_hours, _is_open_24hrsHours
_images, _links, _updates (JSON)Gallery, typed links, offers and updates
_twitter, _facebook, _instagram, _googleSocial
_aggregate_rating, _aggregate_rating_count, _{yelp|tripadvisor|google}_{rating|review_count|url|price}Ratings from data sources
_is_featured, _is_closed, _is_chain, _membership_tierFlags
_score_combined, vibemap_place_vibe_countRanking signals (default sort)
_list_idsStored once per list (multiple values); Lists mode only
_amenity_feature (JSON)Amenities as {name, value} pairs, shown on single place pages and in the map details panel
_edit_request_id, _review_messageSet when Vibemap queues a place edit for review
Event meta vibemap_event_*
KeyContents
vibemap_event_slugOccurrence identity
vibemap_event_idSeries UUID (shared by all occurrences)
_start_date, _end_dateISO 8601 date-times
_is_all_day, _is_canceled, _is_featured, _is_online, _is_ongoing, _is_approvedFlags
_price, _url, _ticket_button_text, _organizer, _additional_linksDetails (_price takes price_display when present)
_performers, _performers_detailPerformers as JSON, as the API sends them. Read by the JSON-LD performer list.
_recurs, _recurrence (RRULE), _recurrence_occurrencesRecurrence
_venue_post_id, _place_id, _place_slugLink to a local place post
_venue_{name|address|latitude|longitude|slug|type}Venue copy, used when there is no linked place
_instance_*, _has_instance_override, _original_title, _original_descriptionOccurrence overrides
_images, _list_idsGallery; list membership
Shared and internal meta
KeyContents
vibemap_api_sync_status, _time, _error, _initial_timePer-post sync status
vibemap_{type}_updated_atUpstream freshness stamp that decides whether an update is applied. Don't edit it.
vibemap_primary_taxonomy_id, _typePrimary term, chosen in the editor sidebar
_vibemap_originsynced or local
_vibemap_synced_excerptThe excerpt the sync last wrote, as saved. An excerpt that differs was edited by hand and is kept.
_vibemap_sync_blocked_at, _by, _vibemap_sync_optoutCollision and unlink state
_vibemap_sync_suppressedSet when you trash a synced post, so the sync doesn't re-create it. Cleared when you restore the post.
_vibemap_trash_scopeEvents: series makes trashing one date disapprove the whole series in Vibemap. Unset means this date only.
_vibemap_approval_decisionThe last approval applied (approved, pending or disapproved). Tells a disapproved draft from an unfinished one.
_vibemap_place_matchA new place's possible Vibemap match, waiting for an editor to resolve it
vibemap_{type}_last_syncedWhen a single-item webhook sync last wrote the post
_vibemap_featured_{url|width|height|blurhash|focal|alt}Featured image in URL mode
_vibemap_{type}_push_baseline, _vibemap_sync_seen_generationSync bookkeeping. Don't edit.

Settings cascade

Most block options belong to shared settings domains, which are groups of attributes reused across blocks: card, carousel, events, filter, grid, map, pagination, similar and view. Because of this, one site-wide default (for example "show vibes on cards") applies to every block that renders cards, and any single block can still override it.

Resolution order

  1. Block attribute

    A value set on this block instance always wins. Domain attributes default to empty (null, "" or []), so a block stores a value only when an editor changes it.

  2. Post-type option

    vibemap_{post_type}_{domain}_{attr}, for example vibemap_vibemap_event_card_show_tags. Set it in Template Settings → Events/Places.

  3. Global option

    vibemap_{domain}_{attr}. Set it in Template Settings → Global. Some older option keys are checked between these steps. The first option that exists wins, so a stored 0 is a real "off".

  4. Built-in fallback

    The attribute's default, listed below.

The resolved values for every post type are printed on each page as window.vibemapDomainDefaults (plus a _global key), in the frontend and in the editor. Read it when debugging "why does this block look like that". On Template Settings, a setting without a fallback default can stay unset: a checkbox shows Inherit, On and Off, and other controls offer a Default choice that names what they inherit. Saving a tab doesn't store values you left inherited.

card domain defaults

showVibes true · showTags false · showCategories false · showDescription false · descriptionLength 150 · showBookmark false · subtitleSource/subtitle2Source none (subtitle2Source is the only control for the address line; showAddress is deprecated) · priceBadgePosition none · showRating false · ratingStarColor #FFD700 · smartCrop true · usePillLayout true · pillSingleDay false · pillShowTime false · showRecurrenceBadge false · openSinglePost false · linkToExternalUrl false · showTierBadge false · hideNoImageItems (global only).

New installs start with post-type settings: event cards show the venue as the subtitle, with tags on; place cards show the address, with vibes on.

filter domain defaults

showVibesFilter true · showCategoriesFilter true · showTagsFilter false · showSearchFilter true · searchMode hybrid · showDateRangeSelector false · initialDateFilter "" · filterViewMode horizontal · enableQueryParams true · groupRecurringEvents false · collapseConsecutiveRuns true · hideRangedEvents false · showTierFilter false.

map domain defaults

mapHeight 750 · mobileMapHeight 600 · zoomMode fit-boundary · shouldCluster false · clusterRadius 50 · enableGrouping true · boundaryBufferMeters 0 · markerStyle mixed · maxImageMarkers 32 · showParkingLayer false · showTransit null (follow the map style) · showSimilarItems true · showUserLocation false · showInlineChips true · showDateRangePills true · sheetDefaultState open · useLegacyBottomCard false · customMapStyleURL "" (falls back to vibemap_global_map_stylesheet).

similar domain defaults

similarStrictness balanced · similarMatchFields all of categories, vibes, tags · similarMinScore and similarRadiusKm come from the strictness preset (Strict 4 and 10 km, Balanced 2 and 25 km, Loose 1 and 50 km) · similarSort score (or random, alpha). Options: vibemap_{post_type}_similar_*, vibemap_similar_*; set them in Template Settings → Similar Items Matching.

grid, carousel, events, pagination, view

grid: columns 3 · shownAtStart 100 · layoutMode default. carousel: autoScrollSpeed 0 · loop true · randomize false. events: pastEventWindowMinutes 90 (how long after its end an event stays visible) · pastEventCutoffDateTime (an ISO date; when set, it replaces the window). pagination: orderBy score_combined · order DESC. view (Combo block only): views from map|grid|list|calendar; list and calendar are for events only.

Template Settings also controls what single pages show: on/off switches for the hero image, sidebar, minimap, hours, links, price, taxonomy chips, venue events, similar items and more. These are stored as vibemap_{event|place}_show_* options and served publicly from GET /vibemap/v1/template-settings.

Blocks & shortcodes

All 19 blocks are dynamic. PHP renders a wrapper (div.wp-block-vibemap-<name> with a data-attributes JSON blob) and a loading skeleton, then a React bundle takes over the markup in the browser. Blocks don't save HTML in the post content, so a plugin update changes every instance of a block at once. Blocks appear under the Vibemap Blocks category in the inserter.

The table below gives an overview of each block. For every attribute a block accepts, see the Shortcode Reference. Attribute names are the same for blocks, shortcodes and Elementor.

BlockShortcodeRenders
vibemap/native-combo
Vibemap Combo
vibemap_combo_mapMap, grid, list and calendar views with filters. The main block; it covers most use cases.
vibemap/native-events
Card Grid
vibemap_events_gridFilterable card grid of events or places
vibemap/card-carouselvibemap_card_carouselCarousel from a source, list, chosen items, a meta field, or recommendations
vibemap/single-cardvibemap_single_cardOne place, event, post or custom card
vibemap/search-filtervibemap_search_filterSearch bar with autocomplete and taxonomy chips
vibemap/add-event-formvibemap_add_event_formPublic event submission form, with AI import and notification emails
vibemap/my-listvibemap_my_listThe visitor's saved items plus recommendations
vibemap/recent-posts-showcasevibemap_recent_posts_showcaseA featured post plus recent posts. Rendered in PHP only.
vibemap/places-map-native
Map (Legacy)
vibemap_places_mapOlder standalone map. Use Combo for new builds.
Blocks used by templates (hidden from the inserter, but available as shortcodes and in Elementor):
vibemap/single-event, vibemap/single-placevibemap_single_event, vibemap_single_placeFull single-page layouts
vibemap/taxonomy-archivevibemap_taxonomy_archiveTerm archive with filters, map and grid
vibemap/event-seriesvibemap_event_seriesAll occurrences of one series
vibemap/similar-items, vibemap/venue-eventsvibemap_similar_items, vibemap_venue_eventsRelated items for the current single page (output is empty elsewhere)
vibemap/hero-image, vibemap/meta-infovibemap_hero_image, vibemap_meta_infoImage grid with lightbox; sidebar details for the current post
vibemap/bookmarks, vibemap/shared-list-contentvibemap_bookmarks, vibemap_shared_listLegacy bookmarks list or itinerary; the /shared-list/ page

Data sources

List blocks take a source attribute. The values the editor writes are all_events, all_places, events_list or places_list (one Vibemap list, chosen with listId), select_events or select_places (hand-picked items), and all_posts for regular posts. The Combo block also accepts the shorter events, places, current and bookmarks. You can narrow results with filterBy and selectedTaxonomies, taxonomyRelation, searchQuery, exclusions, and date filters (initialDateFilter, for example next_7_days). Visitors can widen the initial date range.

Shortcodes

Full reference: Shortcode Reference

Lists every shortcode with every attribute it accepts (over 1,200), including types, defaults, allowed values and when each one applies. The page has a search filter.

Every block has a shortcode, and each shortcode goes through render_block(), so the output is the same as the block's. Attribute rules:

  • Any block attribute works in snake_case. For example, initial_view maps to initialView, and show_ai_search maps to showAISearch.
  • Values are converted to the attribute's type. Booleans accept true/false/1/0. Arrays take comma-separated values. Objects take JSON; exclude_taxonomies also takes a comma-separated term list when exclude_type names the taxonomy (exclude_type="vibemap_event_category" exclude_taxonomies="music,comedy"). WordPress doesn't allow [ or ] inside shortcode attributes, so JSON arrays don't work there.
  • categories, tags and vibes take comma-separated term slugs or IDs. They use the place taxonomies unless source contains "event", so pass source on event blocks.
  • Text between an opening and closing shortcode becomes customContent.
  • Unknown attributes are dropped without a warning. Check names against the Shortcode Reference.
  • Height attributes such as map_height take plain pixel numbers in shortcodes. CSS lengths like 90vh only work in the editor.
[vibemap_combo_map source="all_events" initial_view="list" initial_date_filter="next_7_days" tags="live-music"]

[vibemap_events_grid source="all_places" columns="4" vibes="cozy,outdoors" show_vibes="true"]

[vibemap_card_carousel source="places_list" list_id="<list-uuid>" loop="false"]

Elementor

When Elementor is active, each shortcode is also an Elementor widget in a Vibemap Blocks category. The widget controls are generated from the block's attributes and match the Gutenberg sidebar. Blocks hidden from the Gutenberg inserter are also hidden from the Elementor panel. Previews render on the server, so what you see in the editor is the real output.

Templates & theme integration

Block themes

The plugin registers these block templates, with IDs prefixed vibemap-plugin//: single-vibemap_event, single-vibemap_place, shared-list, and taxonomy-vibemap_{event|place}_{category|vibes|tags}. Each template is your header part, then the Vibemap block, then your footer part. You can override them the usual way: edit them in the Site Editor, or add templates/<slug>.html to your theme. Neighborhood archives have no block template. Search and event-series pages always use the plugin's PHP templates.

Classic themes

For single and taxonomy views, the plugin looks for a template in the child theme, then the parent theme, then its own templates/ folder. To override one, copy the file into your theme with the same name:

single-vibemap_event.php
single-vibemap_place.php
taxonomy-vibemap_{event|place}_{category|vibes|tags|neighborhood}.php
search-vibemap.php          (the /vibemap-search/ results page)

You can't override shared-list or event-series. The plugin's templates call get_header() and get_footer() and wrap the content in div.wp-site-blocks.vibemap-single.

Integration hooks

HookDetails
body.vibemap-templateBody class on Vibemap singles, event-series, shared-list, search, and category/vibe/tag archives. Neighborhood archives don't get it. WordPress also adds single-vibemap_event and single-vibemap_place.
vibemap_before_template_content
vibemap_after_template_content
Actions that receive the template slug and fire just after the header and just before the footer. Use them for breadcrumbs, spacers under an overlay header, or ads. They fire in the plugin's PHP templates, so on block themes they only fire for search, event-series and shared-list. They don't fire when a template renders inside another page.
Single Page Content WidthSet in Template Settings → Global (320–3840 px; 0 = inherit). It sets --vibemap-single-content-width. Without it, single pages use the theme's wide-size, falling back to 1200 px.
vibemap_server_render_listing_maxCaps how many cards the Events grid, Combo, Card Carousel and Taxonomy Archive blocks render in the page's HTML (default 48, never more than the block shows at first). Return 0 to turn listing server rendering off. See host-theme-integration.md for the card markup and classes.
vibemap_disable_transparent_headerOn Vibemap single pages the plugin turns off transparent or overlay headers in Astra, OceanWP, Kadence and Blocksy. Return false from this filter to stop that. For other themes, including Divi and GeneratePress Premium, target the body classes yourself.
// Push content below a fixed, transparent header on Vibemap views.
add_action( 'vibemap_before_template_content', function ( $slug ) {
    echo '<div class="site-header-spacer" aria-hidden="true"></div>';
} );

Virtual routes

The plugin adds three URLs of its own: /vibemap-search/ (?q=, post_type[], date_filter), /event-series/<slug>/, and /shared-list/?ids=1,2&schedule=…. They are registered as rewrite rules. If they return 404 after a deploy, re-save Permalinks. /llms.txt, the IndexNow key file, and the .md and .ics copies of singles need no rewrite rules (see AI search & discovery).

A series' slug is its events' Vibemap slug without the date (open-mic_2026-08-11-22-00 → /event-series/open-mic/), taken from its newest date, so a renamed event moves to its new slug and the old one 301s there. The old /event-series/?vibemap_id=<uuid> links 301 to the slug and keep their other query parameters, such as UTM tags; an unknown series is a 404. With plain permalinks the page is /?event_series=1&vibemap_series=<slug>. The rewrite rule is added on update with a one-time soft flush, so you don't need to re-save Permalinks for it.

Date landing pages add /event/{tonight|today|this-weekend|this-week}/ and the same four under each event category and neighborhood archive (/event-category/music/tonight/). They are server-rendered lists with their own title, meta description, canonical and ItemList JSON-LD, and are listed in the sitemap. Turn them off (vibemap_enable_event_landing_pages, on by default) or edit their intro sentences in Settings → Vibemap → Date landing pages. A page with no events, or a category or neighborhood page with fewer than two, is noindex, follow and left out of the sitemap. An event that runs longer than the window, such as a month-long exhibition on this week, is left out; one that fits, such as a Friday-to-Sunday festival on this weekend, stays. Each page sends Cache-Control: public, max-age (and s-maxage) until its list next changes, at most 15 minutes, and sets the same TTL for LiteSpeed Cache; the landing sitemap does the same. Filters: vibemap_landing_windows (drop windows), vibemap_landing_window (reshape one), vibemap_landing_intro, vibemap_landing_title and vibemap_landing_description (the copy), vibemap_landing_min_items and vibemap_landing_max_items (48 cards). host-theme-integration.md lists the windows, markup and every vibemap_landing_* filter.

Server-rendered blocks

The Single Event, Single Place, event-series and Hero Image blocks, and the first page of cards in the Events grid, Combo, Card Carousel and Taxonomy Archive blocks, are in the page's HTML, so search engines and AI crawlers that run no JavaScript read them and visitors see real content at first paint:

  • Singles: the <h1>, <time datetime> dates in the venue's time zone, the venue <address>, the description, the hero photo (fetchpriority="high", with its width and height) and an Event details block of plain sentences (when, where, cost, tickets; for places where, hours, price, phone, website). Canceled events show a banner, and ended events the notice described in Past events.
  • Listings: each card is an <article> whose <h3> links to the item's page on your site, with its dates and the same photo React loads; the first row loads eagerly. The category, venue and <address> appear when the card settings show them, as on the live cards. The cards come from the same query the block's script makes, so they follow its settings (hand-picked order and grouped series included) and leave out past events, items with no map position and, in a Combo, items outside its boundary, exactly as the live block does. A Combo that opens on its calendar sends a list of upcoming events under a heading per day, scrolling in a box sized to the month grid that replaces it: its weeks, and the events each day shows up to the block's per-day limit, counting every date in those months as the calendar does, not just the cards the list shows. On phones, where the calendar is itself a list by day, the list takes its own height. A visitor's saved items stay script-only.
  • The swap: when the block's script runs, React renders into a new div.vibemap-react-root inside the block and removes the server markup (marked data-vibemap-ssr) in the frame its own content paints. If the data never arrives, the server content stays. Because the React layout is no longer the block's direct child, theme CSS that targets it with a child selector (.wp-block-vibemap-single-event > …) must use a descendant selector instead. Style the server markup through .vibemap-ssr, .vibemap-facts, .vm-ssr-listing and .vm-ssr-card; the Card Grid, Taxonomy Archive and a Combo's Grid print React's own card markup (article.sing-card), so the live cards' styles apply to them as well.
  • Page caches now hold the first page of cards. JavaScript visitors still get fresh data once the block loads; for crawlers, a listing is as fresh as your page cache, so keep its lifetime to hours, not days, on event listings.

vibemap_server_render_listing_max caps the server cards (default 48); return 0 to send the loading skeleton instead. host-theme-integration.md (sections 4 and 5) has the full markup and class list.

Styling

  • Brand theme. Colors and fonts come from your organization's Vibemap theme, or a custom theme slug set in Settings. They are applied as CSS custom properties that the component CSS reads, and every one has a fallback: --vm-color-accent, --vm-color-accent-text (optional darker accent for small text), --vm-color-primary, --vm-color-surface, --vm-color-text, --vm-color-border, --vm-color-muted, --vm-font-sans, --vm-font-serif, --vm-marker-*, --vm-map-*.
  • Term colors. Each term's color and text_color meta style its chips and markers when Use taxonomy colors in blocks is on.
  • Isolation. Styles aren't fully isolated from your theme. Global theme rules on elements like button, h3 or img can reach block content. The only guard is [class*="wp-block-vibemap-"]{min-width:0;max-width:100%}. Scope your overrides under .wp-block-vibemap-* or .vibemap-single.
  • Assets. ui-components.css (about 370 KB), the base block CSS and the frontend config load only on pages that show Vibemap content: Event and Place singles and archives, Vibemap taxonomy archives, the shared list, event series and search pages, and any page whose content, patterns, widgets or Elementor layout holds a Vibemap block or [vibemap_*] shortcode. A block the check misses (a theme template part, do_blocks() in a theme file) enqueues them when it renders. The map CSS loads only where a map can show. Toastify and the modal load only with legacy Bookmarks on, and none of the helpers needs jQuery. Each block's JavaScript loads deferred, only when that block renders, and code that several blocks share ships once as vibemap-shared-<id> handles (build/shared/). If your theme or custom code uses Vibemap's classes or helpers elsewhere, add_filter('vibemap_force_load_assets', '__return_true') loads everything on every page, as before. host-theme-integration.md lists every handle and when it loads.

REST API & webhooks

All routes live under /wp-json/vibemap/v1/. The read routes query your local posts. Blocks use them, and you can call them from your own code too.

Public read routes

RoutePurpose / notable params
GET places-datasearch, taxonomy, terms, taxonomy_relation, post_ids, list_id(s), sort_by, page, per_page, fetch_all (editors and WP-CLI; see vibemap_rest_allow_fetch_all), fields, include_facets
GET events-dataEverything places-data accepts, plus date_filter, start_date, end_date, featured, past_window_minutes, past_cutoff_datetime, exclude_ranged, ranged_hours. start_date and end_date take an ISO date or a relative offset in days, months or years (+14d, -7d, +3m, +1y), counted in whole days in the site's timezone. exclude_ranged=true leaves out ongoing events before paging, so pagination counts only what's left. An event is ongoing when it lasts more than ranged_hours (24 unless set; the date landing pages send their window's length, so a weekend festival stays on /this-weekend/), or when it's flagged ongoing and has no end date. Each event also carries vibemap_ics_url, as below.
GET search-dataSite search across the Vibemap post types
GET taxonomy-termstaxonomy, include_hidden. Category taxonomies also return category_options, and category terms carry slug_unique.
GET similar-items/{post_id}, venue-events/{place_id}Related items (these include a top-level hide_from_frontend list). similar-items takes strictness, match, min_score, radius_km and sort; see the similar domain in Settings cascade.
GET event-series/{vibemap_id}, event-series-listOccurrences of one series, or all series. Every event these routes, events-data, search-data, similar-items, venue-events and posts-by-ids return carries series_url: its series page, or for an event made in WordPress, which holds its whole schedule, its own permalink.
GET posts-by-ids, places-by-api-ids, bookmarks-data, lookup-venue/{venue_id}Lookups by WordPress ID or Vibemap ID
POST collections/recommendationsRecommendations from the live Vibemap API (cached 10 minutes, at most 24 items)
GET settings, template-settingsPublic site configuration for the frontend (boundary, theme slug, map style, badge text, available lists, and synced_lists, the lists this site syncs). settings can be changed with the vibemap_settings_api_response filter.

Place and event posts are also available at /wp/v2/vibemap_place and /wp/v2/vibemap_event, with all meta and the vibemap_featured_image field. Events also carry vibemap_ics_url, the event's .ics address, or null when calendar feeds are off or the event has no public page, here and on each events-data item; Add to Calendar → Apple Calendar (.ics) links it on the single event page and in map and combo detail panels.

Events from /wp/v2/vibemap_event, events-data and event-series/{vibemap_id} also carry vibemap_timezone, the time zone their dates are in: the venue's, else the event's own, else the site's. Add to Calendar builds its Google, Outlook and Yahoo links in it, as the event's .ics does.

Authenticated routes

RouteAuthPurpose
POST sync-single/{id}, sync-images/{id}, GET compare/{id}edit_postsEditor tools: re-pull one post (this skips the local-post protection), re-fetch its images, compare it with Vibemap
link/candidates|compare|apply|unlinkedit_postResolve sync collisions (see Editing synced content)
place-match/{post_id}/compare|link|create-newedit_postResolve a new place that matches an existing Vibemap place: list the differing fields (GET), link with per-field choices (POST), or create a separate place (POST). See Write-back.
POST events/{id}/revert-instanceedit_postRemove an occurrence override
POST fetch-organizationmanage_optionsConnect or refresh the organization
POST send-notification-emailtokenAdd Event Form alerts. Uses a signed notify_token, and the recipient addresses never reach the browser. Rate-limited to 10 per IP every 10 minutes.
webhook/*X-Vibemap-API-KeySee below

Webhooks

Webhooks let Vibemap, or your own tooling, push changes to the site instead of waiting for the next scheduled sync. To turn them on, go to Vibemap Settings → Webhook Settings, click Generate key and save. The key looks like vbm_ followed by 64 hex characters. Deleting the key turns webhooks off, and generating a new one invalidates the old one immediately. Webhooks work whether or not the scheduled syncs are turned on.

Send the key in the X-Vibemap-API-Key header. A missing key returns 401 missing_api_key. A wrong key returns 403 invalid_api_key. If no key is configured, the response is 403 webhook_not_configured.

Refresh one item (runs immediately)

POST /wp-json/vibemap/v1/webhook/sync-item
X-Vibemap-API-Key: vbm_…
Content-Type: application/json

{ "item_type": "event", "item_id": "<vibemap-uuid>", "slug": "optional-occurrence-slug", "action": "update" }
200 OK
{
  "item_type": "event", "item_id": "…", "action": "update", "status": "ok",
  "processed": 3,
  "results": [ { "slug": "jazz-night_2026-10-02-19-00", "start_date": "…", "result": "updated" } ],
  "post_ids": [ 4812, 4813, 4814 ]
}
  • item_type is place or event. action is update (the default) or delete. force defaults to true.
  • Events: the request refreshes every upcoming occurrence of the series, or just one if you pass slug. A 404 for an event can mean all its occurrences have already ended, not that it was deleted.
  • delete moves the posts to the trash. If EMPTY_TRASH_DAYS is 0 it removes nothing and returns 409 with status trash_unavailable.
  • In Lists mode, a post created this way doesn't get list membership until the next full sync. The response warns you with list_membership_not_stamped.
  • Status codes: 200, 400 (bad request), 404 (not found upstream), 409 (trash disabled), 502 (Vibemap API error), 500.

Sync one item against your lists (runs immediately)

POST /wp-json/vibemap/v1/webhook/trigger-sync      { "type": "events" | "places", "id": "<vibemap-uuid>", "slug": "optional-occurrence-slug" }
→ 200 { "ok": true, "action": "created|updated|removed|noop", "post_id": 123, "post_status": "publish",
        "permalink": "…", "synced_at": "…", "membership": "feed", "post_ids": [123] }
→ 202 { "ok": true, "action": "queued" }            (ran past about 7 seconds; finishes in Action Scheduler)
  • Vibemap sends this when an item in your feed is saved. The plugin asks each selected list whether it contains the item. If one does, the post is created or updated and stamped with list membership. If none does, its posts are trashed, except when Prevent removal is on, or the post is Pending, authored in WordPress, or an event that ended within the retention period.
  • In Legacy mode, or when a list can't confirm the item, it only refreshes posts the site already has and returns "membership": "unverified".
  • permalink is null unless the post is published. A failed feed read returns 502 and removes nothing. {"type": "test"} returns {"ok": true, "pong": true}. Item syncs are listed in Sync History.

Full sync (runs in the background)

POST /wp-json/vibemap/v1/webhook/trigger-sync      { "type": "events" | "places" | "all", "force_all": false }   (no "id")
→ { "status": "pending", "sync_id": "…" }            (or "already_running")

GET  /wp-json/vibemap/v1/webhook/sync-status/{sync_id}
→ { "status": "pending|in_progress|completed|failed", "percentage": 64, "phase": "…", "stats": { … } }

GET  /wp-json/vibemap/v1/webhook/sync-history?limit=10&type=all

Results for a completed sync stay available from sync-status for 1 hour.

Hooks reference

These are all the filters and actions the plugin offers for integration. The sync has no per-item "item synced" hook and no filter for mapping fields. To react to sync writes, use the core hooks (save_post_vibemap_place, save_post_vibemap_event, wp_after_insert_post) and check VibeMap_Sync::is_api_sync_active().

Frontend & templates

HookTypeArgs → purpose
vibemap_before_template_contentaction$slug. Fires after the header in the plugin's PHP templates.
vibemap_after_template_contentaction$slug. Fires before the footer.
vibemap_disable_transparent_headerfilterbool (default true). Controls the transparent-header fix for supported themes.
vibemap_single_event_custom_carousel_idsfilter[], $post_id. Adds extra carousels to single event pages.
vibemap_rest_contentfilter$content, $post_id, $post_type. Changes descriptions in read routes (for example, for translation).
vibemap_rest_cache_key_suffixfilter''. Splits the REST cache by a key such as language.
vibemap_settings_api_responsefilter$settings. Changes the public /settings payload.
vibemap_exclude_past_eventsfilterbool, $query. Whether a query that does not set vibemap_exclude_past drops ended events. True on front-end event archives, feeds, taxonomy archives and search, and on theme and page-builder event lists unless Show ended events in theme and page-builder lists is on.
vibemap_event_ended_notice_htmlfilter$html, $post_id, $next (kind, url, text). The "This event has ended" notice on an ended event's page.
vibemap_event_series_urlfilter$url, $series_id. The series page an ended event points and redirects to.
vibemap_event_schemafilter$schema, $post_id. The Event JSON-LD before it is printed.
vibemap_place_feed_includesfilter[]. Opt-in API place extras (for example salesforce) added to every place feed's ?include=. They land as JSON in vibemap_place_extra_data.
vibemap_domain_defaults_post_typesfilterPost types included in window.vibemapDomainDefaults.
vibemap_preload_pathsfilter$paths. Rewrites or removes the REST paths whose data is embedded in the page ahead of time.
vibemap_skip_preloadfilterfalse, $paths. Return true to skip that embedded data.
vibemap_meta_descriptionfilter$description, $post_id. The description for a single event or place page, already cut to 155 characters.
vibemap_schemafilter$schema, $post_id, $post_type. The JSON-LD node for a single event or place page. Return [] to print none.
vibemap_schema_graph_modefilter$mode: yoast, rank_math, other (another SEO plugin prints the page, breadcrumbs and publisher) or standalone (no SEO plugin). Return other if your theme prints its own WebPage or BreadcrumbList, or standalone to print the whole graph beside a plugin that doesn't.
vibemap_schema_publisherfilter$node. The site's Organization (name, home URL, custom logo or site icon). Return another node, such as a Person, or [] for none.
vibemap_schema_item_listfilter$items ([['url' => …, 'name' => …], …], names in plain text, or null before the listing renders), $page. What an archive's ItemList names, in order. Return only items the page shows.
vibemap_schema_event_seriesfilter$node, $vibemap_id. The EventSeries node on a series page. Return [] to print none.
vibemap_event_series_urlfilter$url, $vibemap_id. A series page's URL wherever the plugin builds one: links, canonical, JSON-LD, sitemap and the redirect from an ended event.
vibemap_schema_place_typefilter$type, $post_id. The schema.org type for a place, such as Restaurant. Letters only; anything else falls back to LocalBusiness.
vibemap_noindexfilter$noindex, $context (search, shared-list, event-series for a series page that isn't indexable, my-list or ''), $post (the page, for my-list). Return false to let a utility page be indexed, or true to noindex another page.
vibemap_seo_plugin_activefilterbool. True when a known SEO plugin printed this page's head (Yoast and Rank Math once their head action fires, the others once active). Return true if your theme or an SEO plugin the plugin doesn't detect prints the description and Open Graph tags, so they aren't printed twice.
vibemap_schema_archive_namefilter$name, $post_type. The archive's name in breadcrumbs and its ItemList: "Events" or "Places", or the post type's own archives label when it differs from the admin menu name.
vibemap_synced_excerptfilter$excerpt, $description, $post_type. The excerpt the sync writes. Return '' to leave excerpts empty.
vibemap_collections_login_url, …_signup_urlfilterLogin and sign-up links for My List.
vibemap_analytics_enabledfilterbool. Overrides the analytics setting.
vibemap_analytics_skip_requestfilter$skip. True by default for editors, previews, the Customizer and non-production sites. Return false to track those requests.
vibemap_rest_allow_fetch_allfilter$allowed, $request. True by default for users who can edit_posts and for WP-CLI. Allows fetch_all on places-data and events-data.
vibemap_llms_txt_enabledfilterbool. Overrides the llms.txt setting.
vibemap_llms_txt_documentfilter$doc (title, summary, details, sections of {title, links: [{title, url, note}]}). Adds, removes or reorders what /llms.txt lists.
vibemap_llms_txt_feeds, vibemap_llms_txt_sitemapsfilterThe feed links and sitemap URLs /llms.txt lists.
vibemap_llms_txt_owned_elsewherefilterbool, $wp. Return true to leave /llms.txt to another plugin.
vibemap_markdown_enabledfilterbool. Overrides the Markdown pages setting.
vibemap_markdown_documentfilter$markdown, $post. The Markdown copy of an event or place.
vibemap_markdown_negotiatefilterbool, false by default. True serves the Markdown copy at the page's own address to requests that prefer Accept: text/markdown, sent private, no-store, and adds Vary: Accept to the HTML. Turn it on only behind a cache that honors both.
vibemap_indexnow_activefilterbool. Whether this site sends IndexNow notices. False on non-production sites, when search engines are discouraged and on local host names.
vibemap_indexnow_material_metafilter$keys. Meta keys whose change counts as a page change.
vibemap_indexnow_post_url, vibemap_indexnow_endpointfilterThe URL sent for a post, and the IndexNow endpoint (default https://api.indexnow.org/indexnow).
vibemap_ics_feeds_enabled, vibemap_event_rss_enabledfilterbool. Override the calendar feeds and events RSS settings.
vibemap_ics_eventfilter$event, $post, $in_feed. One event's calendar entry before it is written (summary, description, location, start, end, rrule, …). Return null to leave the event out.
vibemap_ics_feed_limit, vibemap_ics_past_daysfilterUpcoming events per calendar feed (default 500), and how many days of ended events it keeps (default 30, up to 100 events; 0 for none).
vibemap_recaptcha_site_keyfilter$key (default VIBEMAP_RECAPTCHA_SITE_KEY). The Add Event Form's reCAPTCHA v3 site key.
vibemap_ai_crawler_log_requestfilter$count, $crawler (a key such as gptbot). Whether to count this AI crawler request in AI Crawlers. True on Vibemap pages and /llms.txt; return true to count other pages, or false to count nothing.

Caching

HookTypePurpose
vibemap_api_cache_enabledfilterTurns the REST response cache on or off
vibemap_api_cache_time (60), vibemap_api_cdn_cache_time, vibemap_api_cdn_swrfilterBrowser max-age, edge max-age, stale-while-revalidate
vibemap_api_edge_purgeaction$paths. Hook your CDN purge in here (WP Engine purging is built in)
vibemap_api_edge_purge_paths, vibemap_api_edge_purge_enabledfilterWhich paths are purged, and whether purging happens at all
vibemap_api_cache_clearedaction$post_id, $post_type (both null for a full clear)
vibemap_api_cache_cleared_termaction$term_id
vibemap_api_data_cache_prefixesfilterExtra transient prefixes to clear along with the cache

Sync & operations

HookTypeDefault → purpose
vibemap_completeness_tolerancefilterint, $type. How many items can be missing before cleanup is skipped.
vibemap_deletion_cap_min / _ratiofilter10 / 0.10. Thresholds for the deletion cap.
vibemap_past_event_retention_daysfilter183. Days an ended event stays published before cleanup may trash it. 0 removes it once it leaves the past-events window.
vibemap_cleanup_past_event_retain_minutesfilterThe past-events window cleanup keeps, in minutes; the retention period above applies when it is longer.
vibemap_past_event_redirect_daysfilter365. How long a removed ended event's address keeps redirecting.
vibemap_past_event_redirect_urlfilter$url, $series_id, $venue_post_id. Where a removed ended event redirects. Return '' to let it 404.
vibemap_cleanup_batch_size, _time_budget, _max_failuresfilter250 / 25.0 s / 3. Cleanup tuning.
vibemap_churn_removal_maxfilter250, $type. Most dropped dates of live series one cleanup may trash before it waits for an admin. A negative value turns the ceiling off.
vibemap_cleanup_liveness_probe_cap, vibemap_cleanup_liveness_time_budgetfilter100 / 20.0 s. How many vanished events cleanup checks with Vibemap per run; unchecked events are kept until the next run.
vibemap_series_repull_inline_maxfilter100. A series edit with more dates than this refreshes its other dates in Action Scheduler instead of during the save.
vibemap_run_scheduler_batch_sizefilter25. Batch size for the Dashboard's "Run pending tasks".
vibemap_clear_all_batch_size, vibemap_clear_all_scan_pagesfilter100 / 20. Batch size for the Clear-all tools, and how many pages each batch scans past the WordPress-authored posts it keeps.
vibemap_venue_search_hide_unlinked_wp_placesfilterfalse. Return true to hide WordPress places that aren't linked to Vibemap from the event editor's venue search.
vibemap_audit_log_enabledfilterTurns the audit log on or off.
vibemap_log_basedirfilterThe uploads folder. Base folder for vibemap_sync_logs/ and vibemap_audit_logs/. Return '' to stop writing sync log files; audit logs then fall back to wp-content/.
vibemap_error_reporting_enabledfilterbool (default: the Send Error Reports setting). Return false to send no error reports.
vibemap_sentry_dsn, vibemap_sentry_sample_ratefilterThe error-report DSN ('' turns reporting off) and the share of errors sent (1.0).
vibemap_sync_block_changedaction$post_id. A sync collision was recorded or cleared.

You can trigger these Action Scheduler hooks with as_enqueue_async_action(): vibemap_sync_events, vibemap_sync_places, vibemap_refresh_categories, vibemap_repair_venues, vibemap_backfill_neighborhood_terms.

WP-CLI & maintenance

CommandFlagsPurpose
wp vibemap sync <events|places|all>--force --resume --force-restart --no-cleanup --skip-images --max-actions=NRuns a full sync in the CLI process. Recommended on hosts that kill long-running loopback requests. It won't start while another sync is running unless you pass --force-restart.
wp vibemap dedupe-events--dry-run --limit=NMerges duplicate occurrence posts; the extras go to the trash.
wp vibemap repair-venues--dry-run --limit=NFixes event→venue links. Also runs automatically once a week.
wp vibemap backfill-vibe-counts--batch-size=NFills in the default place ranking. Run it once after upgrading from 3.x.
wp vibemap backfill-place-coordinates--dry-run --limit=NFills in missing place coordinates.
wp vibemap featured-url migrate|status|set|clear--cpt= --reverse --dry-run --cleanup --batch-size=NMoves posts between the URL and sideload image modes, or sets the image for one post.
wp vibemap media stats|purge--scope=owned|attached|all --dry-run --keep-featured --check-content --batch-size --max --yesBulk-removes images the plugin downloaded into the Media Library. Always run with --dry-run first.
# Hosts that kill loopback workers: run the sync from system cron instead
0 3 * * *  cd /path/to/site && wp vibemap sync all --quiet

If you schedule the sync from system cron, turn off the built-in schedule (Enable sync off) so the two don't overlap. Webhooks keep working.

Caching & performance

  • REST responses from the public read routes are cached in transients, keyed to a cache version. Saving, trashing or deleting a Vibemap post, or editing a term, changes the version, so the sync invalidates the cache as it writes.
  • HTTP headers: Cache-Control: max-age=60, a CDN-Cache-Control with stale-while-revalidate, and ETag and Last-Modified tied to the cache version. Adding ?_t= bypasses the cache.
  • CDN purge: WP Engine purging is built in. For any other CDN, purge the paths passed to the vibemap_api_edge_purge action.
  • Page caches: page caching is safe. Blocks send their first page of cards, or the single item, in the HTML (see Server-rendered blocks), then load fresh data from the REST routes, so visitors see new data once the REST cache and CDN refresh (about 60 seconds by default). Crawlers read the cached HTML, so keep page-cache lifetimes for event listings short (an hour or less). Date landing pages set their own lifetime (at most 15 minutes, through Cache-Control and LiteSpeed Cache's TTL); a cache that ignores both, such as one that never purges virtual URLs, needs a rule for them.
  • Embedded data: the single-card, carousel, single-page and related-item blocks embed their first request's data in the page as JSON, so they render without a round trip. You can control this with vibemap_preload_paths and vibemap_skip_preload.
  • Optimizers: block bundles ship as *.min.js, which minifiers skip. SiteGround Optimizer also has the plugin's scripts excluded automatically. If another optimizer combines or delays JavaScript and a block breaks, exclude the plugin's build/ folder.
  • Manual clear: Maintenance Tools → Data Management → Clear API Cache.

Analytics, SEO & privacy

Analytics

By default, a shared Vibemap Google Tag Manager container is loaded on the frontend, except for logged-in users who can edit_posts, previews, the Customizer, and sites whose wp_get_environment_type() isn't production (change that with the vibemap_analytics_skip_request filter). Adding ?analytics=off to a URL turns it off for that page view. It records how visitors use Vibemap components: page views, searches, filters, date ranges, map zoom and cluster clicks, item views, call, website, directions and share clicks, ticket and social link clicks, Load More, form starts and submits, and list saves.

Each click that opens an item names where it was found (source: card, marker, list, carousel or calendar) and its 1-based position_in_list, so a pin click and a card click can be told apart. Cards seen arrive as item_impressions events: a card counts once per page view, after at least half of it has been on screen for a second, and up to 20 cards from one list share an event; add up item_count for cards seen. Each batch names the block its cards sit in (embed_type). Ticket and event link clicks (event_link_clicked) send the link's host (outbound_host) and row (link_type), never the address.

Each event also names where it came from: your organization slug (partner, or your theme slug when the site has no organization), theme, the Vibemap block the visitor was using (embed_type, e.g. wp:native-events), surface (wp-plugin), your site's hostname (host) and the plugin version (plugin_version). The events go into the page's window.dataLayer, so your own Google Tag Manager container can read them too.

On pages that show a Vibemap block, the script also measures page speed with the browser's own performance API: Largest Contentful Paint, Cumulative Layout Shift, Interaction to Next Paint, First Contentful Paint and Time to First Byte. Each arrives as a web_vitals event with metric_name, metric_value (milliseconds; CLS is a score) and metric_rating (good, needs-improvement or poor). They describe the whole page, not only the block. ?analytics=off and the analytics setting stop them.

To turn it off, use Settings → Features → Enable Analytics, or add_filter('vibemap_analytics_enabled','__return_false'). The filter takes priority over the setting. When analytics is off, the script isn't loaded at all. Your own analytics are unaffected.

My List doesn't depend on analytics

From 4.4.4, the script behind the My List save toast and non-block saving (vibemap-collections-init) loads on every front-end page, whatever the analytics setting. Before 4.4.4 it loaded only where analytics loaded, so turning analytics off removed the toast and saving from the event feed shortcode, mini-cart and classic templates; in 4.4.0–4.4.3, editors, previews and non-production sites lost them too.

Schema & SEO

  • Meta description. Single event and place pages get one: "date at venue. description" for events, the description for places (falling back to categories and address). A hand-written excerpt replaces the description. With an SEO plugin it goes through that plugin's description filter. A description written in that plugin always wins. Otherwise ours replaces the plugin's own fallback: Rank Math's and SEOPress's excerpt template and The SEO Framework's generated description. Yoast's description is used when it has one (written, or from a template you set for the post type). All in One SEO stores written descriptions where the plugin can't tell them from its template, so it fills only an empty one there.
  • Open Graph. With no SEO plugin printing the head, the plugin prints the meta description plus og:type, og:title, og:description, og:url (the canonical URL), og:site_name, og:image (the featured image, never the no-photo stand-in) and twitter:card. Yoast and Rank Math count only once they print their head (wpseo_head, rank_math/head), so Rank Math before its setup wizard leaves ours in place; other SEO plugins count once active. With an SEO plugin, that plugin keeps its own tags, but its Open Graph and Twitter descriptions (Yoast's wpseo_opengraph_desc and wpseo_twitter_description, Rank Math's og_description and twitter_description) follow the same rule as the meta description. When Jetpack prints Open Graph tags, only the description is added. Turn all of this off under Settings → Features → Meta Description & Social Tags (vibemap_emit_meta_tags).
  • Recurring events. The sync writes one post per date, and each stays its own page: its canonical is its own permalink, its title and Open Graph title carry its date ("Open Mic – Tue, Aug 11, 2026", with the time when the series has two dates that day), its description leads with that date, and its Event names the series as superEvent. Google shows dated events, not series, which is why dates aren't canonicalized to the series. The series page (/event-series/<slug>/) has its own title ("Open Mic - Event Series - Site"), canonical, a description that leads with the schedule and next date, and an EventSeries with its next 30 dates as subEvent; with no SEO plugin, the plugin prints its canonical and Open Graph tags too. It is a virtual page with no post behind it, set up before SEO plugins read the request, so the plugin hands Yoast, Rank Math, SEOPress, All in One SEO and The SEO Framework its title (The SEO Framework's without the site name, which it adds itself), canonical (SEOPress gets the whole <link> tag), description and Open Graph and Twitter title and description; none of them describes it as the home page or the Posts page. It is indexed while it has two or more published dates, one still to come, and event pages are on; otherwise it stays up with noindex, follow. Indexable series pages are listed in the WordPress core sitemap (wp-sitemap-vibemapseries-1.xml) and, since Yoast and Rank Math switch that off, on the first page of their event sitemap (vibemap_event-sitemap.xml, up to 1,000).
  • Excerpt. The sync fills the excerpt with a plain-text copy of the description, which SEO plugin templates such as Rank Math's %excerpt% read. See Editing synced content for how hand edits are kept.
  • JSON-LD. Event and place pages and their archives output it. Turn it off with vibemap_emit_schema, or change the event or place node with the vibemap_schema filter. Its @id is the permalink plus #event or #place, so it never collides with the WebPage node an SEO plugin keys on the bare permalink. Each entity appears once, whichever plugin prints the graph:
    • No SEO plugin: one graph in wp_head: the WebPage (or CollectionPage on an archive) with your site as publisher, the event or place as its mainEntity, a BreadcrumbList on singles (Home, the post type's archive when it has one, the page; the archive is named "Events" or "Places", or the post type's own archives label, never the admin menu's "Vibemap Events") and an Organization for your site: its name, home URL and custom logo, else the site icon. publisher sits on the page, the CreativeWork schema.org gives it to; an Event has none.
    • Yoast SEO: the event, place or archive list joins Yoast's graph as a piece (wpseo_schema_graph_pieces, identifiers vibemap_event, vibemap_place, vibemap_event_series, vibemap_itemlist, vibemap_publisher) and points at Yoast's WebPage through mainEntityOfPage; Yoast's WebPage gets mainEntity back. Yoast keeps its own WebPage and BreadcrumbList. Your site is added as publisher only when Yoast's Site representation names no organization or person. A series page joins Yoast's or Rank Math's graph only when its WebPage is the series page's URL; otherwise its EventSeries prints on its own, as beside any other SEO plugin.
    • Rank Math: the same through rank_math/json_ld, plus a BreadcrumbList and publisher only when Rank Math printed none. An Event or Place schema you configured in Rank Math for the post wins, and ours is left out.
    • Any other SEO plugin (SEOPress, All in One SEO, The SEO Framework, Slim SEO, Squirrly, SmartCrawl), or Yoast or Rank Math printing no graph: only the event, place or list prints, with mainEntityOfPage set to the page URL, since that plugin prints the page, breadcrumbs and publisher. Change the choice with vibemap_schema_graph_mode.
    • Archives (the event and place archives and their category, vibe, tag and neighborhood archives): an ItemList of the first page as it renders, each ListItem a position, URL and name that link to a page with its own Event or Place. The post type archive lists the theme's loop. A term archive lists the cards its listing block prints in the HTML; until that listing renders on the server there is nothing to list, and a classic theme, which prints wp_head before the listing, gets the list in wp_footer. Later archive pages get no list, and password-protected posts no schema.
    • Event: dates in the venue's timezone; status (Scheduled, Cancelled, Postponed, Rescheduled with previousStartDate, or MovedOnline) from the synced event_status; attendance mode; the venue as a Place with a full PostalAddress (street, city, region, postal code, country), geo, and a link to its place page when that page is published; performer (a Person or PerformingGroup each, with profile links); organizer with the organizer's own website when the data names one; the featured image cropped to 16:9, 4:3 and 1:1 on the CDN; and an offers node with the ticket link, availability and price. An ended event keeps its dates and loses its offer; vibemap_event_schema changes the Event node.
    • Price and currency. A price is given only with a currency, and never guessed. The currency is the event's own ("£12", "CAD 30"), else that of the venue's country (from its address, else its time zone), else Settings → Features → Currency for Prices (vibemap_currency), which follows the site language until set. A venue in a country without a known currency, a price whose symbol contradicts its country ("$15" in London), a range ("$10-20") or a bare 0 leaves the price out; the ticket link stays. Free events are priced 0 and marked isAccessibleForFree.
    • Place: the most specific schema.org type its categories name, such as Restaurant, BarOrPub, CafeOrCoffeeShop, Museum, ArtGallery, Park, Store, Hotel or NightClub, else LocalBusiness (change it with vibemap_schema_place_type); address, geo, phone, a price range in the local currency's symbol ("$$", "££") for businesses only, aggregate rating, social links as sameAs, and openingHoursSpecification. Hours come from the synced hours, else from hours text such as "Mon–Thu 11:00 AM–10:00 PM; Fri–Sat 11:00 AM–Midnight"; text that doesn't parse completely is left out, since a partial week would read as closed days. A place marked closed gets no hours.
  • Utility pages stay out of search results. /vibemap-search/, /shared-list/, a series page that isn't indexable (see Recurring events), and pages built around a visitor's My List or bookmarks (the block or shortcode with little else on the page, never the front page) get noindex, follow: in the robots meta tag, in Yoast's and Rank Math's, and as an X-Robots-Tag header. Those pages are also left out of the WordPress and Yoast sitemaps. The vibemap_noindex filter changes the decision.
  • In URL image mode, Yoast, Rank Math and The SEO Framework pick up the CDN image for their sharing tags automatically.
  • Taxonomy archive titles come from vibemap_{place|event}_{category|vibes|tags}_title, where [TERM] is replaced with the term name.

AI search & discovery

Three settings under Settings → AI search & discovery, all on by default, help search engines and AI assistants find, read and cite your own pages.

  • /llms.txt (llmstxt.org): your site name and tagline, then links to the events and places archives, the next 20 events on now or still to come (one per series, with date and venue; an exhibition stays listed for its whole run, by the same end-date rule as the listings), the date pages (Tonight, Today, This Weekend, This Week, then up to 10 category and neighborhood ones), up to 10 indexable series pages with their schedule and next date, up to 20 places (featured first, closed ones left out), the largest event and place categories and neighborhoods, the home page and every page with a Vibemap block, the RSS feeds and the sitemap index (Yoast, Rank Math or core). Hidden single pages and term archives are left out. It is cached for 15 minutes. A physical llms.txt, a rewrite rule another plugin registered for it, or Yoast's or Rank Math's own llms.txt always wins.
  • Markdown pages: every published, unprotected event and place page has a Markdown copy at <permalink>.md (with plain permalinks, ?vibemap_format=markdown), and, when the vibemap_markdown_negotiate filter returns true, answers at the page's own address in Markdown when a request prefers Accept: text/markdown (off by default: caches that ignore Cache-Control would otherwise serve Markdown to browsers). The copy lists the facts first (when, where, price, tickets, organizer, categories; for places the address, hours, phone, website, rating and upcoming events there), then the description, and names the page as its canonical address in a Link header. The page's head links its copy with <link rel="alternate" type="text/markdown">. Hidden singles get no copy, and their .md address answers 404.
  • IndexNow: when an event or place is published, changes a field its page shows (title, description, address, dates, venue, price, tickets, hours, closure), changes its address or is removed, its URL (and the archive's, on publish or removal) is queued. WP-cron sends the queue about a minute later to api.indexnow.org, which shares it with Bing, Yandex, Seznam, Naver and Yep, in batches of up to 10,000 URLs, retrying twice on a rate limit or server error. A sync that rewrites a post with the same values sends nothing. The key file is served at /<key>.txt; the settings screen shows it and the last batch's result. Nothing is sent from staging or local sites, or when Discourage search engines is on.

Calendar and event feeds

Two more settings in the same section, both on by default.

  • Calendar feeds: iCalendar (RFC 5545) at <event permalink>.ics for one event, and at ?vibemap_format=ics on the events archive, an event category, vibe, tag or neighborhood page, and a /shared-list/ address (with plain permalinks, the single event takes the query argument too). The archive and term feeds hold upcoming events by start, up to 500, plus the last 30 days of ended ones so subscribers keep what they went to; an event with no end time ends when it starts, as in the listings, so it stays 30 days too. Drafts and password-protected events are never included. Times carry the venue's time zone, else the event's (vibemap_event_timezone, the one the sync writes) (TZID with a VTIMEZONE built from PHP's zone data; zones without a name go out in UTC), all-day and "times vary" events are dates, a guessed end is left out rather than shown, and a series created in WordPress carries its RRULE, EXDATE and showing length. Synced recurring events are one entry per showing. Each entry has a stable UID, the venue as LOCATION and GEO, the page as URL, STATUS:CANCELLED when cancelled, and the description, price, tickets and organizer as text. A shared list adds each place at the time the visitor scheduled it. Responses send Cache-Control (10 minutes for an event, 15 for a feed), an ETag that answers If-None-Match with 304, Last-Modified and X-Robots-Tag: noindex. Each of those pages links its calendar in the head with <link rel="alternate" type="text/calendar">, /llms.txt lists the events calendar, and an event's Markdown copy links its .ics.
  • Events RSS feed: /event/feed/, its Atom twin and each event term's feed list upcoming events by start date instead of by publish date, each series once at its next showing, without password-protected events, as many as Settings → Reading allows. Each item carries the RSS event module (ev:startdate, ev:enddate, ev:location, ev:organizer, ev:type) and a georss:point, and its text opens with the date and place. Namespaces another plugin already declared are not declared twice. The feed's Last-Modified also moves when an event drops off, after its end or, with no end time, its start, so a reader's conditional request does not keep a stale copy, and it sends Cache-Control: public, max-age=900.

Error reports

Settings → Features → Send Error Reports (vibemap_enable_error_reporting, on by default) lets the plugin send its own errors, such as sync and API failures, to Sentry. The plugin ships with no DSN, so nothing is sent until you set one with VIBEMAP_SENTRY_DSN, the vibemap_sentry_dsn_option option or the vibemap_sentry_dsn filter. A report carries the error and stack trace, the request URL without its query string, your site's host, the plugin, WordPress and PHP versions, your organization slug, and details of the failed Vibemap API call, which can include event and place names, addresses and descriptions. Email addresses are removed, credential-like keys are replaced, the user is cleared, every text value is capped at 1,000 bytes, and errors whose stack trace doesn't pass through the plugin are dropped. To send nothing, untick the setting, return false from vibemap_error_reporting_enabled, or define VIBEMAP_SENTRY_DSN as ''.

AI crawler access

Vibemap → AI Crawlers answers "Can AI crawlers reach this site?" for 18 AI crawlers and robots.txt tokens from OpenAI, Anthropic, Perplexity, Google, Apple, Common Crawl, ByteDance, Meta, Amazon, DuckDuckGo, Mistral and Cohere. Run checks does the following from your own server, one crawler per request:

  • Reads /robots.txt at the root of your domain and applies each crawler's rules (RFC 9309: its own group, else User-agent: *; the longest matching rule wins) to a recent event page, a place page and both archives. A blocked path names the line that blocks it and where to change it: the robots.txt file, Yoast, Rank Math, a plugin or Cloudflare's managed robots.txt. A robots.txt that answers a server error blocks every crawler.
  • Requests the event page as a normal browser and as each crawler, and reports a block only when the crawler is refused and the browser is not. It recognizes Cloudflare challenges and block pages, Sucuri, Wordfence and SiteGround's captcha, and also checks Discourage search engines and noindex on the sample page. Google-Extended, Applebot-Extended and anthropic-ai are robots.txt tokens no crawler sends, so only their robots.txt rules are checked.
  • A blocked AI search or on-request crawler (OAI-SearchBot, ChatGPT-User, Claude-SearchBot, PerplexityBot and others) fails; a blocked training crawler (GPTBot, ClaudeBot, CCBot and others) warns, since many sites block training on purpose.

The requests come from your server's address, not the crawlers', so firewall rules that verify a crawler by its network address, such as Cloudflare's AI bot blocking, can still treat real crawlers differently. Results are kept for a week. Only administrators can run the checks.

The page also counts AI crawler requests to event and place pages, their archives and terms, the plugin's own views, /llms.txt and pages with a Vibemap block or shortcode: one number per crawler per day for 30 days, in the vibemap_ai_bot_hits option (not autoloaded). It stores no IP addresses or user agents. Requests a page cache answers never reach WordPress, so they aren't counted, and counts are by user agent, which anyone can claim.

Visitor data

My List and the legacy bookmarks are stored in the visitor's browser (localStorage keys vibemap_collections and vibemap_bookmarks). Nothing is stored server-side. Add Event Form submissions go to Vibemap. Notification emails are sent through Vibemap's email service, or through wp_mail as a fallback.

Deactivate & uninstall

Deactivating removes the scheduled jobs and flushes rewrite rules. Your settings and content stay in place.

Deleting the plugin removes:

  • every vibemap_* option, including the API key, the webhook key and the organization data;
  • all vibemap_* transients;
  • all Vibemap Action Scheduler jobs.

It keeps:

  • all place and event posts, their meta, and their terms;
  • downloaded Media Library images;
  • the vibemap_sync_logs/ and vibemap_audit_logs/ folders in uploads/, and any older copies in wp-content/;
  • transients held in a persistent object cache.

To remove everything, run Clear All Events / Places and wp vibemap media purge before you delete the plugin, then delete any posts you authored in WordPress yourself: Clear All keeps them.

Changelog

Changes are described from the point of view of a site running the plugin. Action marks changes you may need to act on: settings, meta, routes, templates, script names, or sync behavior.

4.5.0 November 17, 2026

Action needed

  • Action See which cards visitors saw and where they clicked — Embeds and plugin blocks now report cards seen (item_impressions: a card counts once per page view after a second half on screen, and item_count adds up to cards seen), Load More, and Facebook, Instagram and X link clicks. Every item click says where it came from (source: a grid card, map pin, list row, carousel slide or calendar entry) and its position_in_list, so map pin clicks no longer look like card clicks. Ticket and event link clicks (event_link_clicked) now send the destination's host (outbound_host) and link type instead of the full address, which can carry personal details: if your Tag Manager reads url from that event, read outbound_host instead. The Embeds analytics guide explains how to count cards seen and ticket clicks.
  • Action Embed SEO helper for sites that use the Vibemap embed script — The helper prints your embed's events and places into your page's own HTML, as structured data and as a listing that shows in the embed's spot until the live embed loads. It also gives each event-details page its own canonical and share (Open Graph) URL under Yoast, Rank Math, All in One SEO, SEOPress or The SEO Framework, keeps the empty event-details page out of search results, and publishes a sitemap of every item page, so search engines and AI assistants that skip JavaScript can read them. It counts AI crawler visits to those pages, shown on its settings page or, with the Vibemap plugin, under Vibemap → AI Crawlers. Install it, map your calendar and event-details pages under Settings → Vibemap Embed SEO, then clear your page cache.
  • Action Form instructions and custom CSS are limited to safe formatting — The Add Event and Add Place forms now show instructions and your theme's intro message with basic formatting only: paragraphs, line breaks, bold, italic, underline, lists, headings (h3 to h6) and http, https or mailto links. Other tags are dropped and their text kept; images, frames, forms and scripts are removed. Custom CSS on the forms and the offer-update page can no longer import style sheets or load images or fonts from a URL. If your form instructions use other markup, rewrite them with these tags.
  • Action Ended events keep their page for six months, then redirect — An event that has ended no longer disappears: its page stays up with a "This event has ended" notice that links to the next date, the venue or your events page, so links and search results keep working. It leaves your event lists, search, sitemap and term counts as before. After six months the event is removed and its address redirects to the series, the venue or your events archive instead of showing "page not found". On sites that get Vibemap updates by webhook, an event taken down after it ends is removed straight away. Event lists your theme, a page builder or a widget builds (an Elementor Loop Grid, say) leave ended events out too, on the page and when a visitor loads more. To list them there, turn on Show ended events in theme and page-builder lists under Vibemap → Template Settings → Events. Developers can keep ended events in one list with 'vibemap_exclude_past' => false, and change the six months with the vibemap_past_event_retention_days filter.
  • Action Extra rows in a map's phone panel are now opt-in — On phones, the panel that slides up over the map shows one list of everything by default, and featured items no longer add a Featured row above it. To bring the Featured row back, or to add Ongoing events or Top 3 categories rows, open the map in the Hub map builder, go to On phones → Sliding panel and pick them under Extra rows.
  • Action Vibemap's styles load only where Vibemap content appears — The shared Vibemap stylesheets (about 420 KB with the map styles), the notification and dialog helpers, and with them jQuery, used to load on every page of your site. They now load only where a Vibemap block, shortcode, widget or Event/Place page appears, and the map styles only where a map can show. Analytics loading is unchanged. If your theme or custom code relies on Vibemap's styles or helpers elsewhere, add add_filter('vibemap_force_load_assets', '__return_true'); to restore the old behaviour.
  • Action Calendar files and subscribable calendars for your events, and an events RSS feed in date order — Every event page now offers an .ics file, and the events archive, each event category and each shared list can be subscribed to in Google Calendar, Apple Calendar or Outlook, with times in the venue's time zone and repeating events kept as a series. The event page's Add to Calendar menu downloads that file, so Apple Calendar and Outlook get the right time wherever the visitor is. The events RSS feed now lists upcoming events by date, each series once, with every event's date and place. If you send new-event emails from the RSS feed, turn off Settings → AI search & discovery → Events RSS feed to keep the newest-published order.
  • Action Tonight, today, this weekend and this week pages for your events — Your site now has /event/tonight/, /event/today/, /event/this-weekend/ and /event/this-week/, plus the same four under each event category and neighborhood, so people and AI assistants searching "things to do this weekend" land on your domain. Each page lists the events in that window with an intro sentence, links to every event, and its own title, description and sitemap entry; past events never show. They are on by default: turn them off or rewrite the intros in Settings → Vibemap → Date landing pages. If a full-page cache keeps pages longer than an hour, shorten it for these pages, since tonight's list changes through the evening.
  • Action Recurring events get a series page search engines can index, and each date its own listing — A recurring event's series now has its own address, such as /event-series/open-mic/, with its own title, schedule and upcoming dates in its description and structured data, under Yoast, Rank Math and other SEO plugins too, and it appears in the sitemap: WordPress's own, or Yoast's or Rank Math's events sitemap. Each date keeps its own page, now with its date in the page title, so search results tell the dates apart. Links to the old /event-series/?vibemap_id= address redirect to the new one; update menus, buttons or custom code that build that address so visitors skip the redirect.
  • Action Event and place listings arrive with their cards in the page — The Events grid, Combo, Card Carousel and Taxonomy Archive blocks now send their first page of cards in the page's HTML: each title links to its page on your site, with dates and photo, plus the category, venue and address when the cards show them. Search engines and AI assistants that don't run JavaScript can read and follow them, and visitors see real cards instead of a loading placeholder. A Combo that opens on its calendar starts with a list of upcoming events by day, and a Combo with a boundary sends only the places and events inside it, as the live map shows. Past events stay out, as they do in the live listing. The interactive listing now sits inside .vibemap-react-root, so theme CSS that reaches it with a child selector (.wp-block-vibemap-native-events > div) needs a descendant selector. A full-page cache now holds these cards too: keep its lifetime for event pages to an hour or less so search engines see current events.
  • Action AI assistants and search engines find your events and places faster — Your site now serves an llms.txt that lists your event and place archives, events on now and coming up, the Tonight and This Weekend date pages, recurring events' series pages, places, categories, Vibemap pages, feeds and sitemap. Every event and place page also has a Markdown copy at its address plus .md, and Bing and other IndexNow search engines hear within minutes when an event or place is published, changed or removed. All three are on for every site, including sites that already run the plugin once they update. To turn one off, untick it under Vibemap → Vibemap Settings → AI search & discovery. Staging sites, local sites and sites set to discourage search engines never notify IndexNow.
  • Action Event and place pages get a meta description and sharing tags — Single event and place pages now carry a description that leads with the date and venue, so search results and AI answers show when and where. With Yoast, Rank Math, SEOPress or The SEO Framework, a description you write in that plugin still wins; otherwise this one replaces the plugin's excerpt-based description and its Open Graph and Twitter descriptions, so link previews show the date and venue too. All in One SEO keeps its own unless it has none. Without an SEO plugin, the page also gets Open Graph and Twitter tags for link previews. Synced events and places get an excerpt from their description as they next sync, and an excerpt you edit is never overwritten. If your theme already prints its own description or sharing tags, turn this off under Settings → Features → Meta Description & Social Tags.
  • Action Richer search data for events and places, in the right currency — Event pages now tell search engines the full venue address, the performers, the organizer's website, the ticket link, and whether the event is postponed, rescheduled or moved online, with the event photo cropped to the three shapes Google asks for. Place pages name what the place is, such as a restaurant, bar, museum, park or hotel, and list their opening hours. Prices carry the currency of the venue's country instead of always US dollars, and a price is left out rather than shown in a currency that might be wrong. If your events are mostly outside the country your site language names, set the currency under Settings → Features → Currency for Prices.
  • Action Search engines see your site as the publisher, and what each archive lists — Event and place pages now name your site as their publisher and carry breadcrumbs (Home › Events › the page), and event and place archives list the events and places they show, so search engines and AI assistants can read them. With Yoast SEO or Rank Math this joins their structured data instead of adding a second copy. If you turned off Settings → Features → Emit Structured Data (schema.org) because Yoast or Rank Math already printed schema, you can turn it back on.
  • Action Event, place and series pages arrive with their content in the page — The title, dates, venue address, description, hero photo and a short "Event details" summary (when, where, cost, tickets) are now in the page's HTML. Search engines and AI assistants that don't run JavaScript can read them, visitors see the real page instead of a loading placeholder, and the hero photo loads first. Canceled events now say so on their page. The block's interactive layout now sits one level deeper, inside .vibemap-react-root: if your theme styles it with a child selector such as .wp-block-vibemap-single-event > div, switch to a descendant selector.
  • Action Dates, addresses and card titles are marked up for search engines — Event dates and times on cards, detail pages, the calendar and offers now carry machine-readable dates with the venue's time zone, venue and place addresses are marked as addresses, and card titles are third-level headings (they were fourth-level), so each page keeps a single main heading. Nothing looks different. If your site's custom CSS styles card titles through an h4 selector, change it to .sing-card .title.

New

  • Day of the week on date badges — Event date badges can name the weekday ("Fri Nov 13"), as the legacy site did. In the plugin, tick "Show the day of the week on event date badges" in Template Settings or a block's card settings. Add showDayOfWeek=true to a grid, carousel or map-grid embed, flip "Day of the week on date badges" in the Hub builder, or set the events.showDayOfWeek theme override to cover every calendar.
  • See whether AI crawlers can reach your site — The new Vibemap → AI Crawlers page checks your robots.txt and your firewall for each AI crawler, from ChatGPT search and Claude to Perplexity and Common Crawl, flags anything that keeps your events and places out of AI answers, and says how to fix it. It also counts AI crawler visits to your Vibemap pages over the last 30 days, without storing IP addresses or other visitor data.

Improved

  • The Add Event form shows up sooner — Its date and time pickers now load alongside the form rather than before it, so the browser has about a quarter less JavaScript to get through before the form appears. The pickers follow a moment later, and if they can't load, a plain date and time field takes their place so the event can still be submitted.
  • Load More counted in the map view's list — Scrolling the map view's list to load more places now sends load_more with how many cards show, as grids already do, so list depth shows in your reports.
  • Map and list cards are real links search engines can follow — Every card with a page now links to it, including map sidebar cards set to open in the panel: a plain click still opens the panel, while Ctrl/Cmd-click opens the page in a new tab. The save button and "See more dates" sit beside the card link instead of inside it, and screen readers announce the save button with the item's name.
  • Card photos download once, and off-screen ones wait — With smart cropping off, every card used to fetch its photo a second time just to measure it, even far below the screen. Cards now measure the photo they show, so grids and carousels load less and their first images appear sooner.
  • Past events no longer crowd the Vibemap Events screen — The screen always opens on Upcoming, in its usual date order, and the status counts beside it (All, Approved, Pending) count only the events in the view you are on. Past (newest first) and Any date sit beside them with their counts; the screen goes back to Upcoming each time you open it. A search from Upcoming still finds events of every date, and the trash shows them all.
  • The first cards' photos and the detail-page photo load first — Grids, carousels, lists and map sidebars fetch the photos of the cards a visitor sees first right away, ahead of everything else, instead of waiting until the page has laid out; cards further down still load as they scroll into view. A detail page with a single photo keeps its space while the photo loads, so the text below no longer jumps down when it arrives.
  • Map detail panels mark their dates and addresses — The panel that opens from a map pin now tags its date as a date, in the venue's time zone, and its address as an address, as event pages already do, so search engines and assistants read them reliably.
  • A lighter analytics script on every page — The small script Vibemap loads on each page of your site is about a third smaller and no longer pulls in React. Page-speed measuring now loads only on pages that show a Vibemap block, and Vibemap's own usage reporting only once it is switched on.
  • Lists that hide ongoing events load faster on large sites — On a site with thousands of events, lists and carousels with Hide ongoing events on now load in a fraction of the time. They show the same events in the same order.
  • Search, shared-list and My List pages stay out of search results — The site search results page, shared lists and pages built around a visitor's My List or bookmarks now ask search engines not to index them, while still following their links, and they are left out of the sitemap. Ordinary pages, including a home page with a My List block, are unaffected.
  • Event cards show your theme's colours from the first paint — Event grids, archives, combos and carousels now draw their cards with your Vibemap theme's accent colour, title colour, badge text and photo setting as soon as the page loads, instead of switching to them a moment later. The plugin keeps a copy of your theme, which a page never waits on. Each visit still checks Vibemap for a newer version once the page has loaded, so a change you make in the Hub shows on your next visit; the plugin also refreshes its copy every 15 minutes and clears WP Rocket, LiteSpeed, W3 Total Cache, SiteGround and WP Engine page caches when your theme changes.
  • Pages with several Vibemap blocks load less JavaScript — Code the blocks have in common now ships once and is shared between them, instead of being copied into every block. A page with an events grid and a carousel loads about a quarter less JavaScript, a page with three blocks about half, and moving from one Vibemap page to the next reuses what the browser already has. The block editor loads about half as much Vibemap code.
  • Event dates, venue addresses and the main photo are marked up for search engines — An event page's date is a machine-readable date, the venue's location is marked as an address, and the main photo loads first and at its real proportions, which speeds up the page's largest image.
  • Text shows while a map theme's font loads — Pages and blocks styled by a custom theme font now show their text right away in a fallback font, then switch to the theme's font once it arrives, instead of staying blank for up to three seconds on a slow connection.

Fixed

  • Maps show in the block editor on WordPress 7.1 — WordPress 7.1 always draws the post editor in a frame, which kept the Places map and Combo blocks from drawing their map while you edit. They draw, drag and zoom in the editor again; your published pages were never affected.
  • Event lists no longer wait on Vibemap for venue details — When an event's venue isn't one of your synced places, the plugin used to fetch its address from Vibemap while the visitor (or a search crawler) waited, one event at a time, so a list of 50 events could take most of a minute. Lists now answer at once from what your site already has and fill in missing venue details in the background.
  • The block editor's event picker works on sites with thousands of events — On large sites, the list of events the editor loads for picking and filtering ran out of memory and failed. It now loads in small pieces and stays light however many events you have.
  • Changing an event's venue now sticks — Saving an event with a new address moves it to the venue at that address instead of snapping back to the old one. When no venue is there yet, the form asks you to pick one nearby or give the new venue a name, rather than saving a venue named after the street address, and it tells you plainly if the venue didn't change.
  • Add to Calendar saves the right time wherever the visitor is — Google Calendar, Outlook and Yahoo now get the event's time in the venue's time zone, so a visitor in New York who saves a 7 PM show in San Jose sees 10 PM Eastern, not 7 PM. On WordPress, an event with no time zone of its own uses the site's, as the site's calendar file does. Apple Calendar gets the event's calendar file, which carries the venue's time zone and a repeating event's schedule; where the site serves no file, the button builds one with the right time. A show of a series saves that show, and a series saves one show's length rather than the whole run.
  • Names with apostrophes and ampersands read correctly everywhere on a card — A name such as "Ruth’s Table" or "Morris Arboretum & Gardens" now reads the same in the card title, the image description screen readers announce and the first HTML a page sends, instead of showing the code for the character.
  • Add Event Form honors its submit-button position and dialog setting — submitButtonPosition=bottom (the block's Bottom (Inline) option) now leaves the submit bar at the end of the form instead of always pinning it, and inDialog (In Dialog Mode) now lets a form in a dialog size to its content instead of filling the window.
  • Add Place form sends tags, vibes and categories intact — Picked tags, vibes and categories arrived split into fragments; they now reach your directory as chosen.
  • An expired event Edit link explains itself instead of opening a blank form — Opening an emailed Edit link after the event has ended now says the link has expired and offers to submit a new event, instead of showing an empty form that would create a duplicate. If the event can't load because of a connection or server error, the form offers Try again.
  • The suggested end time sticks, and imported venues match more reliably — Clicking OK on the end time the event form suggests (start plus one hour) now keeps it, instead of saving the event with no end time. Events imported from pasted text use their address to find the right venue again. Scraped page text is no longer used as a venue name, and merged duplicate venues are no longer suggested.
  • All-day events stay on their own day for every visitor — An all-day event sorted and ended by UTC's clock, so a visitor in the Americas saw it under the day before and lost it from the list a day early, and a visitor east of UTC saw it after that day's morning events. Lists, carousels and date filters now read it as the venue's day, as the server-drawn cards already did.
  • An event with no end time keeps a blank end — Editing it no longer fills the end with the start time, and adding dates to a repeating event with no end leaves their end blank too.
  • Events with no end time show only their start — On maps, lists, cards and event pages, an event whose end time is unknown no longer displays a made-up end such as "11 AM – 2 PM", and it stays in upcoming lists for three hours after it starts instead of 90 minutes. Events can be created or copied without an end, and a saved end can be removed in the event form, or in WordPress on sites that send edits to Vibemap. In the Hub, the events list, CSV export and review dialog show no end for them. In WordPress, an event saved without an end stays on the calendar.
  • A map that fails to draw shows a proper retry panel — When a map cannot render its style or layers, the "Map preview unavailable" message is now centred in a bordered panel with a real "Try reloading map" button, instead of unstyled text on embeds and WordPress pages.
  • Every listing without a photo shows the same artwork — Places and events with no photo, a broken photo or a photo hidden by their membership level now show your theme's placeholder image, or else the no-photo pattern you picked, on cards, photo map pins and calendars, and in the details panel of a listing with no photo. A photo hidden by membership level never shows on the map. Listing pages without a working photo still open without a header image. "Artwork when a listing has no photo" now applies to the whole map, not only grid cards. When someone shares a listing without a photo from your map, the preview shows your logo on the branded pattern if your theme has one.
  • Calendar-first Combos go straight from the event list to the month grid — A Combo that opens on its calendar no longer flashes a blank box between its list of upcoming events and the calendar.
  • Back returns to the card you opened in a Combo's grid — Open an event or place from a Combo's grid, press Back, and the card you left is where it was, with as many cards loaded as before, instead of shifted up or down the page. On a page with an Events grid and a Combo, Back returns to the card in the block you opened it from, even when both list the same event. On a map, Back works as it always has.
  • Event cards show times in the event's time zone — Cards in the Events grid, Combo, Card Carousel and Taxonomy Archive now read an event's own time zone when its venue has none, so a visitor in another zone sees the same time the event page and search results show.
  • Event grids and carousels no longer jump when the live version takes over — The Events grid, the Taxonomy Archive, a Combo opening on its grid and the Card Carousel send their first cards in the live block's own layout, with the same filters bar, item count, Load More button and empty-list message, so when the interactive block replaces them nothing on the page moves, on desktop or phone. Filter rows match the live grid even when only later items carry a tag or vibe, and cards wait for the bookmark setting so phone titles do not rewrap. The archive's map keeps its height while it loads instead of collapsing for a moment, and on phones it now uses the block's mobile map height. A listing sorted at random, or with hand-picked items first, shows the same items before and after the live grid loads; a random order holds for half an hour, as it did before. If the live grid cannot load, or JavaScript is off, the first cards stay without a Load More button that would do nothing.
  • Events without a photo no longer get a gradient as their featured image — Sync stops importing Vibemap's decorative "no photo" gradient as a featured image and hides the ones it imported before. A one-time background cleanup after the update then detaches them from your events and places; copies already downloaded stay in your Media Library, unused. Real photos and images you set yourself are never touched.
  • Search results page no longer lists every filter pill — A search from the site's header, or a link straight to the results page, shows the 10 most-used event and place categories instead of every term of every taxonomy. A search started from the Search & Filter block carries that block's filter settings to the results page again.
  • The map's filter panel scrolls on phones — On a narrow map, the open filter panel now stops at 70% of the screen height and scrolls, so "Show results" stays in reach. A custom theme's font now also reaches empty-result messages, map legends and the map's loading message, and styles no longer change between releases that did not touch them.
  • The submission limit message gives the right wait — After too many event or place submissions, the forms said to wait a minute. The limit is hourly, so they now say to try again later.
  • The Taxonomy Archive block honours "Items shown initially" — It shows the number set on the block, or in Template Settings → Grid Defaults, then Load More. It always showed 99, so sites with a Grid Defaults value will now see it apply to this block too.
  • Vibemap no longer loads Google Fonts on every page — Vibemap's stylesheet fetched a Google Fonts stylesheet first, before any other style, on every page with a Vibemap block or embed, for one theme's titles. A theme's font now loads only on pages that use that theme. The Clermont and Women's Wave themes now show Montserrat as designed.
  • Phone-width grids, maps and carousels open on their phone layout — An events grid on a phone, a Combo or map in a narrow column, or a card carousel measured its width a frame late, so it first painted desktop cards, the desktop header, a map sidebar or too many slides, and then jumped. Each now measures before its first paint.
  • Venue checks read street names like Stevens Creek correctly — When the event form compares the address you entered with the venue it was saved at, it no longer drops words that begin like "Ste", "Unit" or "Apt" (Stevens, Unity, Aptos), and it keeps five-digit house numbers instead of mistaking them for ZIP codes, so it warns only when the addresses really differ.

Security

  • Analytics keep links to the page, not their query strings — A website link click now reports the site's address without its query string, which can carry an organizer's or a visitor's details, plus the site's host as before. Vibemap's own usage reporting keeps only campaign tags (utm_…) from page addresses, so a search on your site never leaves it.
  • Descriptions can no longer run scripts — Event, place and series descriptions are cleaned before they render on detail pages, embedded single pages and map panels, so markup copied from another website can't run code or restyle your page. Formatting, images and links stay.

4.4.5 November 5, 2026

Fixed

  • Places syncs no longer lose their first page on WP Engine — When the sync's saved copy of page 1 comes back empty, the plugin fetches that page again, so the run processes every item and cleanup is no longer blocked by a one-page deficit.

4.4.4 November 5, 2026

Action needed

  • Action Events with no end date stay on the calendar — When Vibemap sent an event without an end date, as it does for open-ended series, the sync blanked vibemap_event_end_date and every events query then hid the event. The sync now fills in an end (a series' last listed or next occurrence, otherwise start plus 3 hours; 23:59 that day for all-day and "times vary" events), records it in _vibemap_event_end_date_filled, and never sends it back to Vibemap through write-back. Events blanked by earlier versions are repaired on the next sync.

New

  • Events can say "Times vary" instead of a start time — For events whose date is fixed but whose start time isn't, such as shows at different times each day, the event editor sidebar has a Times Vary checkbox beside All Day, and the Add Event Form offers Specific times, All day and Times vary; cards, the map details panel and single event pages then show "Times vary". The flag syncs into vibemap_event_times_vary, goes back to Vibemap with write-back, and makes the event's JSON-LD carry dates only, as for all-day events.

Fixed

  • My List works fully with analytics off, for editors and on staging — The script behind the My List save toast (vibemap-collections-init) now loads on every front-end page. Before, it loaded only where the analytics script loaded. Without it there was no save toast, the event feed shortcode, mini-cart and classic templates couldn't save, and My List's share dialog linked to /wp-login.php instead of your login page. That hit every site with analytics turned off, and since 4.4.0 logged-in editors, previews and non-production sites too.
  • "Only show passed-in taxonomies" works on Places and Combo blocks — With the setting on (onlyShowPassedTaxonomies), the filter chips on Places and Combo blocks now show only the categories, vibes and tags the block is set to; before, the setting did nothing there. On every block, including Events, a row with no terms configured keeps all its chips instead of going empty. Whether a row shows at all is still up to the block's filter toggles.
  • Syncs no longer skip their first page on hosts with a persistent object cache — The sync kept each run's first page of results in a transient. With a persistent object cache, as on WP Engine, a transient lives only in that cache, and a page larger than the cache's item limit came back empty, so the first page's items were never processed. The first page now goes in a non-autoloaded option.
  • Single event pages show the right dates in the When card — A series page showed the whole run as one span ("Nov 12 – Dec 10 · Thu 7:30PM – Thu 9:30PM"); it now shows the current or next occurrence with its own times. More dates lists one chip per day with that day's times. Single pages of synced events also list their other dates again, which had been dropped.

4.4.3 November 4, 2026

Improved

  • Map details show "Translating…" while a description is translated — With the Vibemap Translate add-on, opening a place on the map in another language left the description blank for the few seconds translation takes. The details panel now shows a "Translating…" placeholder until the translation arrives: in the visitor's language with Vibemap Translate 0.3.2 or later, in English with older versions.

4.4.2 November 3, 2026

Action needed

  • Action Category archives can show subcategory filter chips — Template Settings → Archives has a new Show Category Filter setting (vibemap_category_archive_show_category_filter), off by default; turned on, place and event category archives show the category's subcategories as filter chips, and visitors stay inside that category. It works through the plugin's PHP archive templates, which classic themes use, so a theme that overrides taxonomy-vibemap_place_category.php or taxonomy-vibemap_event_category.php must pass showCategoryFilter from that option itself.
  • Action Filter bars hide internal and location tags — Tag chips no longer offer Vibemap's internal events_feed tags. On event filter bars, location tags are hidden too: tags the API marks as geographic, and tags whose names contain "county", "service area", "BID" or "district" or end in a two-letter state code (", CA"). If your event filters relied on such a tag, check that they still show what you expect.

4.4.1 November 3, 2026

Fixed

  • Combo block's search bar and filter chips are back — From 4.3.1 through 4.4.0, Combo blocks lost their search box, filter chips and date controls, on the site and in the editor. They show again as configured.

4.4.0 November 3, 2026

Action needed

  • Action fetch_all now works only for editors, and the sample routes return at most 12 items — places-data and events-data honor fetch_all only for users who can edit_posts (the block and Elementor pickers) and for WP-CLI; every other request gets normal pagination, because one anonymous fetch_all could take seconds and hundreds of MB on a large site. sample-places and sample-events clamp limit to 1–12. If your own public code relies on anonymous fetch_all, page through the results, or allow it with the new vibemap_rest_allow_fetch_all filter.
  • Action Analytics no longer counts editors, previews or staging sites — The Vibemap analytics script now skips logged-in users who can edit_posts, post previews, the Customizer, any site whose wp_get_environment_type() isn't production, and localhost, .local and .test hosts; ?analytics=off turns tracking off for that page view. To track one of those requests anyway, return false from the new vibemap_analytics_skip_request filter. The My List save script (vibemap-collections-init) follows the same rule, so editors, previews and staging sites don't get the save toast; check My List logged out on your production site.
  • Action Vibemap Add Event Form takes its required fields and header color from your Hub theme — Required Fields (requiredFields) now defaults to empty, which uses the event form's required fields from your Vibemap theme and falls back to name, start_date and description when the theme sets none. Blocks that never changed the setting now follow the Hub; set Required Fields on the block to keep a fixed list. The header color now falls back to the theme's primary color before its accent, as the Hub form does.
  • Action Single event and place pages get a redesigned sidebar — Events lead with a When card (date, time and repeat pattern, with a month calendar for recurring events only), then links, Add to Calendar and Share, and a Where card with a 3D map, the venue, Website and Directions. Place hours say when they change ("Closed · Opens Fri 11 AM"), here and in the map details panel, and both page layouts drop to one column below 992 px. Separate Date and Time (vibemap_event_separate_datetime, block attribute separateDateTime) no longer affects the Vibemap Single Event or Vibemap Meta Info sidebar, which always puts date and time on separate lines.
  • Action Elementor widgets can exclude by taxonomy or by post — Exclude By is now a dropdown of Specific Posts and the widget's category, vibe, tag and neighborhood taxonomies, each with its own picker, and widgets that list events or places show the include pickers for whichever type source selects. Shortcodes accept a comma-separated term list in exclude_taxonomies together with exclude_type (for example exclude_type="vibemap_event_category" exclude_taxonomies="music,comedy"), and JSON values are no longer split at their commas. The Elementor editor script is renamed from vibemap-elementor-single-card-picker to vibemap-elementor-item-pickers.

New

  • Single event pages show your event disclaimer — When your Vibemap theme has an event disclaimer, Vibemap Single Event shows it in the sidebar under the date, time and location, or in the main column when the sidebar is hidden.
  • Vibemap Add Event Form can use reCAPTCHA v3 — Define VIBEMAP_RECAPTCHA_SITE_KEY in wp-config.php, or return a key from the new vibemap_recaptcha_site_key filter, and the form loads reCAPTCHA v3 and sends a token with each public submission. The key comes from the server only, so no block or shortcode attribute can set it. With no key, which is the default, nothing changes and no reCAPTCHA script loads.
  • Map details panels show translated place descriptions — With the Vibemap Runtime Translation add-on (0.3.0 or later) active, opening a place in the Vibemap Combo or Vibemap Map (Legacy) details panel shows its description in the visitor's language. The description stays blank until the translation arrives, so English never flashes, and falls back to English if the lookup fails. Lists and grids stay in English, and events translate on their single page.
  • New vibemap_place_feed_includes filter syncs optional place extras — Return extra names (for example salesforce) from the filter and every place feed request, including single-item syncs, asks the Vibemap API for them with ?include=. The sync stores them as JSON in vibemap_place_extra_data. Places synced before you add the filter pick them up on a forced sync (wp vibemap sync places --force).

Improved

  • Maps, cards and filters work with a keyboard and screen reader — Filter chips, map-list cards, carousel arrows, the phone sheet handle, the hours toggle and the vibes Show more toggle now take Tab, Enter and Space and announce their state, and the locate button and view toggles show a focus ring again. Small accent-colored text, such as event badge dates and carousel headers, reads a new optional --vm-color-accent-text CSS variable first, so you can keep a bright accent for fills and set a darker one for text.

Fixed

  • Map and Combo blocks apply filters from the page URL — Vibemap Combo and Vibemap Map (Legacy) now apply ?categories=, ?vibes= and ?tags= (comma-separated slugs or term IDs; category, vibe and tag also work) and ?search= or ?q= when the page loads, and keep those parameters in the URL as visitors change filters, leaving other parameters alone. Links built for Vibemap web embeds work the same way. Set enableQueryParams to false on a block to turn this off.
  • Reviewers get one alert per submitted event — After a successful submission, Vibemap Add Event Form also posted to the failure-alert route, so reviewers received a second email on top of the new-event alert. Only failed submissions use that route now.
  • Vibemap Add Event Form saves what the submitter entered — A description typed or pasted right before Submit now saves, a tag that contains a comma (such as "Lane County, OR") stays one tag, and an image found by event import now saves instead of only showing in the preview. Pasted-text import keeps the event's own date, sends a bare venue name to the venue search instead of the address field, and no longer marks a timed event as all-day. Custom fields assigned to the organizer section now appear, and checkbox custom fields save true or false.
  • A duplicate event submission says "Already listed" instead of "Success!" — When Vibemap already has the event, Vibemap Add Event Form now says Already listed, names the matching event and links to it, so a wrong match no longer reads as a saved submission. Event links after a submission open the event on web.vibemap.com instead of the old vibemap.com page, which redirected to an outdated copy.
  • Event edits keep their approval status and save cleared fields — For signed-in curators, Approval status offers Approved, Pending review and Declined: Pending review now saves as pending instead of declined, and saving an edit leaves the status alone unless you change it. When editing an event, clearing the description, link or price, unticking online, free or all-day, removing the last image, or removing an occurrence now saves.
  • Recurring events keep their pattern in the Add Event Form — Every week now takes several weekdays and saves one weekly rule, and a monthly "2nd Tuesday" pattern keeps its ordinal in the form's summary. Editing a series no longer moves its end date a day later on every save, the first show's End field can only end a series earlier, and an event with a few specific dates no longer reopens as a weekly series that the next save made endless.
  • Blocks keep working with analytics turned off — With Enable Analytics off, the details panel's Back button, the view tabs and the photo gallery threw an error and did nothing. Every tracking call now does nothing when analytics isn't loaded, so these controls work again.
  • Clustered maps honor Marker style and redraw right after filtering — With Cluster nearby markers on, Marker style set to Icons only or Only featured as images now applies; clustered maps showed a photo for every place that had one. Markers also redraw as soon as a filter's results load, instead of waiting for the basemap or an overlay to finish loading or for the next pan.
  • Search runs once you stop typing — The map's search box sent every partial word ("c", "co", "cof") as its own search; it now sends one search 300 ms after the visitor stops typing. The result count says "results" when places and events are mixed, and on phones a taxonomy hidden on desktop no longer appears in the chip row above the map.
  • The phone map sheet stays up when filters match nothing — On phones, a filter with no matches removed the results sheet and left nothing to act on; the sheet now stays and shows the same no-matches message as the desktop list. Its catch-all row is headed "All Places", "All Events" or "All Places & Events" by what it holds, where a places map used to say "All Events", and the locate button now rides above the open sheet instead of hiding under it.
  • Cards and the details panel read more cleanly — Place cards no longer print the address twice. In the map details panel, event prices read "$25" or "Free" instead of a bare number, and a place's website links sit under Links instead of "Main URL". Offer badges stay on one line instead of covering the photo on phones, and small cards drop the word "Available".

4.3.2 October 16, 2026

Fixed

  • Event and place pages no longer overload the database — In 4.3.1, the similar-items lookup ran a query whose cost grew steeply with the number of fields stored on each event, and single pages run that lookup on every uncached view, so crawlers walking event pages could slow a site or take it down. The lookup now runs one indexed query per coordinate pair and returns the same items; sites on 4.3.1 should update.

4.3.1 October 14, 2026

Action needed

  • Action Choose how Similar Places and Similar Events pick their matches — Template Settings has a new Similar Items Matching section for match strictness (Strict, Balanced, Loose), the fields to match on (categories, vibes, tags), a minimum score, a maximum distance and the order. Blocks and Elementor override them with similarStrictness, similarMatchFields, similarMinScore, similarRadiusKm and similarSort, and GET /wp-json/vibemap/v1/similar-items/{post_id} with strictness, match, min_score, radius_km and sort. The default, Balanced (any shared category, within 25 km, best match first), replaces the old rule of a shared tag for events and a shared top-level category for places with no distance limit, so check that your single pages still show the related items you expect.
  • Action Event and place pages no longer 404 when another plugin owns /event/ or /place/ — When another plugin (The Events Calendar, for example) already registers the slug set for Vibemap single pages, those pages move to /vm-event/ or /vm-place/ instead of losing to the other plugin's rewrite rules. The switch happens on the next wp-admin page load and flushes rewrite rules and the API cache itself. Vibemap Settings shows a note under the slug field naming the post type or taxonomy that holds it; enter a different slug there to choose your own URL.
  • Action Legacy sync filters pick from synced terms, and a category filter matches exactly one category — In Legacy mode, the Category, Vibes and Tags sync filters are now dropdowns of the terms already synced into the site, one value each, and a category filter goes to Vibemap as the category's unique slug, so it no longer pulls in other categories that share its plain slug. Saved category text is converted automatically; a value that matches no category, or several, appears in an admin notice and stops that sync until you pick a category in Vibemap Settings. Event write-back also stops sending a Category, Vibes or Tags filter value as the event's editorial category.
  • Action On phones, the map's bottom sheet starts open — The default for Bottom-sheet default state (sheetDefaultState) changes from Peeking to Opened, so the sheet starts expanded. To keep the old behavior, set it to Peeking in Template Settings under Mobile Map & Bottom Sheet, or on the block.

New

  • List blocks warn when their list isn't synced — The Combo, Card Grid, Card Carousel and Map (Legacy) blocks show a warning in the editor, and the Combo block on its canvas too, when a chosen Vibemap list isn't one this site syncs, since the block would have nothing to show. The warning links to Vibemap Settings. The public settings route now returns synced_lists, the place and event list IDs the site syncs.
  • Combo block keeps numbered pins, coverage dots, a scroll hint and base-map colors — New Combo attributes showNumberedMarkers, numberedMarkerStyle, showDots, dotsColor, dotsRadius, dotsOpacity, panHintMode (off, cooperative or custom) and baseMapEdits carry these settings from a Vibemap map builder map into WordPress. They have no sidebar controls: set them in the block code or as shortcode attributes.
  • Single-day events can use the pill date badge, with the start time — Two new event card settings: Use pill layout for single-day event badges (pillSingleDay) shows a one-day event as a pill ("Oct 8"), and Show start time in single-day pills (pillShowTime) adds its start ("Oct 8 · 7PM"). Both are off by default; set them in Template Settings → Events, per block, or in Elementor on any block that shows event cards.
  • Add Event Form handles multiple showtimes — The form's repeat options gain Multiple showtimes, for runs such as a Friday evening show plus Saturday matinee and evening shows. When the form opens an existing event with several patterns or showtimes, it now loads every pattern with its own times. Before, it fell back to a weekly pattern that hid the others and could drop them on save.

Improved

  • Block settings offer only terms synced into the site — The Card Grid's Select Tags, the Add Event Form's Auto Tags and the Place Legend's Match Values (exact-match rows on tags, categories or vibes) now suggest only terms synced into your site and drop typed text that matches none of them. A saved value that no longer matches is flagged so you can remove it.

Fixed

  • Category filters and legend rows match the exact category — Category filters and Place Legend category rows now identify each category by its unique slug, so two categories that share a plain slug (such as Food and Venues › Food) no longer stand in for each other. For developers, place and event payloads from the plugin's REST routes gain category_slugs (each category's unique slug plus its parents), category terms gain slug_unique, and taxonomy-terms responses for the category taxonomies gain category_options.
  • Date badge settings reach every block that shows event cards — The Bookmarks, Single Card, Taxonomy Archive, Single Event, Single Place, My List and Event Series blocks now pass the date badge settings to their cards. Blocks that resolve their settings as places (Bookmarks, My List, Single Place) read the pill layout, single-day pill, pill start time and ongoing "Now" settings from Template Settings → Events, where you set them. The Card Grid's editor preview also follows Template Settings for the pill layout.
  • Saving Template Settings no longer locks in inherited values — Saving an Events or Places tab without changes used to store every row's displayed value as that tab's own setting, so later changes on the Global tab stopped reaching it. Rows you haven't changed now stay inherited. Settings stored by earlier saves keep their values.
  • Single Card block loads its current script — The Single Card block still requested the script name used before 4.2.1, which returned a 404. It now loads the renamed .min.js file.
  • Back returns visitors to where they were in the Card Grid — After opening an event from a Card Grid and pressing Back, visitors return to the same scroll position with the same number of cards loaded, instead of landing at the bottom of the page. Scrolling or tapping during the restore cancels it.
  • Carousels in the map's details panel follow your card settings — The "Events at this Venue" and "Similar Places" / "Similar Events" carousels in a map's details panel now use the same card settings as the block's other cards (vibes, tags, categories, description, subtitles, ratings, badges) instead of their own defaults.
  • Blocks retry your brand theme after a failed load — If loading your organization's theme fails with a network or server error, a block that loads 5 seconds or more later fetches it again, instead of every block using default colors and fonts for the rest of the visit.

4.3.0 October 2, 2026

Action needed

  • Action Events and places follow Vibemap's Approved, Pending and Disapproved states — The sync publishes Approved items, keeps Pending items as pending (hidden from visitors) and moves Disapproved items to the Trash; places used to publish whatever their approval, so a place still Pending in Vibemap now leaves the site. Pending reaches an existing post when the item next changes in Vibemap or on a Force sync. Posts authored in WordPress are never trashed this way, and on a site with EMPTY_TRASH_DAYS set to 0 a Disapproved post becomes a draft instead.
  • Action Approve, Set to Pending and Disapprove from the post lists — Event and place lists offer Approve, Set to Pending and Disapprove as row and bulk actions, and the editor's status labels read Approved, Pending and Disapproved. The event sidebar's Approved for Publishing checkbox is removed; set the post status instead. With write-back on, Set to Pending now sends is_approved: null to Vibemap instead of false.
  • Action Detect sync writes with VibeMap_Sync::is_api_sync_active() — The plugin no longer defines the DOING_API_SYNC constant during a sync, so code that checks defined('DOING_API_SYNC') to skip writes made by the sync no longer sees them. Call VibeMap_Sync::is_api_sync_active() instead. Code that defines DOING_API_SYNC itself is still honored.
  • Action Cleanup moves stale posts to the Trash instead of deleting them — Posts that drop out of the feed are now trashed, so you can restore them, and if the item comes back the sync restores the same post instead of creating a second one. Cleanup never removes Pending posts or posts authored in WordPress. If EMPTY_TRASH_DAYS is 0, cleanup, closed-place removal and webhook deletes refuse to run (webhook deletes answer 409) and a notice on every admin screen says so; set it to a number of days in wp-config.php to let them run.
  • Action A post you trash stays off your site — The sync no longer re-creates a synced post you moved to the Trash, and WordPress's scheduled trash emptying skips it so the removal sticks; restore it from the Trash to hand it back to the sync. Trashing one date of a recurring event now removes only that date from your site and leaves the series published on Vibemap. Trashing a place or a one-off event still disapproves it on Vibemap when write-back is on.
  • Action Clear All keeps posts authored in WordPress — Clear All Events and Clear All Places under Maintenance Tools → Data Management no longer delete posts created in the WordPress editor, and the result says how many were kept. To empty a post type completely, delete those posts yourself.
  • Action Webhooks can sync one item against your lists — POST /wp-json/vibemap/v1/webhook/trigger-sync with type events or places and an id now syncs only that item instead of starting a full sync: it creates or updates the post when one of your selected lists contains the item, and trashes the post when none does, unless removal is prevented. The response gives action (created, updated, removed or noop), post_id, post_status and permalink, or 202 with action: queued when the work runs past about 7 seconds; a failed feed read returns 502 and removes nothing. In Legacy mode it only refreshes posts the site already has, and {"type": "test"} answers {"ok": true, "pong": true}.
  • Action Sync History shows every run, and logs move to the uploads folder — Runs whose cleanup was blocked or skipped now appear in Sync History, single-item webhook syncs get their own rows with a plain-language reason when nothing changed, and Removed is split into past events, stale occurrences and items gone upstream. Sync logs now go to uploads/vibemap_sync_logs/ and audit logs to uploads/vibemap_audit_logs/, because wp-content is read-only on some managed hosts and logs written there were lost; existing sync logs are moved once. Update backup or monitoring scripts that read the old folders, and use the vibemap_log_basedir filter to pick another base folder or return '' to stop writing log files.
  • Action Legacy mode category filters match exactly one category — In Legacy sync mode, the Places and Events category filter now resolves to one Vibemap category, so food syncs Food and no longer also pulls in Venues › Food; a category's display name works too. A slug that several categories share, with none of them canonical (such as yoga), keeps the old merged match. The next Legacy sync may add or remove items that only the merged match covered.
  • Action Place pages show amenities — Single place pages list a place's amenities from Vibemap, with numbers as stat tiles, yes/no amenities as chips and text as label and value; the map details panel shows them as compact chips. They are stored in the new vibemap_place_amenity_feature meta, so run a Force place sync after upgrading to fill it for places that haven't changed in Vibemap. Hide or rename the section with the single-place attributes showAmenities and amenitiesTitle.
  • Action Every map uses your global map stylesheet, and transit has its own setting — Taxonomy archive maps, single-page minimaps and the map details panel now fall back to the global map stylesheet, and a blank Custom map style URL in Template Settings no longer hides it; archive maps with no style set switch from Mapbox Streets to your theme's style or the Vibemap default. Maps used to force transit layers on, which made most custom styles look like the default. The new Transit lines & stops setting (showTransit, stored as vibemap_map_show_transit and vibemap_{post_type}_map_show_transit) defaults to Follow map style, so a style that hides transit stays that way.
  • Action Term archive pages follow the per-type Template Settings — The plugin's category, vibe, tag and neighborhood templates no longer pass the Archives tab and global card options as block attributes, so the Events and Places Template Settings (map height, marker style, columns, card details) now win on those pages, with the Archives tab as a fallback. Event-term archives read the event settings instead of the place settings. If you copied one of these templates into your theme, it still passes the old values; remove them to let Template Settings apply.
  • Action Saving Template Settings without changes no longer changes your site — Settings that inherit by default, such as Default view, Available views and the calendar options, now offer a Default choice that names what they inherit, and saving leaves them unset; a stored value missing from a list stays selected. Before, an untouched save stored the first option in each list, so Combo blocks could start opening on Grid. If that happened on your site, set Default view to First available view on the Events and Places tabs and save.
  • Action Category chips follow a standard destination order — With categories sorted By count (the default), chips now run Food, Drink, Attractions and Arts, Shopping, Sports and Recreation, Music, Family and Community, Stay, then Services, followed by other categories by count. To keep your own order, set Categories sort order to Custom order or Alphabetical in Template Settings. Category and tag renames set in your Vibemap theme now show on filter chips; before, the plugin dropped them.

New

  • Choose what happens when a new place already exists on Vibemap — With place write-back on, saving a new place that matches a Vibemap place opens Is this the same place? instead of linking or merging on its own. Yes — link to it lets you pick Keep mine or Use Vibemap's for each field that differs, and No — create a new place creates a separate one; until you choose, the post stays unlinked with its status unchanged, and Possible match — resolve in the sidebar reopens the dialog. When Vibemap queues your edit for review instead, the editor now says so and links the post rather than re-submitting it on every save.
  • New Send Error Reports setting — Vibemap Settings → Features has a Send Error Reports checkbox, on by default, that lets the plugin send its own errors to Vibemap with email addresses, credentials, cookies and query strings stripped. No reporting address ships in 4.3.0, so nothing is sent unless you set one with the VIBEMAP_SENTRY_DSN constant. To turn reporting off in code, define VIBEMAP_SENTRY_DSN as '' or return false from the vibemap_error_reporting_enabled filter.

Improved

  • Cleanup checks with Vibemap before removing an event, and caps occurrence turnover — When a whole event leaves the feed, cleanup asks Vibemap about it and removes it only if Vibemap reports it disapproved or gone; it checks up to 100 events per run (vibemap_cleanup_liveness_probe_cap, vibemap_cleanup_liveness_time_budget) and keeps the rest until the next run. If a run would trash more than 250 dropped dates of series still in the feed, cleanup stops and waits for Run cleanup anyway; change the limit with vibemap_churn_removal_max. A blocked cleanup now shows a notice on every admin screen with a link to the posts it would remove, and the button says how many it removes.
  • Combo calendar loads only the months it shows — A Combo block on Calendar view now fetches events for the months on screen, and the next month when a visitor pages, instead of paging through the whole catalog; calendar thumbnails load as small images, and each venue on an events map is fetched once. The filter bar's search box, view toggles and menus no longer use MUI, and its pop-ups load when first opened. The search box keeps its MUI class names, so CSS overrides on .MuiOutlinedInput-root still apply.

Fixed

  • Write-back keeps your venue, tag and series edits — Picking a new venue for an event no longer sends the previous venue back to Vibemap, and the venue search ranks title matches first and marks WordPress places that are Not in Vibemap yet (hide them with vibemap_venue_search_hide_unlinked_wp_places). Unticking Featured on an event now sticks, tag names with & are no longer sent to Vibemap as &amp;, and tags set on one date of a series survive the next sync. Saving an edit to a whole series refreshes its other dates on your site right away, and the post shows Other dates not refreshed if that fails.
  • The editor says what happened after you save — When Vibemap queues a place edit for review, refuses an approval change, or reports the item already exists, the block editor now shows a notice instead of nothing, and the place sidebar shows labels such as Submitted for review instead of raw status codes. A notice also appears when you trash an item and Vibemap keeps it published. The PHP warning Undefined array key "images_total" during single-item image syncs is gone.
  • Add Event Form: pasted images, clearer errors and approval choices that save — Pasting an image into the description is now refused with a pointer to the Images section, and a description over 30,000 bytes is stopped before submitting, instead of the whole submission failing. Errors list the fields Vibemap rejected rather than raw server messages, and a signed-in user's Approval status and an admin's Featured status are now saved with the event. The recurrence editor is more compact, its preview includes dates from every extra pattern, and edits to an extra pattern save even when the main pattern is untouched.
  • Combo block: the Venues toggle switches List and Calendar views, and titles clear the bookmark — Switching a Combo block to Venues while it shows List or Calendar now shows the venue grid, instead of events under a place count. On horizontal cards, titles no longer run under the bookmark star. In the editor, changing Default view now updates the block preview.

4.2.2 September 24, 2026

New

  • events-data takes exclude_ranged. It leaves out ongoing events (longer than 24 hours, or flagged ongoing with no end date) before paging, so total_count and pagination count only the events that are left. An overnight show, such as 8pm to 2am, is kept.
  • events-data start_date and end_date accept relative offsets (+14d, -7d, +3m, +1y), counted in whole days in the site's timezone. ISO dates work as before.

Fixed

  • Card Carousel: turning on Hide ongoing events could leave the carousel empty. Results are sorted by start date, so the first page could be all long-running exhibits, and the filter used to run only on that page in the browser. The server now removes ongoing events before picking the page, and the carousel's Date Boundary Start/End apply to the same query. If the browser filter still leaves the row short, the carousel loads up to three more pages. Carousels with the setting off make the same request as before.
  • Block color pickers now save hex values instead of color objects. This affects the Taxonomy Archive bookmark icon, Search Filter, boundary fill and line colors, and legend colors.
  • Add Event Form: the End field no longer copies the Start value when first opened, which had been creating zero-length events. Recurrence fixes: the first occurrence end shows the correct day, specific-date durations are limited to one day, and dates on the 31st no longer roll into the next month.
  • The "today" marker in the event mini calendar now uses its own color.

Improved

  • Map popups stay open while you hover them and stay pinned on click or tap.

4.2.1 September 3, 2026

4.2.0 was never released.

Action needed

  • Action Block scripts are renamed to *.min.js. This fixes the Add Event block going blank under SiteGround Optimizer. Update any optimizer or CDN rules that match the old .js filenames.
  • Action Place write-back now round-trips. Categories are pulled by unique slug, then name, then slug, and hidden categories are kept. Pushes send category slugs instead of names. New meta _vibemap_place_push_baseline records the last pull, so fields that were blank then aren't pushed. After upgrading, the first push for each existing place sends only fields that have a value.
  • Action Saving a place no longer deletes its gallery. The push sends the featured image first, then the gallery. If WordPress has no images for the place, it doesn't send the images field.

New

  • New setting: Similar items in details panel (showSimilarItems). Set it per block, in Elementor, or in Template Settings → Map (vibemap_{post_type}_map_show_similar_items, vibemap_map_show_similar_items). It defaults to on.
  • Event cards and detail pages show a mini calendar of occurrence dates, plus a compact date badge.
  • Showtimes on the same day are combined into one card with a multi-time badge.
  • Signed-in users can set an event's approval status from the event form.

Improved

  • Embeds load about 450 KiB less JavaScript.
  • Search, filter, date-range and map-zoom analytics events now reach GA4, with real result counts. Before this release they were silently dropped.
  • Merchant edit forms no longer promise a review for edits that are already live. The offer update form has working photo uploads and a pinned preview.

Fixed

  • Tapping a card in the mobile map sheet opens the details panel.
  • The map widget no longer shows an empty sidebar gap at mid-range widths.
  • The recurrence badge no longer covers the date badge.
  • Times display correctly when recurrence patterns have different times.
  • Signed-in curators see the moderation menu in cross-site embeds again, and cards no longer show a false end date.
  • Category filters use the unique slug when it's available.
  • One broken overlay layer no longer turns off every map tooltip.
  • Event "Save As" keeps the venue. City-only event addresses fall back to the venue's street address.

4.1.2 August 20, 2026

New

  • New WP-CLI command wp vibemap media stats|purge removes downloaded Media Library images in bulk. It is resumable and has a dry run.

Improved

  • Large list-backed fetches are capped at 500 items per request. "0" and "1" are read as booleans for shouldCluster and showHeat.

4.1.1 August 19, 2026

Action needed

  • Action This restores the Combo block's post-type setting that 4.1.0 dropped. Under 4.1.0, Combo blocks ignored each site's per-post-type Template Settings, and about 20 defaults (such as shownAtStart) changed on existing Elementor Combo widgets. If you ran 4.1.0, update to this version.

4.1.0 August 19, 2026

Action needed

  • Action Single event and place pages are wider. They now follow the theme's wide-size (falling back to 1200 px) instead of 800 px. To keep the old width, set Template Settings → Global → Single Page Content Width to 800.
  • Action New template hooks vibemap_before_template_content and vibemap_after_template_content (see Templates).
  • Action The sync no longer overwrites posts you authored. Posts now record whether they were created by the sync or by a person. On a collision, the sync skips the post and shows Sync blocked, and editors resolve it from a sidebar panel. New REST routes: link/candidates|compare|apply|unlink. New audit log in wp-content/vibemap_audit_logs/.
  • Action Rescheduled events no longer create duplicate posts. Changing only an event's time updates the existing post. A cleanup pass trashes duplicates that already exist. New meta _vibemap_sync_seen_generation.
  • Action New webhook POST webhook/sync-item refreshes a single place or event. trigger-sync also accepts type: "item".

New

  • Combo List view for events: day headings with horizontal cards. Turn it on under Available views or with ?views=…&defaultView=list.
  • Opt-in "you are here" marker with a compass (showUserLocation, site option vibemap_map_show_user_location). Embed iframes include allow="geolocation".
  • New Mobile Map & Bottom Sheet panel on each block: useLegacyBottomCard, sheetTitle, sheetDefaultState, showInlineChips, inlineChipsTaxonomy, showDateRangePills.
  • Elementor widget controls match the Gutenberg sidebar. New card settings showRating and ratingStarColor.
  • Add Event and Add Place forms can extract details from pasted text, and they select an exact venue match automatically.

Improved

  • subtitle2Source is now the only control for the card subtitle and address line, and showAddress is deprecated. If you relied on showAddress, set subtitle2Source instead.
  • An end time of 23:59 no longer rolls into the next day.

4.0.3 August 6, 2026

Action needed

  • Action Coordinates saved in the editor are stored again. In 4.0.0–4.0.2, number meta couldn't be written over REST. Re-enter any coordinates edited while running those versions.

New

  • New setting boundaryBuffer, also available as the ?boundaryBuffer= URL parameter.

Improved

  • The map's Venues toggle respects boundary, taxonomy, search, date and tier filters. All-day events output date-only schema. Open Graph and Twitter tags added. Events without photos use their venue's images.

4.0.2 July 30, 2026

Action needed

  • Action Lists mode: fixed a completeness-check bug that blocked cleanup when an item was in several lists. New per-list tally option vibemap_{type}_list_seen.

New

  • New settings vibemap_parallel_page_loading and vibemap_parallel_page_concurrency. The carousel gains a recommendations source.

Fixed

  • Custom boundaries always reload their shape from Vibemap instead of the copy saved in the page.

4.0.1 July 29, 2026

New

  • New setting: Initial date range (initialDateFilter, including "Next 7 days") for event Grid, Combo and Map-Grid. Set it per block or site-wide with vibemap_{post_type}_filter_initial_date_filter or vibemap_filter_initial_date_filter.
  • New setting: Analytics switch (vibemap_enable_analytics and the vibemap_analytics_enabled filter).

Improved

  • Large Safari and iOS performance fix: block bundles are 48–77% smaller, embedded data is about 90% smaller, and Mapbox loads lazily.

Fixed

  • The "Arts & Culture" and "Family-Friendly" event categories are no longer hidden by mistake.

4.0.0 July 24, 2026

Action needed

  • Action Featured Image URL mode is the default. Images are served from the ImageKit CDN instead of being downloaded. See Images for how to switch.
  • Action Places are ranked by vibemap_place_vibe_count. Run wp vibemap backfill-vibe-counts once, or wait for the next full sync.
  • Action New neighborhood taxonomies with archive templates. They are filled in automatically after the upgrade.
  • Action New wp vibemap sync command. New My List block. New send-notification-email route.
  • Action Event occurrences in a back-to-back run are shown as separate cards unless collapseConsecutiveRuns is on (the default).
  • Action REST meta: clearing coordinates now clears the field instead of storing 0,0. Links and organizer fields are written back to Vibemap. The primary taxonomy picker moved to the editor sidebar.

New

  • Hybrid fuzzy search, a mobile map redesign (bottom sheet, chips, opt-in geolocation), an interactive locator minimap, a Combo maxWidth setting, and server-side date scoping for maps.