PBJ SEO — User Guide

PBJ SEO — Install and Usage Guide

What this plugin does

PBJ SEO outputs every on-page SEO signal WordPress core doesn't: titles, meta descriptions, canonical URLs, robots directives, Open Graph / Twitter cards, and a single JSON-LD schema graph (Organization, WebSite, WebPage, Article, Product, BreadcrumbList, LocalBusiness, Service, FAQPage). Since 2.0.0 it also contains the merged PBJ Site Essentials module (security headers, legacy 301 redirects, geo meta, perf tweaks, [pbj_year]) and a block-editor sidebar with per-post SEO fields and a live best-practices checklist.

Requirements

• WordPress 6.4 or newer.
• PHP 7.4 or newer.
• No dependencies. WooCommerce and Rank Math local-SEO options are detected and used when present, never required.

Installation

1. Plugins → Add New → Upload Plugin → choose pbj-seo.zip → Install Now.
2. If WordPress says the plugin is already installed, choose "Replace current with uploaded" — that is the upgrade path.
3. Activate "PBJ SEO".
4. Settings carry over on upgrades (per-post meta lives in the posts themselves).

Upgrading from PBJ Site Essentials: after activating PBJ SEO 2.0.0+, deactivate and delete the standalone "PBJ Site Essentials" plugin. The merged module stands down while the old plugin is active, so there is no double output during the transition — but nothing new takes effect until the old plugin is gone.

First-time setup

There is no settings screen. Defaults apply immediately. Three things worth checking on a new site:

1. Force-HTTPS is ON by default (2.0.0+). It only ever redirects when the Site/Home URL is already https://, so local sandboxes are unaffected. Opt out with define( 'PBJ_SEO_FORCE_HTTPS', false ); in wp-config.php.
2. Site logo (Customizer → Site Identity) — it's the fallback share image and the Organization schema logo.
3. Open any post in the editor, click the magnifier icon in the top bar (or the "PBJ SEO" entry in the options menu), and check the Site-wide panel — it flags discouraged search engines, plain permalinks, missing tagline/logo/site icon, and non-HTTPS home URLs, each with an "Open settings" button.

Daily usage

Write your post, then open the PBJ SEO sidebar:

• SEO title — replaces the whole document title. Empty = "Post Title – Site Name". Counter shows length against the ~60-character display limit.
• Meta description — empty = auto-generated from the excerpt or content. Hand-written descriptions earn more clicks; the checklist reminds you.
• Hide from search engines — per-post noindex toggle.
• This page checklist — every check updates live as you edit. Failing items show a button that takes you to the fix: set featured image, select the exact image missing alt text, edit slug, add excerpt.
• The pre-publish panel repeats anything still failing when you click Publish.

FAQ schema is automatic: add a heading containing "Frequently Asked Questions", then H3 questions each followed by a paragraph answer. The checklist confirms when a FAQ section is detected.

Service-page schema is automatic for slugs in the service map (see the code explainer to change the map via pbj_seo_service_schema_map).

Testing what crawlers see

• View source on any front-end page: everything between <!-- PBJ SEO --> and <!-- /PBJ SEO --> is the plugin's output.
• Validate schema at https://validator.schema.org or Google's Rich Results Test.
• Check headers with curl -sI https://yoursite.com/ — you should see the security headers and (on LiteSpeed) X-LiteSpeed-Cache-Control.
• Test a legacy redirect: curl -sI https://yoursite.com/seo should return 301 with the mapped location.
• Log out (or use a private window) to see cached/anonymous behavior.

Upgrading

Upload the new pbj-seo.zip via Plugins → Add New → Upload Plugin and choose "Replace current with uploaded". Per-post meta and the htaccess marker survive. The Update URI: https://pbj.tech/pbj-seo header prevents WordPress.org from ever offering a conflicting update.

Troubleshooting

• Redirect loop after enabling HTTPS — your proxy terminates TLS but doesn't send X-Forwarded-Proto: https. Fix the proxy header, or define( 'PBJ_SEO_FORCE_HTTPS', false );.
• Sidebar doesn't appear — it only loads in the block editor (post/page edit screens), not the classic editor or site editor. Check the ⋮ options menu → Plugins → PBJ SEO.
• SEO fields don't save — the post type must support custom-fields for meta over REST. Add add_post_type_support( 'your_type', 'custom-fields' );.
• Duplicate meta tags in head — the standalone PBJ Site Essentials plugin or an old mu-plugin (pbj-geo-meta.php, pbj-schema-extras.php, pbj-perf-tweaks.php, pbj-legacy-redirects.php) is still installed. The plugin stands down feature-by-feature while those exist; remove them to hand over fully. Another SEO plugin (Yoast/Rank Math) running simultaneously will also double-emit — run one.
• Search/404 pages showing cached content — fixed in 2.0.0 (cache headers moved after the main query). If you still see it, the page was cached before the upgrade: save any post to trigger a full X-LiteSpeed-Purge: *.
• Stale pages after edits on LiteSpeed — purges ride on admin responses. If a migration bypassed wp-admin, save any post to purge, or restart LiteSpeed.
• geo meta shows the wrong city — coordinates come from Rank Math local-SEO options when present (rank-math-options-titles), else Jupiter FL defaults. Set the pin in Rank Math or filter the output.

Where things live

• Plugin: wp-content/plugins/pbj-seo/pbj-seo.php (all PHP), assets/js/editor.js (sidebar).
• Per-post meta keys: _pbj_seo_title, _pbj_seo_description, _pbj_seo_noindex ('1' = noindex).
• Options: pbj_seo_htaccess_version (LiteSpeed CacheLookup marker tracking).
• .htaccess marker block: # BEGIN PBJ SEO LiteSpeed Cache (removed on deactivation).
• Key filters: pbj_seo_force_https, pbj_seo_cache_ttl, pbj_seo_cacheable, pbj_seo_default_image, pbj_seo_schema_graph, pbj_seo_is_article, pbj_seo_article_type, pbj_seo_article_author, pbj_seo_service_schema_map, pbj_seo_redirect_map, pbj_seo_redirect_attachments.