Requirement: Kirby 3
For a kirby3 site, this plugin (omz13/xmlsitemap) automatically generates an xml-based sitemap at /sitemap.xml
and provides a prettyfier (/sitemap.xsl
) for humans.
- Generates a sitemap; valid too.
- The generated page can be cached for a determined amount of time, c.f.
cacheTTL
in Configuration. This not only improves the response time if it can be retrieved from the cache. - For all pages,
<loc>
and<lastmod>
are given;<priority>
is not given because "its a bag of noise";<changefreq>
is also not given because it does not affect ranking. <lastmod
> is calculated using the date in a page's field calledupdatedat
, or if not present then from the fielddate
; if neither were found, it is based on the modification time for the page's content file.- When a page is included in the xml-sitemap, information for images (
<image:loc>
) on each page is inclued unless this is disabled; c.f.disableImages
in Configuration. - The generated
sitemap.xml
has an accompanyingsitemap.xsl
to produce a prettified page for human consumption. - Only pages that have a status of "published" are included (everything else,
drafts
andunlisted
, are excluded). - Pages or their children can be excluded based on the following criteria, and in the following order:
- The homepage is always included.
- The error page is always excluded.
- Only pages that have a status of "published" are included, i.e. those with "draft" or "unpublished" are excluded.
- Unpublished pages can be explicitly included based on their slugname; c.f.
includeUnlistedWhenSlugIs
in Configuration. - Pages made using certain templates can be excluded; c.f.
excludePageWhenTemplateIs
in Configuration. - Pages with certain slugnames can be excluded; c.f.
excludePageWhenSlugIs
in Configuration. - Pages with a content field
excludefromxmlsitemap
that istrue
are excluded. - Pages with a method
issunset
that returnstrue
are excluded. - Pages with a method
isunderembargo
that returnstrue
are excluded. - For use with "one-pagers", children of pages made using certain templates can be excluded as sub-ordinate links (c.f.
excludeChildrenWhenTemplateIs
in Configuration) but any images in those children will be included and listed as normal (which is how one-pagers are expected to work).
- For debugging purposes, the generated sitemap can include additional information as xml comments; c.f.
debugqueryvalue
in Configuration.
For a user-oriented html-based sitemp, kindly see omz13/kirby3-htmlsitemap.
For a plugin that provides the methods issunset
and isunderembargo
, kindly see omz13/kirby3-suncyclepages.
Kirby3 is under beta, therefore this plugin, and indeed kirby3 itself, may or may not play nicely with each other, or indeed work at all: use it for testing purposes only; if you use it in production then you should be aware of the risks and know what you are doing.
For 1.0, the non-binding list of planned features and implementation notes are:
- MVP (
loc
andlastmod
) done 0.1 -
<priority>
-
<changefreq>
- Respect page status done 0.2
- Allow specific unlisted pages to be included done 0.2 c.f.
includeUnlistedWhenSlugIs
- One-pager support done 0.1 c.f.
excludeChildrenWhenTemplateIs
- Include image sitemap
<image:image>
-
<image:loc>
done 0.2 -
<image:caption>
-
<image:title>
-
<image:license>
- Exclude image sitemap; c.f.
disableImages
done 0.3 - Exclusion of individual pages – done 0.2 c.f.
excludePageWhenSlugIs
- Exclusion of pages by template – done 0.1 c.f.
excludePageWhenTemplateIs
- Better heuristics for
<lastmod>
(e.g.modifiedat
field?) -
Overriding of stylesheet - Disable stylesheet
- Remove credits
- robots.txt
- Cache done 0.4 c.f.
cacheTTL
- Automate GitHub release – gothub? github-release-notes?
- Inform search engine crawlers when map changes
- Guard 50,000 URLs limit
- Guard 50MB limit
- Sitemap Index files
- Video sitemap
<video:video>
If your kirby3-based site is managed using-composer, simply invoke composer require --no-dev omz13/kirby3-xmlsitemap
, or add omz13/kirby3-xmlsitemap
to the "require" component of your site's composer.json
as necessary, e.g. to be on the bleeding-edge:
"require": {
...
"omz13/kirby3-xmlsitemap": "@dev",
...
}
Clone github.com/omz13/kirby3-xmlsitemap into your site/plugins
and then in site/plugins/kirby3-xmlsitemap
invoke composer update --no-dev
to generate the vendor
folder and the magic within.
$ git clone github.com/omz13/kirby3-xmlsitemap site/plugins/kirby3-xmlsitemap
$ cd site/plugins/kirby3-xmlsitemap
$ composer update --no-dev
If your project itself is under git, then you need to add the plugin as a submodule and possibly automate the composer update; it is assumed if you are doing this that you know what to do.
So you want everything in a zip file you can simply expand into site/plugins/kirby3-xmlsitemap
? Not yet. Sorry.
The following mechanisms can be used to modify the plugin's behaviour.
In your site's site/config/config.php
the following entries prefixed with omz13.xmlsitemap.
can be used:
disable
: a boolean which, if true, to disable the xmlsitemap functionality (c.f.xmlsitemap
in viasite.txt
).cacheTTL
: the number of minutes that the xml-sitemap should be cached before being regenerated; if explicitly set to zero, the cache is disabled. If not specified a default of 10 minutes is assumed.debugqueryvalue
: a string to be as the value for the query parameterdebug
to return the xml-sitemap with debugging information (as comment nodes within the xml stream). The global kirbydebug
configuration must also be true for this to work. The url must be to/sitemap.xml?debug=debugqueryvalue
and not/sitemap?debug=_debugqueryvalue_
(i.e. the.xls
part is important). Be aware that the debugging information will show, if applicable, details of any pages that have been excluded (so if you are using this in production and you don't want things to leak, setdebugqueryvalue
to something random). Furthermore, the site debug flag needs to be set too (i.e. thedebug
flag insite/config.php
).includeUnlistedWhenSlugIs
: an array of slugnames whose pages are to be included if their status is unlisted.excludePageWhenTemplateIs
: an array of templates names whose pages are to be excluded from the xml-sitemap.excludePageWhenSlugIs
: an array of slug names whose pages are to be excluded from the xml-sitemap.excludeChildrenWhenTemplateIs
: an array of templates names whose children are to be ignored (but pages associated with the template is to be included); this is used for one-pagers (where the principal page will be included and all the 'virtual' children ignored).disableImages
: a boolean which, if true, disables including data for images related to pages included in the xml-sitemap.
For example, for the Kirby Starter Kit, the following would be applicable:
<?php
return [
'omz13.xmlsitemap.cacheTTL' => 60,
'omz13.xmlsitemap.includeUnlistedWhenSlugIs' => [ ],
'omz13.xmlsitemap.excludePageWhenTemplateIs' => [ 'contact','sandbox' ],
'omz13.xmlsitemap.excludePageWhenSlugIs' => [ 'form' ],
'omz13.xmlsitemap.excludeChildrenWhenTemplateIs' => [ 'events','one-pager','shop','team','testimonials' ],
],
];
For experimental purposes this plugin implements a single-level pseudo-namespace. You can mix discrete vs array options, but try not to, and be aware that priority is given to the array variant. The above discrete configuration would therefore become:
<?php
return [
'omz13.xmlsitemap' => [
'cacheTTL' => 60,
'includeUnlistedWhenSlugIs' => [ 'about' ],
'excludePageWhenTemplateIs' => ['contact','sandbox'],
'excludePageWhenSlugIs' => [ 'form' ],
'excludeChildrenWhenTemplateIs' => [ 'events','one-pager','shop','team','testimonials' ],
'disableImages' => false,
],
];
See Kirby3's issue #761 for more about namespaced options.
And to have a debugged sitemap returned at /sitemap.xml?debug=wombat
, it would be:
<?php
return [
'debug' => true,
'omz13.xmlsitemap' => [
'omz13.xmlsitemap.debugqueryvalue' => 'wombat,'
'omz13.xmlsitemap.includeUnlistedWhenSlugIs' => [ ],
'omz13.xmlsitemap.excludeChildrenWhenTemplateIs' => ['events','one-pager','shop','team','testimonials'],
'omz13.xmlsitemap.excludePageWhenTemplateIs' => ['contact','sandbox'],
'omz13.xmlsitemap.excludePageWhenSlugIs' => [ 'form' ],
],
];
The plugin can be explicitly disabled in content\site.txt
by having an entry for xmlsitemap
and setting this to false
. This could be achieved through the panel by adding the following into site/blueprints/site.yml
:
type: fields
fields:
xmlsitemap:
label: XML sitemap
type: toggle
default: off
text:
- disabled
- enabled
If a page's content has a field called excludefromxmlsitemap
and this is set to true
, then that page (and any children, if present) will be excluded. Similarly to site.txt
, this can be easily achieved in a blueprint.
type: fields
fields:
excludefromxmlsitemap:
label: Exclude from sitemap.xml
type: toggle
default: off
text:
- include implicitly
- explicitly exclude
As pages are implicitly included within a sitemap, this mechanism should only be used when you have a reason to explcitly exclude a page when it is not possible to do otherwise (e.g. using excludePageWhenTemplateIs
).
To develop on this plugin, composer update --dev
will pull in the necessary packages and whatnots.
The composer
package include scripts that are useful during development:
composer lint
to lint the source (using parallel-lint)composer style
to check style issues (usingphpcs
from PHP_CodeSniffer) against coding standardomz13-k3p
in omz13/coding-standard).composer fix
to fix code style issues (usingphpcbf
from PHP_CodeSniffer)composer mess
to check for potential messes (usingphpmd
from the PHP Mess Detector)composer stan
to do static analysis of the source (usingphpstan
from the PHP Static Analysis Tool)composer sanity
to run all the above in sequence. If no errors are shown, this is good.
A makefile
is provided because:
make sanity
to check the validity of the composer file and run the sanity script (and its less keys than typingcomposer sanity
, and also because I keep mistyping it ascompsoer sanity
).make release
to relase an updated version using liip/rmt.
This plugin is provided "as is" with no guarantee. Use it at your own risk and always test it yourself before using it in a production environment. If you find any issues, please create a new issue.
You are prohibited from using this plugin in any project that promotes racism, sexism, homophobia, animal abuse, violence or any other form of hate speech.
To show your support for this project you are welcome to buy me a coffee.