SEO Surgeon Documentation

Overview

SEO Surgeon is a WordPress SEO plugin that takes a different approach from traditional SEO tools. Instead of overwhelming you with dozens of checks of equal weight, SEO Surgeon uses an impact-based scoring system that prioritizes the changes that will actually move the needle for your search rankings. Every recommendation is tagged with a HIGH, MEDIUM, or LOW impact badge so you know where to focus your effort.

The plugin provides a 100-point SEO score for each post and page, a live Google SERP preview that updates as you type, automatic schema markup generation, and a settings page for configuring organization-level SEO data. SEO Surgeon is available in three paid tiers:

• Lite — Core meta box, live SERP preview, 12-check impact analyzer, Article/WebPage/Breadcrumb schema, Open Graph & Twitter Card tags. 1 site activation.
• Plus — Everything in Lite, plus WooCommerce Product schema and custom social preview (per-post OG title, description, and image with live Facebook card preview). 3 site activations.
• Pro — Everything in Plus, plus advanced analysis (readability scoring, keyword density, heading hierarchy) and white-label meta box. Unlimited site activations.

SEO Surgeon integrates directly into the WordPress editor via a meta box, so you can optimize your content without leaving the post editing screen. There is no separate dashboard to navigate to for day-to-day use.

Installation

SEO Surgeon installs like any standard WordPress plugin. Download the seo-surgeon.zip file from your Boulley Technology account or the product page.

1. In your WordPress admin, go to Plugins > Add New > Upload Plugin.
2. Select the ZIP file and click Install Now.
3. Click Activate Plugin after installation completes.

Once activated, SEO Surgeon adds a meta box to all post and page editing screens, and a settings page under Tools > SEO Surgeon. No additional setup is required to start using the on-page analysis features.

If you are migrating from another SEO plugin, SEO Surgeon can run alongside most other SEO plugins without conflict. However, you may want to disable the other plugin's meta box to avoid confusion, since both will appear on the editor screen.

Meta Box

The SEO Surgeon meta box appears below the post editor when you create or edit any post or page. It contains several fields and tabs that let you control how your content appears in search results and how it scores against SEO best practices.

SEO Title

The SEO title field lets you set a custom title tag for the page. This is the clickable headline that appears in Google search results. If left empty, SEO Surgeon falls back to your post title. A character counter shows you how long your title is relative to the recommended maximum of 60 characters. Titles that exceed this length may be truncated in search results.

Meta Description

The meta description is the short summary text displayed below the title in search results. While Google does not always use your meta description, providing one gives you control over the snippet when it does. The recommended length is 120-160 characters. SEO Surgeon shows a character counter and highlights when you are outside the optimal range.

Focus Keyword

Enter the primary keyword or key phrase you want the page to rank for. SEO Surgeon uses this keyword to run its analysis checks, verifying that the keyword appears in important locations like the title, first paragraph, headings, URL slug, and image alt text. You can only set one focus keyword per page, which encourages you to keep each page focused on a single topic.

Analysis Tab

The Analysis tab in the meta box shows your page's overall SEO score out of 100 points, along with a breakdown of individual checks. Each check is displayed as a pass or fail item with an impact badge indicating how much it matters for your rankings.

• HIGH impact checks are the most important. These cover title tag length and keyword placement, H1 presence, and meta description. Failing a HIGH impact check costs you the most points.
• MEDIUM impact checks cover image alt text, internal and external links, and content length. These contribute to a well-optimized page but are secondary to the HIGH impact items.
• LOW impact checks cover Open Graph tags and canonical URL. They contribute fewer points but help you reach a perfect score.

Click Analyze to run the checks against your current saved content. The score is out of 100 and reflects only the standard 12 checks. Pro-tier advanced analysis checks appear in a separate section below and are informational — they do not affect the score.

Advanced Analysis PRO

Pro-tier users see three additional analysis checks below the standard 12. These checks appear under an Advanced Analysis heading in the Analysis tab and are labeled ADVANCED instead of HIGH/MEDIUM/LOW. They are qualitative insights and do not change the 100-point score.

Readability — Flesch Reading Ease

SEO Surgeon calculates a Flesch Reading Ease score for your content. This score measures how easy the text is to read based on average sentence length and average syllables per word. The scale runs from 0 (extremely dense academic text) to 100 (very simple).

