Aardvark Seo Laravel Package

Getting Started

1. Install the addon

   composer require withcandour/aardvark-seo
   

2. Publish config and views (check php artisan vendor:publish for the exact tags the addon registers):

   php artisan vendor:publish --provider="WithCandour\AardvarkSeo\ServiceProvider"
   

3. Open config/aardvark-seo.php first. This is where site-wide defaults live: site name, default title/description, social handles, sitemap toggle, and whether SEO fields are injected globally or per-blueprint. Get this file right before touching templates.
4. Attach the seo fieldset to the blueprints you care about — usually resources/blueprints/collections/pages/page.yaml and your blog collection. Add it under a dedicated SEO tab so editors don't have to hunt for it.
5. Render the tag once in your layout <head>. The addon exposes an Antlers tag (commonly {{ seo }} or a similarly-prefixed tag — confirm by listing vendor/withcandour/aardvark-seo/src/Tags). Put it in resources/views/layouts/base.antlers.html immediately after <meta charset>.
6. First use case: edit a blog entry in the CP, fill in Meta Title, Meta Description, and an OG image, save, then view source on the front end. If the tags appear, the wiring is correct and you can move on to defaults and schema.

Where to look when something is off, in order: config/aardvark-seo.php → vendor/withcandour/aardvark-seo/src/Tags (what the tag actually emits) → resources/views in the vendor directory (what partial is being rendered) → the service provider (routes, sitemap, event listeners).

Implementation Patterns

• One include, one source of truth. Create a resources/views/partials/seo.antlers.html that contains only the addon tag plus any layout-local overrides, and include it from every layout. Never scatter SEO markup across templates.
• Cascade defaults → collection → entry. Use the config for site-wide values, the blueprint's default field values for per-collection overrides (e.g., blog posts append "— {{ site:name }}"), and let editors override per entry. Always provide a fallback in the template for blank fields: {{ seo_title or title }} style logic, otherwise half your entries ship with empty <title> tags.
• Fieldset reuse over duplication. Define the SEO fieldset once and import it into every blueprint that needs it. This keeps future addon upgrades from requiring edits in ten files.
• Per-collection JSON-LD. Map blog posts to Article, products to Product, the homepage to Organization/WebSite. If the addon's schema selection is config-driven, encode the mapping there; if it's field-driven, expose a select field in the blueprint and default it by collection via the field's default value.
• Sitemap loop. Enable the sitemap, add the route to robots.txt, and submit it in Search Console on every environment you care about. Exclude noindex entries — most SEO addons do this automatically, but verify by curling /sitemap.xml after adding a noindexed entry.
• OG image fallback chain. Entry-level OG image → collection default → global default. Editors forget this field constantly; a fallback prevents social cards with no image.
• Multi-site. Set defaults per site in config, and check how the addon builds canonical URLs and hreflang. Verify localized entries point at their own URLs, not the origin site's.
• Editor workflow. Put the SEO tab last in the blueprint, and add help text on the meta description field ("aim for 150–160 characters"). The addon gives you fields; the guidance is your job.
• CI smoke test. A simple curl -s https://staging/sitemap.xml | grep -c '<url>' plus a grep for empty <title></title> catches the majority of regressions.

Gotchas and Tips

• Adding SEO fields later doesn't backfill. Existing entries will have null for every new field. Write template fallbacks, or run a one-off command to populate defaults before launch.
• Duplicate meta tags. If your layout also hardcodes <title> or <meta name="description">, you'll render two of each. Delete the hardcoded ones the moment you add the tag.
• Config caching. php artisan config:clear locally after editing aardvark-seo.php; remember config:cache in production. A "my config change did nothing" bug is almost always this.
• Static caching and the sitemap. With Statamic's static caching or full-measure caching, new entries won't appear in the sitemap until the cache is cleared. Wire cache invalidation to the entry-saved event if the addon doesn't already.
• Route collisions. Other sitemap packages and custom /sitemap.xml routes conflict silently — the last registered route wins. Run php artisan route:list | grep sitemap if the output looks wrong.
• Force noindex on non-production environments. The cleanest approach is an env check in the config file that globally forces noindex everywhere except production. Otherwise staging sites end up in Google's index.
• JSON-LD escaping. Structured data must be output raw, not HTML-escaped. If you override the partial, use {{ ... | raw }} (or the addon's equivalent) or Google's validator will reject it.
• Field handle collisions. If a collection already has a field called seo, seo_title, etc., the blueprint import will clash. Rename your existing field before adding the fieldset.
• Blueprint/fieldset changes sometimes need a cache clear (php artisan cache:clear and, on older setups, stache:clear) before the CP reflects them.
• License and maintenance risk. The package is listed under NOASSERTION, has a small star count, and the linked repo appears to be a fork. Confirm the canonical upstream (withcandour/aardvark-seo), read the LICENSE file in vendor/, and pin an exact version in composer.json. Treat the source as readable and forkable — you will likely need to patch it eventually.
• Debugging empty output. If {{ seo }} renders nothing: the fieldset isn't on the blueprint, the entry was saved before the field existed, the layout isn't using the right layout file, or the tag name is wrong. Check those four in that order before filing anything upstream.
• Extension points. Publish the views and override the partial rather than editing vendor/. For anything more dynamic (e.g., SEO for a custom route), bind data into the view or use Statamic's Antlers view data rather than modifying the addon.