Migrate legacy gap helpers
Use wp pom migrate-gap-helpers after updating a site that contains the retired pixel-based web-gap* helpers, legacy [web_gap] or [web_parallax_layer_text] gap values, or an earlier dynamic pom/gap block. The command moves those values to the current rem scale and converts old Gap blocks to their static HTML form.
Replacement map
| Retired helper or shortcode value | Current helper | Height |
|---|---|---|
web-gap-10, gap_space="10" |
web-gap-075, gap_space="075" |
0.75rem |
web-gap, web-gap-20, gap_space="20" |
web-gap-125, gap_space="125" |
1.25rem |
web-gap-30, gap_space="30" |
web-gap-2, gap_space="2" |
2rem |
web-gap-40, web-gap-50, gap_space="40", gap_space="50" |
web-gap-3, gap_space="3" |
3rem |
web-gap-60, gap_space="60" |
web-gap-4, gap_space="4" |
4rem |
web-gap-8 and web-gap-12 provide new 8rem and 12rem choices without legacy predecessors.
The same gap_space map applies to web_parallax_layer_text, which uses these helpers for the space before its heading.
Preview and apply
This command uses the unified helper migration engine, limited to gap helpers. To migrate fonts, gaps and spacing together with one scan, use wp pom migrate-helpers instead.
Preview without content writes:
wp pom migrate-gap-helpers --dry-run --url=https://example.testApply with an existing private, writable mode-0700 directory outside WordPress:
wp pom migrate-gap-helpers --apply --backup-dir=/private/migrations --url=https://example.testAll helper commands default to simulation; omitting --dry-run does not apply changes. Progress is shown by phase, and --verbose lists each proposed location. The command saves exact originals and proposed values in a private backup before applying changes. It leaves all caches and generated assets unchanged.
Use --network for POM-theme sites in the current network. Shared user data, network options and shared managed templates require --include-shared; --include-network-options adds network options alone. See the unified guide for scope, format limits, progress, concurrent-write handling and recovery after interruption.
Completed conversions are preserved on repeat runs, including after an older migration stopped partway through. Verify representative pages and templates in the editor and frontend, then rerun with --dry-run --fail-on-remaining. Unsupported serialized objects/references or ambiguous values are preserved and reported for manual review.
Old self-closing pom/gap blocks are expanded to saved static markup. Their custom classes are sanitized and retained; legacy size values in paired Gap blocks are also converted. Verify that migrated Gap blocks remain selectable and display correctly in both the editor and frontend.