README

需求： Kirby 3.0

咖啡、啤酒等

为创建此插件投入了巨大的工作量。真的。如果你敢看源代码，你会发现里面有很多东西可以使你的生活变得更轻松（即使这意味着我必须整天趴在键盘上工作，让你不用这么做！）。谁知道遍历 kirby 3 网站的所有页面并生成正确的 XML 元素会如此有趣（我在这里使用“有趣”这个词有它的另类现实意义）。如果你运营一个多语言网站，你应该会很高兴，因为它可以正确生成网站地图，相信我，这比你想象的要难得多。为了好玩，为了防止你的处理器因为生成过程过于激烈而受损，结果被缓存了，编写缓存代码时喝了很多咖啡。如果你为这个存储库星标，我还会得到多巴胺的刺激。所以请给它星标吧。求你了！

此插件免费，但如果你在商业项目中使用它来表示你的支持，欢迎（强烈鼓励）

文档

目的

对于 kirby3 网站，此插件（omz13/xmlsitemap）会在 /sitemap.xml 自动生成基于 XML 的网站地图，并提供一个供人类使用的美化器（/sitemap.xsl）。

生成网站地图；也有效。
适用于单语言和多语言网站。
对于多语言网站，为每种语言生成一个条目（<url>），在每个 <loc> 中都有相应的 <xhtml:link> 成员，每个语言一个，并从语言的配置 locale 计算出 hreflang），以及根据网站默认语言的一个额外伪语言 x-default。
生成的页面可以缓存一定时间，参照配置中的 cacheTTL。这不仅提高了响应时间，如果可以从缓存中检索到，而且也减少了服务器 CPU 的负载（因为生成它需要努力）。
对于所有页面，提供 <loc> 和 <lastmod>；不提供 <priority>，因为“它只是一堆噪音”；也不提供 <changefreq>，因为它不会影响排名。
<lastmod> 是通过页面字段中名为 updatedat 的日期计算得出的，如果没有，则从字段 date 中获取；如果都没有找到，则基于页面内容文件的修改时间（如果失败，则基于创建时间）。
如果未禁用，当页面包含在 xml-sitemap 中时，会包含每个页面上图像的信息（<image:loc>）；参照配置中的 disableImages。
生成的 sitemap.xml 有一个配套的 sitemap.xsl，用于生成供人类消费的美化页面。
仅包含状态为“已发布”的页面（其他内容，如草稿和未列出，均被排除）。
可以根据以下标准按顺序排除页面或其子页面：
- 主页始终被包含。
- 错误页面始终被排除。
- 仅包含状态为“已发布”的页面，即那些具有“草稿”或“未发布”状态的页面被排除。
- 可以根据其slugname显式包含未发布的页面；参见配置中的includeUnlistedWhenSlugIs。
- 可以根据其模板显式包含未发布的页面；参见配置中的includeUnlistedWhenTemplateIs。
- 使用某些模板制作的页面可以被排除；参见配置中的excludePageWhenTemplateIs。
- 具有某些slugname的页面可以被排除；参见配置中的excludePageWhenSlugIs。
- 包含内容字段excludefromxmlsitemap且值为true的页面被排除。
- 包含方法issunset且返回值为true的页面被排除。
- 包含方法isunderembargo且返回值为true的页面被排除。
- 对于“单页”使用，使用某些模板制作的页面的子页面可以作为下级链接被排除（参见配置中的excludeChildrenWhenTemplateIs），但那些子页面中的任何图片将正常包含和列出（这正是单页期望的工作方式）。
可以指定一个闭包来返回要包含在网站地图中的页面集，参见配置中的addPages。
出于调试目的，生成的网站地图可以包含额外的信息作为xml注释；参见配置中的debugqueryvalue。
出于调试目的，可以绕过缓存并显式重新生成网站地图；参见使用中的nocache。

路线图

计划功能和实现说明的非约束性列表是：

MVP (loc和lastmod) 完成0.1
~~<priority>~~
~~<changefreq>~~
尊重页面状态 完成0.2
允许包含特定的未列出页面 完成0.2 参见includeUnlistedWhenSlugIs
单页支持 完成0.1 参见excludeChildrenWhenTemplateIs
包含图片网站地图<image:image>
<image:loc> 完成0.2
<image:caption>
<image:title>
<image:license>
排除图片网站地图；参见disableImages 完成0.3
排除单个页面 – 完成0.2 参见excludePageWhenSlugIs
按模板排除页面 – 完成0.1 参见excludePageWhenTemplateIs
更好的<lastmod>启发式方法（例如modifiedat字段？）
~~覆盖样式表~~
禁用样式表
移除致谢
robots.txt - 与omz13/kirby3-wellknown一起工作
缓存 完成0.4 参见cacheTTL
自动化GitHub发行版 – gothub？github-release-notes？
当地图发生变化时通知搜索引擎爬虫
保护50,000个URL限制
保护50MB限制
站点地图索引文件
视频站点地图 <video:video>
支持多语言网站 - 完成 0.5 需要 kirby 3.0.0-beta-6.16 或更高版本
ML站点地图中的 x-default 完成 0.5
如何防止 sitemap.xml 被缓存？
绕过缓存并返回新鲜生成的站点地图，例如，在“用法”中的 nocache。

