WP Title Layer

WP Title Layer keeps the native WordPress post_title as the canonical primary title, then stores the surrounding editorial structure as separate data:

• an explanatory subtitle;
• one native WordPress Series relationship per post;
• ordered or unordered Series, optionally divided into seasons;
• an opt-in Sequence view for inserting and moving ordered articles without renumbering every later article, independent of optional book-like tracks;
• explicit Series/Season scope plus introduction, main-article, epilogue, and appendix tracks for book-like Series;
• an optional explicit Series lifecycle status without publishing side effects;
• a read-only, status-aware Series content-health report;
• named display templates with category, Series, and post-level selection;
• optional Series archives, ordered reading navigation, progress, and explicit full-Series or current-season boundaries;
• an optional parent Category branch for each Series, with non-blocking consistency checks that never rewrite article categories;
• per-Series archive layout, Subtitle, Excerpt, and structured featured-image policies;
• an optional media-library Series icon that remains decorative and outside article, SEO, and social-title semantics;
• optional Rank Math variables for independently composed SEO and sharing titles;
• a read-only landing-page and channel report for duplicate Category entry points, canonical, robots, sitemap, search titles, and social titles;
• a media-library Series cover control and a fail-safe Classic Editor meta box;
• opt-in archive-card subtitles for verified official Kadence 1.5.x templates;
• an accessible, progressively enhanced tabbed settings screen that keeps placement, presentation, reading, and search/share responsibilities separate;
• a non-destructive migration path from Secondary Title and verified ACF subtitle fields.

The current implementation status and production acceptance order are tracked in the 1.0.0-rc.1 feature map. The completed stages and path to 1.0 are recorded in the development roadmap, with the ordering and upgrade contract in the Series Sequence Manager design. A focused 1.0.0-rc.1 acceptance record covers the four Series shapes, explicit scope, role tracks, isolated fixtures, front-end order, legacy compatibility, and the public release package.

ACF is not a dependency. WP Title Layer registers and owns its taxonomy, post metadata, term metadata, REST schema, editor controls, and rendering layer. It works when ACF is absent or has been removed.

Before removing ACF from an existing site, run the migration report while ACF is still active. The five audited Series fields report non-empty field-post values and unique post IDs, not confirmed use: ACF-saved 0, false, and configured defaults can be included, while exact empty strings are excluded. WP Title Layer never converts those five fields automatically. If the site owner confirms they were unused, any verified ACF subtitle values have been migrated, and the site has no other ACF-dependent content, WP Title Layer itself gives no reason to keep ACF installed. The report cannot certify unrelated fields owned by themes or other plugins.

Install and start

1. Install the ZIP or copy the wp-title-layer directory to /wp-content/plugins/.
2. Activate WP Title Layer.
3. If the site used Secondary Title or an ACF field named subtitle, open Tools → Title Layer Migration and run the read-only scan first.
4. Review conflicts, then start the copy. Version 1.0.0-rc.1 continues through the batches automatically in the migration screen and can safely resume the same run after a reload or interrupted request.
5. Verify several posts and deactivate Secondary Title. While Secondary Title remains active, WP Title Layer stays in migration-only mode: its editor and front-end presentation are not enabled, preventing two plugins from owning the same output.
6. Open WP Title Layer → Control Center, then configure display under Settings → WP Title Layer. When the detected theme supports it, select Replace the theme post title so the layer occupies the original title slot instead of the article body.
7. Test one ordinary article and one Series article. Block themes and the verified official Kadence 1.5.x title templates have title-slot integrations. A Kadence child theme that overrides those title templates, and other classic themes, retain their title and use manual block/theme-API placement.
8. Enable Reader features separately if desired. They remain off by default.
9. Open WP Title Layer → Landing & Channels for one Series at a time before changing canonical, robots, sitemap, or duplicate Category entry points.
10. For an existing Series, open WP Title Layer → Sequence & Structure. Every ordered Series has a Sequence view; initialize it once if needed. Use Structure tracks only when the Series also needs book-like roles. Merely upgrading the plugin does not convert or rewrite any old Series.

Migration never deletes the source values and never overwrites an existing wptl_subtitle, including one intentionally saved as empty.

What migration copies

Version 1.0.0-rc.1 has exactly two automatic subtitle sources:

• Secondary Title's _secondary_title post meta;
• an ACF field whose field name is subtitle, but only when WP Title Layer can verify a real ACF field definition and the post's _subtitle reference points to that field key.

A raw meta key named subtitle is not sufficient proof. Unverified references, disagreeing sources, multiple values, and existing different targets enter the conflict report instead of being guessed or overwritten.

The migration screen also audits these five legacy Series-like ACF fields:

• series_key
• series_title
• series_order
• series_has_order
• series_stage

They are non-empty-value and verified-reference counts, not confirmed usage counts. ACF defaults can be included, exact empty strings are excluded, and the same post can be counted once for each field. Version 1.0.0-rc.1 does not automatically map them to wptl_series, seasons, or sequence metadata.

