Getting started

Welcome to Mercury Schema

Mercury Schema adds schema markup to your WordPress site: small labels that tell Google, Bing and AI assistants exactly what each page is about. You don't need to write any code.

What is schema markup?

When a person reads your recipe page, they can see the cooking time and the ingredients. A search engine sees a page of text. Schema markup spells out the details in a format search engines understand: "this is a recipe, it takes 25 minutes, it serves 4".

Search engines use these labels to show rich results: search listings with extras such as star ratings, prices, event dates or cooking times. Rich results stand out, so more people tend to click them.

An example search result. The rating, cooking time and calories come from Recipe schema.

What Mercury Schema does for you

• Sets up the basics automatically. A one-minute setup adds your organization, website, page details and breadcrumbs to every page.
• Fills in details for you. New schemas take the title, date, author and featured image from your post, so most fields are already done.
• Never publishes broken markup. If a required detail is missing, the schema is marked Incomplete and kept off your site until you fill it in.
• Stays light. No extra scripts or styles are loaded on your site, so pages don't get slower.
• Works with your tools. The block editor, the classic editor, Elementor and other popular page builders, WooCommerce, and caching plugins.

Quick start

Follow these guides in order and your site is set up in about ten minutes.

What you need

• WordPress 6.0 or newer
• PHP 8.0 or newer (your web host can tell you which version you have)
• An Administrator account to install and set up the plugin

Getting started

Install the plugin

Mercury Schema is free in the official WordPress plugin directory, so you can install it from your dashboard in under a minute.

Install from your dashboard

1. In your WordPress dashboard, go to Plugins › Add New Plugin.
2. In the search box, type Mercury Schema.
3. On the Mercury Schema card, click Install Now.
4. When it finishes, click Activate.

WordPress takes you straight to the Mercury Schema setup wizard. Carry on with Run the setup wizard.

Or upload the zip file

If your site can't install plugins from the directory, click Download on its WordPress.org page to get the zip file, then upload it.

1. Go to Plugins › Add New Plugin and click Upload Plugin at the top of the page.
2. Click Choose File, pick the zip you downloaded, then click Install Now.
3. When the upload finishes, click Activate Plugin.

Finding Mercury Schema later

Mercury Schema has its own blue item in the left-hand menu of your dashboard.

1. The Mercury Schema menu item. Click it to open the plugin's screens.
2. If you skipped the wizard, this notice reminds you. Click Start setup to begin.

Updating to a new version

New versions arrive through WordPress like any other plugin. When one is ready, Plugins shows an update notice under Mercury Schema: click update now. To update automatically, click Enable auto-updates next to it on the same screen.

If you installed by uploading a zip, updates still arrive this way.

Getting started

Run the setup wizard

The wizard picks the right schema types for your site and adds the site-wide basics for you. It takes about a minute, and you can change everything later.

1. Getting Started

The wizard opens by itself after you activate the plugin.

1. Click Start setup to choose your setup.
2. In a hurry? Skip and use the Basic setup finishes straight away with the Basic choice below.

2. Choose your schema setup

Pick one of three starting points.

1. Basic turns on the 5 schema types every site needs.
2. Smart turns on 13 types, including FAQ, Product, Review and Local Business. This is the best choice for most sites.
3. Custom lets you switch each type on or off yourself on the next screen.
4. Click Finish setup (or Next if you chose Custom).

3. Schemas (Custom only)

If you chose Custom, you now see every schema type with a switch.

1. Enable all switches every type on (or off) at once.
2. Click a card to switch that schema type on or off. Blue means on.

4. Done

That's it. Mercury Schema is now adding schema to your site.

1. The schemas the wizard added for the whole site: Organization and Website on your home page, Web Page and Breadcrumbs on your pages, and Article on your blog posts.
2. Add schema to a post opens one of your posts. See Add schema to a post or page.
3. Review site-wide schemas is where you add your logo and social profiles. See Site-wide schemas.
4. Test with Google checks your home page in Google's free testing tool. See Test your schema.

Running the wizard again

Go to Mercury Schema › Schema Types and click Run setup wizard again at the bottom of the page. Your schemas and settings stay as they are until you finish the wizard.

1. Run setup wizard again.

Using Mercury Schema

Choose your schema types

The Schema Types screen controls which kinds of schema your site uses. Switch on only what you need, so the list in the editor stays short.

Go to Mercury Schema › Schema Types.

1. The three Mercury Schema screens: Schema Types, Site-wide Schemas and Settings.
2. How many types are on. Enable all switches every type on or off.
3. Click any card to switch that type on or off. A grey switch means off.

Changes save straight away. You'll see a short confirmation in the corner of the screen.

What happens when a type is off

• It no longer appears in the Add schema list in the editor.
• Any schema of that type that you already added stops appearing on your site. It shows a Type off label in the editor.
• Nothing is deleted. Switch the type back on and everything returns as it was.

Not sure which types you need? See Which schema type should I use?

Using Mercury Schema

Site-wide schemas

