Mity Docs Mity Docs for Mity Digital
Sitemapamic Documentation

Blueprints

Sitemapamic works without any changes to your blueprints. Add a few fields, though, and your authors can control each entry's and term's place in the sitemap.

Field mappings

The mappings option in config/sitemapamic.php tells Sitemapamic which fields to read:

1'mappings' => [
2 'include' => 'meta_include_in_xml_sitemap',
3 
4 'changefreq' => 'meta_change_frequency',
5 
6 'priority' => 'meta_priority',
7],

The keys are what Sitemapamic is looking for, so don't change them. The values are the field handles in your blueprints, so change those to match your own fields.

Mapping

Default handle

Purpose

include

meta_include_in_xml_sitemap

Whether the entry or term is listed.

changefreq

meta_change_frequency

The URL's <changefreq>.

priority

meta_priority

The URL's <priority>.

Every field is optional. A blueprint without a mapped field simply uses the default behaviour for it.

Each mapping must name a field, though. To stop using a mapping, leave the handle in place and remove the field from your blueprints. A mapping set to null or an empty string throws an InvalidArgumentException when the sitemap is built.

Include

Use a Toggle field. An entry or term is left out of the sitemap only when the field is false. When the field is on, empty, or missing from the blueprint, it is listed.

1-
2 handle: meta_include_in_xml_sitemap
3 field:
4 type: toggle
5 display: 'Include in XML sitemap'
6 default: true

Change frequency

Use the Sitemap Change Frequency fieldtype, which Sitemapamic provides. It's a dropdown of the seven values the sitemap protocol allows, and it stores the value as a plain string.

1-
2 handle: meta_change_frequency
3 field:
4 type: sitemapamic_change_frequency
5 display: 'Change frequency'

It has two options:

Option

Default

Description

placeholder

The text shown when no value is chosen.

clearable

true

Whether authors can clear the value. A cleared field uses the defaults.

You can also use your own field, as long as it stores one of always, hourly, daily, weekly, monthly, yearly or never. A Dictionary field using the Sitemap Change Frequencies dictionary works too, including one that stores a single value in an array.

Priority

Use any field that stores a number from 0 to 1, such as a Float field or a Range field with a step of 0.1.

1-
2 handle: meta_priority
3 field:
4 type: range
5 display: Priority
6 min: 0
7 max: 1
8 step: 0.1

Invalid values

A changefreq that isn't one of the allowed values, or a priority outside 0–1, is ignored and the defaults are used instead. No error is shown, so one bad value never breaks your sitemap.

Sharing the fields with a fieldset

To use the same fields across Collections and Taxonomies, put them in a fieldset, such as resources/fieldsets/sitemap.yaml:

1title: Sitemap
2fields:
3 -
4 handle: meta_include_in_xml_sitemap
5 field:
6 type: toggle
7 display: 'Include in XML sitemap'
8 default: true
9 -
10 handle: meta_change_frequency
11 field:
12 type: sitemapamic_change_frequency
13 display: 'Change frequency'
14 -
15 handle: meta_priority
16 field:
17 type: range
18 display: Priority
19 min: 0
20 max: 1
21 step: 0.1

Then import it into each blueprint:

1-
2 import: sitemap

Computed values

A mapping can name a computed value instead of a blueprint field. This is handy when the value depends on other data, such as leaving out entries with a noindex flag.

Check out the Computed configuration for full details.

A few things to know:

  • Computed values work for entries only. Terms always use their stored value.

  • A stored value wins. The computed value is used only when the entry has no value of its own for that field.

  • The callback runs for every entry in the sitemap, so keep it fast. Slow callbacks slow down every sitemap build.

Localisations

On a multi-site, Sitemapamic reads each localisation's own values. A localisation does not inherit include, changefreq or priority from its origin entry.

So if an origin entry is excluded, its localisations are still listed unless they are excluded too. This lets each site decide for itself.

Upgrading from v3

v3 named the change frequency mapping change_frequency. If your published config still uses that key, it keeps working. Rename it to changefreq when you next update your config.