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.

The dashboard (3.0.0, expanded through 3.3.0): a full admin dashboard at the top-level SEO menu with seven tabs — Checklist, Options, Business, Robots & Sitemaps, Google Tools, 404s & Redirects, License — covering a whole-site SEO checklist and page-by-page audit, on/off switches for every feature, your business/schema data, robots.txt and sitemap controls, built-in Google Analytics + Search Console setup, and an automatic 404 log with one-click redirect creation. See "The dashboard" below.

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

Defaults apply immediately — you don't have to configure anything. On a new site, open SEO → Checklist and work down the two lists:

1. The Site checklist flags anything site-wide that hurts SEO — discouraged search engines, plain permalinks, missing tagline/logo/site icon, non-HTTPS, a front page with no share image, a disabled sitemap — each with a Fix button that jumps to the right screen. It also confirms PBJ SEO's own output is live and warns if a second SEO plugin is active.
2. Pages that need attention lists every published page and post with something to improve, and an Edit button that opens its SEO panel.
3. Force-HTTPS is ON by default and only ever redirects when the Home URL is already https:// (local sandboxes are unaffected). You can toggle it — and every other feature — on the Options tab, or override it with define( 'PBJ_SEO_FORCE_HTTPS', false ); in wp-config.php.

The dashboard

The top-level SEO menu has seven tabs:

• Checklist — the site audit and per-page audit described above. Nothing is changed here; it's your to-do list, always current. Since 3.3.0 it also warns when Google Analytics isn't connected or Search Console isn't verified, each with a Fix link to the Google Tools tab.
• Options — an on/off switch for every feature (force-HTTPS, security headers, LiteSpeed edge cache, geo meta, legacy redirects, custom redirects, 404 logging, attachment redirects, feed noindex, head cleanup, performance tweaks), each with a plain-English explanation. Everything ships ON, so turning nothing on/off leaves 2.x behavior exactly as it was.
• Business — every piece of local-business data the plugin can emit, editable in one place: name, schema type, phone, email, price range, image, description, postal address, geo coordinates, the service-area list, and the per-page Service schema map. Empty fields simply stand down (no node, no tags).
• Robots & Sitemaps — shows your sitemap URL and whether it's enabled, previews the effective robots.txt, and lets you append custom robots rules (saved and emitted through WordPress's robots_txt filter). Since 3.3.0 it also controls exactly what the sitemap includes and has a Refresh sitemap now button — see "Sitemap controls" below. The sitemap itself is generated by WordPress core; PBJ SEO adds <lastmod> dates and advertises it in robots.txt.
• Google Tools — step-by-step Google Analytics and Search Console setup with the two inputs the plugin acts on (GA4 Measurement ID and the verification token), plus a Bing field. See "Google Tools tab" below.
• 404s & Redirects — a lightweight logger records not-found URLs (with hit counts and referrers) as visitors hit them; click Redirect on any row to turn it into a 301, or add one by hand. The redirect manager supports 301/302, shows a per-rule hit counter, and applies your redirects site-wide. The built-in legacy map still applies on 404 and can be toggled off on the Options tab.
• License — enter your PBJ license key to unlock automatic updates. The plugin is fully functional without a key; a key covers up to 3 sites.

Google Tools tab

SEO → Google Tools connects the site to Google without another plugin. Each card is a numbered walkthrough with direct links to the right console screen:

• Google Analytics (GA4) — create a Property and Web data stream at analytics.google.com, then paste the stream's Measurement ID (G-XXXXXXXXXX) into the field and save. PBJ SEO outputs the Google tag (gtag) on every page itself — no other setup, no analytics plugin. Logged-in editors and admins are never tracked, so your own work doesn't skew the numbers. Leave the field empty and no Analytics tag is output at all. Verify by visiting the site in a private window and watching Analytics → Reports → Realtime.
• Google Search Console — add a URL prefix property at search.google.com/search-console, choose the HTML tag verification method, and paste what Google shows into the Verification tag or token field — the whole <meta> tag or just the token, both work. Save, then click Verify in Search Console. Keep the token in place afterward; Google re-checks it periodically.
• Submitting your sitemap — once verified, open Sitemaps in Search Console (the tab links straight to it) and enter wp-sitemap.xml. That's the whole job; Google fetches it from there on.
• Bing Webmaster Tools (optional) — same idea for Bing (which also feeds DuckDuckGo and ChatGPT search). The quickest path is "Import from Google Search Console" at bing.com/webmasters; to verify manually instead, paste Bing's meta-tag token (msvalidate.01) into the Bing field.

Sitemap controls

SEO → Robots & Sitemaps controls exactly what the core sitemap includes (new in 3.3.0). Defaults match WordPress core exactly, so nothing changes until you untick something:

• Per-post-type toggles — one checkbox per public post type (Pages, Posts, Products, …). Untick a type to keep it out of the sitemap entirely. Media is already excluded by core.
• Category & tag archives — one toggle for all taxonomy archive sitemaps (categories, tags, product categories, and so on).
• Author archives — a toggle for per-author archive pages. Single-author sites usually turn these off — they duplicate the blog listing.
• Exclude specific pages or posts — a field of IDs (comma- or newline-separated) to omit individual entries. Find the ID in the editor URL (post=123).
• Refresh sitemap now — rebuilds the sitemap routes (flushes rewrite rules), clears any cached copy, then fetches the live sitemap and reports what crawlers see: on success the admin notice reads "Sitemap refreshed — it is live and currently lists N URLs"; if the fetch fails, it reports the HTTP status code and tells you to check that XML sitemaps are enabled and the site is reachable.

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 listed in the Service pages map on SEO → Business (or supplied in code via pbj_seo_service_schema_map — see the code explainer).

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 (or none) — coordinates and city/region come from the Business tab; when those are empty they sync from Rank Math local-SEO options if present (rank-math-options-titles). Since 3.2.0 there are no hardcoded fallbacks — fill in SEO → Business.

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_settings (feature toggles), pbj_seo_business (Business-tab data), pbj_seo_google (GA4 ID + verification tokens), pbj_seo_sitemap (sitemap include/exclude controls), pbj_seo_redirects (custom 301/302 map), pbj_seo_404_log (recent 404s), pbj_seo_robots_extra (custom robots.txt lines), pbj_seo_htaccess_version (LiteSpeed CacheLookup marker tracking).
• .htaccess marker block: # BEGIN PBJ SEO LiteSpeed Cache (removed on deactivation).
• Dashboard: the top-level SEO menu (added 3.0.0 under Settings, promoted to the sidebar in 3.0.1). All admin code lives in the same pbj-seo.php file, gated behind is_admin().
• 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.