The migration process is intentionally conservative:

1. scan without writing;
2. preview ready, matching, and conflicting records, then freeze the reviewed candidate IDs and state as plaintext-free, non-autoloaded manifest chunks;
3. copy only frozen candidates whose source, target, ACF trust, content type, status, and eligibility still match the scan, and only into an absent canonical target;
4. retain all source data;
5. journal each batch before the browser requests the next one;
6. resume an interrupted run without re-copying completed batches;
7. export a formula-safe conflict CSV only after the run reaches a stable terminal state;
8. allow guarded rollback only for unchanged rows created by that batch.

Anything added or changed after the scan is left for a new scan or recorded as a conflict; it is never silently pulled into the reviewed batch.

Series model and limits

wptl_series is one non-hierarchical taxonomy. Each Series has two independent settings:

• ordered or unordered: whether a meaningful reading path exists;
• flat or seasoned: whether entries are grouped into seasons.

Version 1.0.0-rc.1 supports at most one Series per post. It does not model multiple independent memberships.

Each Series may optionally point to one parent Category. This is an editorial map between two independent taxonomies, not a taxonomy hierarchy. An article is consistent when it belongs to that Category or one of its descendants. A mismatch is shown in the block editor and Series Health, but never blocks a save and never adds or removes an article Category automatically.

Each Series can optionally declare one descriptive lifecycle status: Planning, Ongoing, Paused, or Completed. Existing Series remain Not set until an editor makes an explicit choice; no date or article count is used to guess a status. The value is available in the Series editor, Series list, REST term metadata, and the structured Series archive. It never publishes, hides, locks, or reorders articles.

An ordered Series with seasons also has an explicit reading-navigation scope:

• Entire Series allows previous/next, start, position, and total to cross a season boundary;
• Current Season derives all five controls from the article's exact defined season and stops at that season's first and last public article.

Existing Series and missing or invalid values default to Entire Series, so an upgrade does not silently change navigation. Flat Series always use the full Series. If Current Season is selected but an article has no valid season, navigation fails closed for that article instead of guessing a boundary; the read-only Series Health report identifies the season problem.

Existing ordered Series remain on their legacy wptl_sequence_position values until an administrator explicitly initializes them in WP Title Layer → Sequence & Structure → Sequence. Its searchable Series chooser opens a selection immediately; without JavaScript, the matching native select and Open button remain available. The preview freezes the reviewed membership and source values, reports ambiguous rows, writes private ranks in resumable batches, and commits the new schema marker only after the whole Series validates. It never deletes or rewrites the legacy values.

After initialization, the Manager's canonical rank drives every front-end consumer. Authors move an article before or after another article, drag it, or use keyboard controls; they do not maintain rank integers. Visible ordinary article numbers are calculated from the resulting order, while an optional public label can still display values such as 21A or 0-1. New articles are safely appended to their Series or Season and can then be moved. A guarded single-step undo and revision conflict checks prevent stale screens from overwriting later work.

Season definitions also receive stable positive public IDs. New links use ?wptl_season=1, ?wptl_season=2, and so on; renaming or reordering a Season does not change its ID, deleted IDs are not reused, and old key-based links remain compatible.

Version 1.0.0-rc.1 separates a book-like entry's scope from its role. Flat Series entries are Series-wide. In a seasoned Series, every main article must belong to one Season, while an introduction, epilogue, or appendix may be explicitly Series-wide or belong to one Season. Each combination has its own track in Sequence & Structure → Structure tracks, so multiple prefaces or afterwords can be rearranged without consuming ordinary-article numbers. Public labels such as 0-1, Preface II, or Appendix A remain optional display text, not ranks.

Existing Series are not guessed into this model. The Structure tracks view first shows a read-only compatibility preview; any legacy non-main role with unresolved scope must be corrected in the article editor. Activation is per Series and commits only after its track ranks validate. The Sequence view remains available to every ordered Series before and after that activation. Newly created empty Series start canonical immediately. Unordered Series retain their chosen body sort and no main previous/next path, but their non-main structural tracks can still be placed at the appropriate archive edges.

Open WP Title Layer → Series Health (or use Check Series health in the Control Center) to audit that soft constraint without changing content. The report checks one Series at a time for missing or invalid positions, undefined or missing seasons, and duplicate positions. It separates published, scheduled, private, draft, pending, trashed, and password-protected articles, then links each finding to the native article editor when the current user may edit it. Draft-stage gaps are informational; published, scheduled, and private gaps are called out separately.

The report aggregates whole-Series counts in the database and fetches only 50 member rows per page. It never publishes, hides, reorders, assigns, or repairs an article. Its Series overview can be searched by name or slug; filtered pagination keeps the search term without loading member rows. Unordered Series are not treated as if they were missing a reading position, while a seasoned Series still requires a valid season assignment.

An absent or invalid Series mode is treated as unordered; publication date is never invented as a logical reading order.