• Pass (60–100): Standard to very easy — accessible to most readers.
• Warning (50–60): Fairly difficult — consider shorter sentences and simpler words.
• Fail (below 50): Difficult to read — break up long sentences and reduce complex vocabulary.

Keyword Density

If you have set a focus keyword, SEO Surgeon calculates what percentage of the total word count it accounts for. The ideal range is 0.5% to 2.5%.

• Pass (0.5%–2.5%): Healthy usage — the keyword is present without being forced.
• Warning (2.5%–4% or below 0.5%): Slightly high or low — review usage for naturalness.
• Fail (above 4% or 0%): Keyword stuffing risk or keyword absent — adjust accordingly.

Heading Hierarchy

SEO Surgeon checks that your heading levels do not skip levels (for example, jumping directly from H2 to H4 without an H3 in between). Skipped heading levels can confuse screen readers and make your content structure harder for crawlers to parse.

• Pass: No heading level skips detected.
• Warning: One skip detected.
• Fail: Two or more skips detected — review your heading structure.

SERP Preview

The SERP Preview tab shows you exactly how your page will appear in Google search results. It renders a realistic preview with your SEO title, URL, and meta description formatted the same way Google displays them.

The preview updates in real time as you type in the SEO title and meta description fields. If a title or description is too long, the preview shows the truncation with an ellipsis, matching Google's behavior. This lets you fine-tune your wording to fit within the visible space.

The URL shown in the preview is derived from your post's permalink. If you change the slug, the preview updates accordingly. The preview also shows the breadcrumb path that Google would display based on your site's URL structure.

Social Preview PLUS

Plus and Pro users see a Social Preview section below the robots meta controls in the SEO Settings tab. This lets you set a custom title, description, and image specifically for social media shares — separate from your SEO title and meta description.

Live Facebook Card Preview

A Facebook-style card preview updates in real time as you type, showing exactly how your post will appear when shared on Facebook, LinkedIn, and other platforms that read Open Graph tags. The preview shows the site name, card title, and description.

Fields

• Social Title — Defaults to your SEO title if left blank. Use this to write a more conversational or click-friendly headline for social shares.
• Social Description — Defaults to your meta description if left blank. Social descriptions can be slightly longer and more casual than search snippets.
• Social Image URL — Defaults to your featured image if left blank. Enter a custom URL to use a different image for social shares. Recommended size: 1200×630px.

Schema Markup

SEO Surgeon automatically generates structured data (schema markup) for your site using JSON-LD format. This markup helps search engines understand your content and can enable rich results like breadcrumbs, organization info, and article details in search results.

Automatic Schema Types

• Organization Schema — Generated site-wide using the information you provide on the Settings page (organization name, logo, social profiles). This tells search engines about your business entity.
• Article Schema — Automatically added to blog posts. Includes the headline, author, publish date, modified date, and featured image. This can enable rich article cards in Google News and Discover.
• Breadcrumb Schema — Generated for all pages based on your site's hierarchy. Breadcrumb markup gives Google the page's position in your site structure and can display breadcrumb navigation in search results.

WooCommerce Product Schema PLUS

With a Plus or Pro license and WooCommerce active, SEO Surgeon automatically generates Product schema for your product pages. This includes the product name, description, price, currency, availability status, and review ratings if available. Product schema can enable rich product cards in search results with price and availability information displayed directly.

SEO Surgeon also removes WooCommerce's built-in schema output on product pages to prevent duplicate structured data.

Settings Page

The SEO Surgeon settings page is located at Tools > SEO Surgeon in your WordPress admin. It contains global configuration that applies across your entire site.

Organization Information

Enter your organization or business name, logo URL, and contact information. This data is used to generate the Organization schema markup that appears site-wide. Providing accurate information here helps search engines associate your content with your business entity.

Social Profiles

Add URLs for your social media profiles (Facebook, Twitter/X, LinkedIn, Instagram, YouTube, etc.). These are included in your Organization schema markup, which helps search engines display your social links in Knowledge Panels and brand cards.

Content Length Targets

Set minimum and target word counts for each post type on your site. SEO Surgeon uses these targets when scoring the content length check in the Analysis tab. The defaults are reasonable starting points (300 minimum, 1000 target for posts), but you can adjust them to match the expectations of your niche. For example, long-form content sites might set a target of 2000 words, while product description pages might only need 300.

White-Label PRO

Pro users can rename the SEO Surgeon meta box to any label they choose. This is useful for agencies deploying the plugin on client sites, where you may want the meta box to say "SEO Settings" or your agency's name instead of "SEO Surgeon".

