Statamic Sitemap Laravel Package

Getting Started

Sitemapamic is a Statamic addon that generates XML sitemaps for your site — a sitemap index at /sitemap.xml plus per-collection, per-taxonomy, and custom sitemaps underneath it.

Install and publish:

composer require mitydigital/statamic-sitemapamic
php artisan vendor:publish --tag=sitemapamic-config

Where to look first: config/sitemapamic.php. That file is the whole feature surface — it controls which collections/taxonomies are included, the route, caching, multisite alternates, and the XSL stylesheet. Read it top to bottom before touching anything else; almost every "why isn't X in my sitemap" question is answered there.

A minimal config looks like:

return [
    'collections' => [
        'pages'  => ['enabled' => true],
        'posts'  => ['enabled' => true],
        'events' => ['enabled' => false],
    ],
    'taxonomies' => [
        'tags' => ['enabled' => true],
    ],
    'cache' => [
        'enabled' => true,
        'expiry'  => 60, // minutes
    ],
];

First use case: enable one collection, visit /sitemap.xml in a browser (the XSL stylesheet makes it readable), confirm your URLs are there, then submit it to Google Search Console. For a typical marketing site with pages + posts, that's a ten-minute job.

3.5.1 note: the release filters empty results. If you'd previously seen <urlset> blocks with no <url> children, or stub sub-sitemaps in the index for collections with zero published entries, those are now dropped cleanly. Non-breaking; no action required unless you were asserting on the exact sitemap index structure in tests.

Implementation Patterns

Per-collection entries with custom data. Each collection block accepts enabled plus optional overrides for the blueprint, whether to include the homepage, and per-entry callbacks. The common pattern is to leave the defaults alone and only override loc/lastmod for collections with unusual routing:

'collections' => [
    'posts' => [
        'enabled' => true,
        'callback' => function ($entry) {
            return [
                'loc'     => $entry->absoluteUrl(),
                'lastmod' => $entry->lastModified()->toAtomString(),
            ];
        },
    ],
],

Multiple sitemaps on one site. The index auto-splits by collection and taxonomy. If you're porting an existing sitemap setup, keep the paths stable — /sitemap.xml as the index, then hand Search Console only that one URL. Don't submit sub-sitemaps individually; the index covers them.

Multisite. With multisite enabled, Sitemapamic emits xhtml:link rel="alternate" hreflang="…" entries for every site an entry exists on. This is the reason to use the package rather than hand-rolling a sitemap — getting alternates and locale mapping right yourself is tedious. Verify after enabling by grepping the output for hreflang.

Caching / static sites. With caching enabled, the sitemap is cached for the configured expiry. On a Statamic static-cached site, wire the sitemap regeneration into your deploy/build step. The invalidation command is the entry point:

php artisan sitemapamic:clear

A workable pattern is a deploy hook that runs sitemapamic:clear (or a full static:clear + static:warm) after content is published, so editors don't see a stale sitemap for an hour.

Custom (non-Statamic) URLs. Use the custom key for things outside the content tree — legacy redirects that are really pages, external profile URLs, or routes served by custom Laravel controllers. Each entry needs at minimum a loc.

Editorial workflow. Because the sitemap respects published status and (where configured) noindex, the practical workflow is: editors toggle publish, the sitemap follows. Don't build a second source of truth for "what's public" — encode it as collection config plus entry status.

Gotchas and Tips

Empty collections are now silently absent (3.5.1). This is the intended behaviour, but it changes what you see during local development: enable events in config with no published events and there will be no events sub-sitemap at all. If you're writing feature tests that assert on the index structure, assert on presence of populated sitemaps rather than the full configured set — otherwise 3.5.1 will break your suite.

Cache is the number one support issue. If a newly published entry isn't in the sitemap, run php artisan sitemapamic:clear before debugging anything else. In local dev, set cache.enabled to false; leaving it on and then wondering why edits don't appear is a rite of passage.

Config changes need a cache clear too. Statamic caches its own config/blueprints — after editing config/sitemapamic.php, run php artisan config:clear (and statamic:stache:clear if collection changes are involved) or you'll chase ghosts.

enabled vs. omission. Explicitly setting 'enabled' => false vs. removing the collection from the array can behave differently across versions with respect to defaults. Prefer explicit enabled flags so intent is readable and upgrades are predictable.

Don't fight the route. Overriding the sitemap path is possible, but robots.txt, Search Console, and any static-cache rules all assume /sitemap.xml. If you must move it, update all three in the same commit.

Extension points to reach for first: the per-entry callback for loc/lastmod overrides, the custom array for non-Statamic URLs, and the XSL toggle for a human-readable view during development (turn XSL off in production if you want the raw XML to be the default response — some crawlers and curl checks are cleaner without it).

Debugging method that works: request /sitemap.xml directly with curl rather than a browser, so you see the raw XML and can confirm caching state via response headers. Then walk config → cache → content status in that order.

Upgrading: 3.5.1 is a patch on the 3.5 line — safe drop-in from 3.5.0. Pin the minor version in composer.json ("mitydigital/statamic-sitemapamic": "^3.5") and re-read the config file after any minor bump, since the addon's config surface grows more often than its major version changes.