Site-wide schemas describe your whole website: who runs it, what it's called, and how pages fit together. You set them up once and they appear on every matching page.

Go to Mercury Schema › Site-wide Schemas. If you ran the setup wizard, five schemas are already here and marked Ready.

1. Add schema adds another site-wide schema, such as Local Business.
2. The status label. Ready means it's complete and appearing on your site.
3. The switch turns a schema off without deleting it.
4. The ⋯ menu has Duplicate, Copy JSON-LD and Delete.

Add your logo and social profiles

The Organization schema tells search engines who is behind the site. It's the most useful one to complete.

1. Click Organization to open it.
2. Check the fields. Name, website, logo and description are filled in from your WordPress settings already.
3. Add your Email and Telephone if you want them shown.
4. In Profile URLs, paste the web address of each social profile, one per line.
5. Click Save changes.

1. Every schema has three tabs: Fields (the details), Display rules (where it appears) and Preview (what search engines will see).
2. The { } button inserts a dynamic value, a detail filled in automatically. {{site_name}} means "the site title from Settings › General".
3. Profile URLs: one address per line, for example your Facebook, Instagram or LinkedIn page.
4. Save changes. The button turns blue whenever you have unsaved changes.

Choose where a schema appears

Open the Display rules tab to limit where a site-wide schema is added.

1. Show on: the home page, single posts and pages, or archive pages (categories, tags and the blog list). The Organization schema belongs on the Front page.
2. Post types: only add it to posts, only to pages, and so on.

Below these you can also limit a schema to certain categories, to posts written by certain author roles, or to specific post IDs. Leave a group empty to mean "any".

Using Mercury Schema

Add schema to a post or page

Use the Schema Markup box to add schema for one post or page, such as an FAQ, a recipe or a product. Here we add an FAQ to a blog post.

Find the Schema Markup box

Open any post or page for editing. The Schema Markup box is below your content. In the block editor you may need to scroll down, or drag the Meta Boxes bar up.

1. Add schema opens the full list of schema types.
2. Site-wide schemas already on this page. You don't need to add these again.
3. Quick buttons for the most popular types.

Choose a schema type

Click Add schema. Type in the search box to find a type, or click one from the list.

1. Search by name, for example "recipe" or "event".
2. Click a type to add it. Here we pick FAQ.

Types you switched off under Schema Types aren't listed. A type that's already on the page is marked Added.

Fill in the details

1. Type your first question and its answer.
2. Click Add question for each extra question.
3. Click Save changes.

1. Each question has a Question and an Answer. Use the arrows to reorder questions and × to remove one.
2. Add question adds another one.
3. Save changes saves the schema.

Fields marked with a red * are required. Everything else is optional, but the more you fill in, the more search engines know.

Check the status

After saving, the label at the top of the schema tells you whether it's working.

1. Ready: the schema is complete and is being added to the page.

Fixing an Incomplete schema

Mercury Schema never puts a broken schema on your site, because search engines can flag pages with broken markup. Instead it tells you what's missing.

1. The Incomplete label.
2. A summary of the problem. The field that needs attention is outlined in red below it.

In this example the Video's Thumbnail URL uses the post's featured image, but the post doesn't have one. To fix it, either set a featured image on the post, or replace {{featured_image}} with the address of an image.

Preview what search engines see

Open the Preview tab to see the finished schema with all dynamic values filled in.

1. A green Valid message, or a list of what to fix.
2. The code that's added to your page. You don't need to understand it.
3. Copy copies the code. Test in Google opens Google's testing tool for this page (published pages only).

Turn off, copy or delete a schema

1. The switch stops the schema from appearing on your site without deleting it.
2. The ⋯ menu: Duplicate makes a copy, Copy JSON-LD copies the finished code, and Delete removes the schema. Click Delete twice to confirm.

Using Mercury Schema

Dynamic values

Dynamic values are placeholders that fill themselves in from your post or site, like {{post_title}}. They keep your schema up to date when you edit the post.

Most new schemas already use dynamic values, which is why fields such as the headline and date are filled in for you. When you change the post title, the schema changes too.

Insert a dynamic value

1. Click into a field where you want the value.
2. Click the { } button at the right of the field.
3. Choose a value from the list.

1. The { } button.
2. The list of values. The code on the right is what's inserted into the field.

You can also mix your own text with a dynamic value, for example Recipe: {{post_title}}.

All dynamic values

With WooCommerce active, six more values are available for products: price, currency, stock status, SKU, average rating and review count. See Page builders and WooCommerce.

Using Mercury Schema

Page builders and WooCommerce

Mercury Schema works with the popular free page builders, has its own button inside Elementor, and reads product details from WooCommerce automatically.

Edit schema inside Elementor

1. Open your page with Edit with Elementor.
2. In Elementor's top bar, click the Mercury Schema M icon (Schema Markup).
3. Add and edit schemas in the window that opens, exactly as described in Add schema to a post or page.
4. Close the window with the × to get back to your design.

1. The Schema Markup button in Elementor's top bar.

