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 |
|---|---|---|
|
| Whether the entry or term is listed. |
|
| The URL's |
|
| The URL's |
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_sitemap3 field:4 type: toggle5 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_frequency3 field:4 type: sitemapamic_change_frequency5 display: 'Change frequency'
It has two options:
Option | Default | Description |
|---|---|---|
| The text shown when no value is chosen. | |
|
| 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_priority3 field:4 type: range5 display: Priority6 min: 07 max: 18 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_frequency11 field:12 type: sitemapamic_change_frequency13 display: 'Change frequency'14 -15 handle: meta_priority16 field:17 type: range18 display: Priority19 min: 020 max: 121 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.