To set a custom title, go to Tools > SEO Surgeon > White-Label and enter your preferred label in the Meta Box Title field. Save settings. The new title will appear immediately on all post editing screens. Leave the field blank to revert to the default "SEO Surgeon" label.

License Activation

Navigate to Tools > SEO Surgeon and find the license activation section at the top of the page.

1. Enter your license key from your Boulley Technology account or purchase confirmation email.
2. Click Activate License.
3. The page will confirm activation and your tier's features become available immediately.

License keys are tied to a specific number of site activations (1 for Lite, 3 for Plus, unlimited for Pro). To move a license to a different site, deactivate it first from Tools > SEO Surgeon on the old site, then activate on the new one. You can manage all your licenses from your Boulley Technology account dashboard.

Troubleshooting

The meta box is not appearing on the editor screen

Check that you have Screen Options configured to show the SEO Surgeon meta box. Click "Screen Options" at the top right of the post editor and make sure SEO Surgeon is checked. If you are using the Block Editor (Gutenberg), the meta box appears in the sidebar panel or below the editor depending on your WordPress version.

The SEO score seems inaccurate

Make sure you have entered a focus keyword. Without a focus keyword, several checks cannot run and the score will be incomplete. Also verify that your content has been saved; the analysis runs against the current content in the editor, not previously saved versions.

Schema markup is not showing in Rich Results Test

Ensure your page is publicly accessible (not password-protected or behind a maintenance mode wall). Google's Rich Results Test needs to fetch the page to read the schema. Also check that another SEO plugin is not overriding the schema output. If you have multiple SEO plugins active, disable the competing plugin's schema feature.

SERP preview shows the wrong URL

The SERP preview uses your current permalink structure. If your permalinks are set to "Plain" in WordPress settings, the preview will show query parameter URLs. Switch to a more SEO-friendly permalink structure under Settings > Permalinks (Post name is recommended).

Frequently Asked Questions

Does SEO Surgeon replace Yoast or Rank Math?

SEO Surgeon can serve as a standalone SEO solution for on-page optimization and schema markup. It does not currently include XML sitemaps or robots.txt management, so if you rely on those features from your current plugin, you may want to keep it active alongside SEO Surgeon or use a dedicated sitemap plugin.

Will it slow down my site?

SEO Surgeon adds minimal frontend overhead. The analysis runs only in the WordPress admin editor, not on the public-facing site. The schema markup output is a small JSON-LD script tag that does not affect page rendering or load times.

Can I use it on custom post types?

Yes. SEO Surgeon automatically adds its meta box to all public post types. If you have custom post types registered with 'public' => true, the meta box will appear on their editor screens. You can also set content length targets per post type in the settings.

Does it support multilingual sites?

SEO Surgeon works with multilingual plugins like WPML and Polylang. Each translation gets its own SEO title, meta description, and focus keyword. The analysis runs independently for each language version of a post.

What happens to my SEO data if I deactivate the plugin?

SEO Surgeon stores its data in post meta fields. Deactivating the plugin does not delete this data. If you reactivate later, all your SEO titles, descriptions, and keywords will still be there. The schema markup output will stop appearing on the frontend while the plugin is inactive, but no data is lost.

Changelog

1.3.0

• Advanced Analysis (Pro) — Flesch Reading Ease readability score, keyword density check, and heading hierarchy validation. Appear as ADVANCED checks below the standard 12 in the Analysis tab.
• Custom Social Preview (Plus+) — per-post OG title, description, and image fields with a live Facebook card preview in the meta box.
• WooCommerce Product schema now requires Plus or Pro tier (was any paid license).
• White-label meta box (Pro) — set a custom meta box title under Tools > SEO Surgeon > White-Label.
• Fixed PHP 7.4 compatibility in internal link extraction (str_starts_with replaced with strpos).

1.2.0

• Initial release.
• SEO meta box with live Google SERP preview.
• Impact-based analyzer with 100-point scoring (12 checks).
• Automatic schema markup: Article, WebPage, Breadcrumb, Organization.
• Open Graph and Twitter Card output.
• WooCommerce Product schema (Pro).

Support

If you run into anything that isn't covered here:

• Submit a support ticket at boulleytechnology.ca/support.php
• Email support at support@boulleytechnology.ca
• General inquiries: info@boulleytechnology.ca

License holders get priority response. We typically reply within a few hours during business hours.