如果您想实现这些功能或其他功能，请给我咖啡（或EUR或USD）。

安装

根据您的认识论模型选择以下选项之一

composer require omz13/kirby3-xmlsitemap；插件将自动出现在 site/plugins 中。
下载最新版本的zip文件 - master.zip - 并将内容复制到您的 site/plugins/kirby3-xmlsitemap。
git submodule add https://github.com/omz13/kirby3-xmlsitemap.git site/plugins/kirby3-xmlsitemap.

记录在案：使用composer安装很酷；支持通过zip和子模块安装确实很痛苦，尤其是作为一个通过composer安装的人，所以请感到内疚地给我咖啡、啤酒等，因为这是为了您的利益，而不是我的（是的，我宁愿花时间在温暖阳光的地方，而不是在键盘前弯腰，外面在下雪，温度计显示没有超过0C的倾向）。

配置

以下机制可用于修改插件的行为。

通过 `config.php`

在您的网站的 site/config/config.php 中，可以使用以下带有 omz13.xmlsitemap. 前缀的条目

disable：一个布尔值，如果为true，则禁用xmlsitemap功能（参看 via site.txt 中的 xmlsitemap）。
cacheTTL：xml-sitemap在重新生成之前应缓存的分钟数；如果明确设置为0，则禁用缓存。如果没有指定，则假定默认值为10分钟。
hideuntranslated：一个布尔值，如果为true，则将任何未翻译的页面（对于多语言网站）从站点地图中排除（感谢 @mauricerenck 的想法）。
debugqueryvalue：一个字符串，用作查询参数 debug 的值，以返回包含调试信息的xml-sitemap（作为xml流中的注释节点）。必须将全局kirby debug 配置设置为true才能使此功能正常工作。URL必须是到 /sitemap.xml?debug=debugqueryvalue 的，而不是 /sitemap?debug=_debugqueryvalue_（即.xls部分很重要）。请注意，调试信息将显示（如果适用）任何被排除的页面的详细信息（因此，如果您在生产中使用此功能并且不想泄露信息，请将debugqueryvalue设置为随机的值）。此外，还需要设置站点调试标志（即在site/config.php中的debug标志）。
includeUnlistedWhenSlugIs：要包括其状态为未列出时其页面将被包含的slug名称数组。
includeUnlistedWhenTemplateIs：要包括其状态为未列出时其页面将被包含的模板名称数组。
excludePageWhenTemplateIs：要排除的模板名称数组，其页面不应包含在xml-sitemap中。
excludePageWhenSlugIs：要排除的slug名称数组，其页面不应包含在xml-sitemap中。
excludeChildrenWhenTemplateIs : 要忽略子元素的模板名称数组（但包含该模板的页面将被包含）；此功能用于单页文档（主要页面将被包含，所有“虚拟”子页面将被忽略）。
disableImages : 一个布尔值，如果为真，将禁用包含xml-sitemap中包含的页面相关的图像数据。
addPages : 一个闭包，如果存在，则返回要添加的Pages集合。这是将虚拟页面添加到网站地图的方式。

示例 - Starter Kit的配置

对于Kirby Starter Kit，以下配置适用：

<?php

return [
  'omz13.xmlsitemap.cacheTTL' => 60,
  'omz13.xmlsitemap.includeUnlistedWhenSlugIs' => [ ],
  'omz13.xmlsitemap.includeUnlistedWhenTemplateIs' => [ ],
  'omz13.xmlsitemap.excludePageWhenTemplateIs' => [ 'contact','sandbox' ],
  'omz13.xmlsitemap.excludePageWhenSlugIs' => [ 'form' ],
  'omz13.xmlsitemap.excludeChildrenWhenTemplateIs' => [ 'events','one-pager','shop','team','testimonials' ],
  ],
];

出于实验目的，此插件实现了一个单级伪命名空间。您可以混合离散与数组选项，但尽量不要这样做，并且请注意，优先级给予数组变体。因此，上述离散配置将变为：

<?php

return [
  'omz13.xmlsitemap' => [
    'cacheTTL' => 60,
    'includeUnlistedWhenSlugIs' => [ 'about' ],
    'includeUnlistedWhenTemplateIs' => [ ],
    'excludePageWhenTemplateIs' => ['contact','sandbox'],
    'excludePageWhenSlugIs' => [ 'form' ],
    'excludeChildrenWhenTemplateIs' => [ 'events','one-pager','shop','team','testimonials' ],
    'disableImages' => false,
  ],
];