1. Add schema works just like in the WordPress editor.
2. Close the window. Anything you saved is kept.

Other page builders

With any other builder, add schema on the page's normal WordPress edit screen: open Pages › All Pages, click the page's title (not "Edit with…"), and use the Schema Markup box. Your schema appears on the published page however it was built.

We test Mercury Schema with these free builders and block plugins:

Paid builders such as Divi, Bricks, Oxygen and WPBakery should work the same way, using the WordPress edit screen, but we haven't tested them.

WooCommerce products

When WooCommerce is active, a new Product schema on a product fills itself in from the product: price, currency, stock status, SKU, average rating and number of reviews. When you change the price in WooCommerce, the schema follows.

1. Check that Products is ticked under Mercury Schema › Settings, so the Schema Markup box appears on products.
2. Open a product and add a Product schema.
3. Check the fields and click Save changes.

Ratings are only included once a product has at least one review.

Using Mercury Schema

Use one source of schema

Search engines should get each kind of schema from one place only. If an SEO plugin, your theme or another schema plugin also adds schema, the same details can appear twice, which can confuse search engines.

Our recommendation

Use Mercury Schema as the only source of schema on your site. Keep your SEO plugin for the jobs it's best at, such as titles, meta descriptions and sitemaps, but turn its schema off.

Mercury Schema warns you

When it finds a popular SEO or schema plugin on your site, Mercury Schema shows a warning at the top of its screens and on the last step of the setup wizard.

1. The warning names the plugin that also adds schema, says what to do, and links back to this page.

Turn off schema in your SEO plugin

We checked what each popular SEO plugin adds with its default settings, and how to switch it off. If your plugin has a setting, use it. If it doesn't, switch off the same types in Mercury Schema instead (see the next section).

SEO plugins change between versions, so after changing a setting, check a page to be sure.

Or switch off the same types in Mercury Schema

If your SEO plugin can't turn its schema off, let it handle the basic types and use Mercury Schema for everything else, such as FAQs, recipes, products and events.

1. Go to Mercury Schema › Schema Types.
2. Switch off the types your SEO plugin already adds. For Yoast SEO, that's usually Website, Web Page, Breadcrumbs, Article and Organization.
3. Keep the other types on, and add them to your posts as usual.

Nothing is deleted when you switch a type off, so you can change your mind later.

Check a page for duplicates

1. Open the Schema Markup Validator and paste the address of one of your pages.
2. Look at the list of detected items. Each type, such as Organization or BreadcrumbList, should appear once.
3. If one appears twice, find where the second copy comes from: an SEO plugin, another schema plugin, or your theme.

Using Mercury Schema

Test your schema with Google

Google's free Rich Results Test shows which rich results a page qualifies for. Use it after adding schema to an important page.

1. Make sure the page is published and visible to the public.
2. In the schema's Preview tab, click Test in Google. Or go to search.google.com/test/rich-results and paste the page's address.
3. Wait for the test to finish (usually under a minute).
4. Look for green ticks next to each detected item, such as FAQ, Recipe or Breadcrumbs.

Reading the results

• Valid items: everything is fine.
• Warnings (orange): optional details are missing. The page can still get rich results; adding the details may help.
• Errors (red): something must be fixed. Mercury Schema checks required fields before printing, so this is rare. Check the schema's Preview tab first.

Testing a site that isn't public yet

Google can't reach a site on your own computer or behind a password. Use the Copy button in the Preview tab, then paste the code into the Code tab of the Rich Results Test.

How long until rich results show up?

Google has to visit your page again before it notices new schema. That usually takes a few days to a few weeks. To speed it up, use URL Inspection › Request indexing in Google Search Console. Even then, Google decides when to show rich results.

Reference

Which schema type should I use?

Mercury Schema has 22 schema types. Most sites only need a few. Find the kind of content you have, and add that type.

"Nothing" means the required details are filled in from your post or site automatically. You can still add more.

The Basic setup switches on Organization, Website, Web Page, Breadcrumbs and Article. Turn any type on or off under Schema Types.

Entering dates and times

A few fields expect a particular format. The field shows an example, and you'll see a message if the format is wrong.

A note on FAQ and How-To results

Google now shows FAQ rich results mostly for well-known government and health websites, and no longer shows How-To rich results. These schemas are still worth adding: search engines and AI assistants use them to understand your questions and instructions, even when no extra result appears.

Reference

Settings

Most sites never need to change these. Go to Mercury Schema › Settings.

1. Post types: where the Schema Markup box appears. Posts and Pages are ticked by default. Tick Products if you use WooCommerce.
2. Output location: where the code is placed on your pages. Keep Page head unless a support person asks you to change it.
3. Debug logging: records why a schema wasn't added to a page, for troubleshooting. Leave it off normally.

Click Save Changes after changing anything.

Who can edit schema

Help

FAQ and troubleshooting

Answers to the questions people ask most. Click a question to open it.

Something isn't working

General questions

Still stuck?

Report a problem on GitHub. Tell us what you were doing, what you expected and what happened instead. A screenshot helps.