Skip to content
metacraft

Getting started

From a fresh install to a site that outputs its titles, descriptions, social tags, JSON-LD and sitemap from MetaCraft. Allow about half an hour. Nothing changes on the live site until step 4.

Requirements

  • ExpressionEngine 7.5 or later, PHP 8.2 or later.
  • Structure is optional. MetaCraft reads its page tree when it's installed, and works from channel URL patterns when it isn't.
  • AI suggestions (optional) need your own Anthropic API key.

Install

  1. Copy the metacraft/ folder to system/user/addons/metacraft/.
  2. Control Panel → Add-Ons → MetaCraft SEO → Install.
  3. Open Add-Ons → MetaCraft SEO. Until a channel is turned on, the Overview shows the three steps below.

Upgrade

  1. Replace system/user/addons/metacraft/ with the new folder (keep no old files behind).
  2. Control Panel → Add-Ons: MetaCraft shows an Update button. Click it to run the database updates, or run php system/ee/eecli.php addons:update --addon=metacraft.
  3. Hard-reload a MetaCraft screen if it looks half-styled (⌘⇧R / Ctrl+F5).

Upgrades keep your settings and every entry's SEO values, and the head tag's output stays the same until you use the new features. The changelog lists what's new in each version.

Step 1: review the site defaults

Settings → General:

  • Site name and Base URL: leave blank to use EE's, or set them if EE's base URL includes index.php or an internal hostname. The Canonical example line shows a real URL as you type.
  • Title format: {title} {separator} {site_name} suits most sites. The Example box shows an entry title and a page without one.
  • Default description: usually best left blank. Search engines then write their own snippet for pages without one.

Settings → Social: a default share image (at least 1200 × 630) and your X @handle.

Settings → Structured data: who publishes the site (an organization, a local business, a clinic…), its logo, profile links, and for local businesses the address and opening hours.

Settings → Advanced: on a Structure site, set Trailing slashes in URLs to Add.

Each tab saves with Save settings (or ⌘S / Ctrl+S). See Settings for every option.

Step 2: turn MetaCraft on for your channels

Settings → Channels lists every channel. Switch on the ones whose entries are pages on the site (pages, articles, events, staff…), then click Edit on each to choose:

  • where its description and social image come from: a field such as Summary or Hero image, the same text or image for every entry, or nothing;
  • its structured data type (Article, Event, FAQPage, Person…) and the fields that fill it;
  • whether editors see the MetaCraft SEO tab on the publish form (on by default).

A channel that's left off is ignored, apart from its Structure pages, which still get titles and canonicals from the site defaults.

Step 3: give channel entries their URLs

Entries in the Structure tree already have URLs. For other channels whose entries have their own pages (a blog, news, events), open the Sitemap screen and give the channel a URL pattern under Sources, such as /blog/{url_title}/. MetaCraft uses it to recognise the page, build its canonical URL and list it in the sitemap.

Step 4: add the head tag

Put the tag once inside <head>, in the layout or partial every page uses, and remove the old <title>, description, canonical and og: tags (or {exp:seo_lite}) from the same head:

<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  {exp:metacraft:head}
</head>

View a few pages' source to check the output. The Overview lists any template that would still output a tag twice. Template tags has every parameter and examples for search, 404 and listing pages.

Switching from SEO Lite Pro? Import its data first: see Switching from SEO Lite Pro.

Step 5: publish the sitemap

  1. Sitemap screen: turn Enabled on and check the public statuses.
  2. Create an XML template containing only {exp:metacraft:sitemap} with the route sitemap.xml.
  3. Open /sitemap.xml, add Sitemap: https://your-site/sitemap.xml to robots.txt, and submit it to Google Search Console.

XML sitemaps covers large sites, static files and hosting quirks.

Step 6: fill the gaps

The Overview now shows how many published entries have custom values, use defaults only, or need attention (a missing description or image with nothing to inherit, or a duplicate title or canonical). Content SEO lists every entry with filters for each problem, Quick edit for titles and descriptions, and Edit SEO for everything else. See Overview and Content SEO and Editing an entry's SEO.

Optional: page content and AI suggestions

MetaCraft can read each entry's rendered page and suggest titles, descriptions and structured data values for review. Marks in your HTML (Marking page content) work without AI. For AI suggestions, an admin turns them on in Settings → AI with your Anthropic API key. See Page content and suggestions, including what is sent and what it costs.

Optional: cron

Two commands keep things fresh without anyone waiting:

php system/ee/eecli.php metacraft:sitemap   # static sitemap files (only needed in static mode)
php system/ee/eecli.php metacraft:capture   # re-read changed pages for suggestions