有关命名空间选项的更多信息，请参阅Kirby3的想法问题#32。

要返回在/sitemap.xml?debug=wombat处的调试过的网站地图，将如下所示：

<?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' ],
  ],
];

示例 2 - `addPages`的示例闭包

添加属于命名集合的页面

'omz13.xmlsitemap.addPages' => function() {
   return kirby()->collection('articles');
   }

添加特定页面

'omz13.xmlsitemap.addPages' => function() {
  $c = new Kirby\Cms\Pages;
  $c->add( kirby()->site()->find('blog/the-sweet-dessert') );
  return $c;
  }

通过`content/site.txt`

可以通过在site/blueprints/site.yml中添加以下内容，在content/site.txt中显式禁用此插件，并设置此值为false。

type:          fields
fields:
  xmlsitemap:
    label:     XML sitemap
    type:      toggle
    default:   off
    text:
      - disabled
      - enabled

通过内容字段

如果页面内容中有一个名为excludefromxmlsitemap的字段，并且此设置为true，则该页面（以及任何子页面，如果有的话）将被排除。类似于site.txt，这可以在蓝图（blueprint）中轻松实现。

type:          fields
fields:
  excludefromxmlsitemap:
    label:     Exclude from sitemap.xml
    type:      toggle
    default:   off
    text:
      - include implicitly
      - explicitly exclude

由于页面隐式包含在网站地图中，因此仅在有必要显式排除页面而无法以其他方式实现时才应使用此机制（例如使用excludePageWhenTemplateIs）。

页面方法

headLinkAlternates

如果您有一个多语言网站，除了在网站地图中包含所有不同语言的链接之外，在网站上每个页面还需要在<head>中包含<link rel="alternate" hreflang="" />元素。

为了使这变得简单，此插件提供了一个页面方法来实现。因此，在您的<head>中，只需添加：

<?= $page->headLinkAlternates(); ?>

用法

该插件在/sitemap.xml处提供网站地图，并关联一个样式表'/sitemap.xls'。

因此，可以通过对这些端点进行简单的GET请求来检索网站地图。

curl -H host:whatever.test -k https://whatever.test/sitemap.xml

获取调试响应

如果网站处于调试模式，当设置了一个匹配配置中debugqueryvalue值的debug参数时，/sitemap.xml将返回一个详细的调试填充响应。

curl -H host:whatever.test -k https://whatever.test/sitemap.xml?debug=42

在调试模式下，端点将接受一个额外的可选参数，nocache，如果为真，将绕过缓存响应并显式返回一个新鲜生成的响应。

curl -H host:whatever.test -k https://whatever.test/sitemap.xml?debug=42&nocache=1

--dev

要开发此插件，请执行composer update --dev以拉取必要的包和其他相关内容。

composer包包含在开发期间有用的脚本。

composer lint用于检查源代码（使用parallel-lint）。
composer style用于检查样式问题（使用PHP_CodeSniffer的phpcs），与位于omz13/coding-standard中的编码标准omz13-k3p进行比较。
composer fix用于修复代码样式问题（使用来自PHP_CodeSniffer的phpcbf）。
composer mess 用于检查潜在的错误（使用来自 PHP Mess Detector 的 phpmd）
composer stan 用于对源代码进行静态分析（使用来自 PHP Static Analysis Tool 的 phpstan）
composer sanity 依次运行上述所有操作。如果没有错误显示，则表示一切正常。

提供了一个 makefile 因为

make sanity 用于检查 composer 文件的正确性并运行检查脚本（比直接输入 composer sanity 简便，而且因为我经常不小心将其误写为 compsoer sanity）。
make release 用于使用 liip/rmt 发布更新版本。

免责声明

此插件提供“原样”且无任何保证。请在自己的风险下使用，并在将其用于生产环境之前始终自行测试。如果您发现任何问题，请创建新问题。

许可

MIT

禁止您将此插件用于任何宣传种族主义、性别歧视、恐同、动物虐待、暴力或其他任何形式仇恨言论的项目。

wearejust / kirby3-xmlsitemap

维护者

详细信息

README

咖啡、啤酒等

文档

目的

相关插件

路线图

安装

配置

通过 `config.php`

示例 - Starter Kit的配置

示例 2 - `addPages`的示例闭包

通过`content/site.txt`

通过内容字段

页面方法

headLinkAlternates

用法

获取调试响应

--dev

免责声明

许可

wearejust / kirby3-xmlsitemap

维护者

详细信息

README

咖啡、啤酒等

文档

目的

相关插件

路线图

安装

配置

通过 config.php

示例 - Starter Kit的配置

示例 2 - addPages的示例闭包

通过content/site.txt

通过内容字段

页面方法

headLinkAlternates

用法

获取调试响应

--dev

免责声明

许可

通过 `config.php`

示例 2 - `addPages`的示例闭包

通过`content/site.txt`