README

要求: Kirby 3.0

Coffee, Beer, etc.

创建此插件投入了大量的工作。真的。只需看看源代码，因为里面有很多东西可以让你的生活更轻松（即使这意味着我不得不整天弯腰在键盘前做这个，这样你就不必了！）。谁知道遍历 kirby 3 网站的所有页面并输出正确的 xml 元素会如此有趣（我在这里用 fun 一词的意思是另一个现实中的意思）。如果你运行的是一个多语言网站，你应该非常高兴，因为它的站点地图是正确的，相信我，这比你想象的要难得多。为了好玩，以及为了避免你的处理器因为生成过程过于激烈而受到打击，结果被缓存起来，编写缓存代码也花了很多咖啡。如果你给这个仓库点星，我也会得到多巴胺的刺激。所以，请给它点星。求你了！

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

文档

目的

对于 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 被排除。
- 具有返回 true 的方法 issunset 的页面被排除。
- 具有返回 true 的方法 isunderembargo 的页面被排除。
- 对于 "单页" 的使用，使用某些模板创建的页面的子页面可以作为下级链接被排除（参看配置中的 excludeChildrenWhenTemplateIs），但那些子页面中的任何图像都将被包含并正常列出（这正是单页预期的工作方式）。
可以指定一个闭包来返回要包含在 sitemap 中的页面集，参看配置中的 addPages。
为了调试目的，生成的 sitemap 可以包含作为 xml 注释的额外信息；参看配置中的 debugqueryvalue。
为了调试目的，可以绕过缓存并返回显式重新生成的 sitemap；参看使用中的 nocache。

路线图

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

MVP（《loc》和《lastmod》）完成 0.1
~~<priority>~~
~~<changefreq>~~
尊重页面状态 完成 0.2
允许包含特定的未列出页面 完成 0.2 c.f. includeUnlistedWhenSlugIs
单页支持 完成 0.1 c.f. excludeChildrenWhenTemplateIs
包含图像 sitemap <image:image>
<image:loc> 完成 0.2
<image:caption>
<image:title>
<image:license>
排除图像 sitemap；c.f. disableImages 完成 0.3
排除单个页面 - 完成 0.2 c.f. 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 功能（参看 通过 site.txt 的 xmlsitemap）。
cacheTTL：xml-sitemap 在重新生成之前缓存的分钟数；如果显式设置为零，则禁用缓存。如果未指定，则默认为 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：要排除从xml-sitemap中包含的页面名称的slug名称数组。
excludeChildrenWhenTemplateIs：要忽略的子页面所属的模板名称数组（但与模板关联的页面将被包含）；这用于单页（主要页面将被包含，所有“虚拟”子页面将被忽略）。
disableImages：一个布尔值，如果为true，则禁用包含xml-sitemap中包含的页面相关的图像数据。
addPages：一个闭包，如果存在，则返回要添加的Pages集合。这是将虚拟页面添加到sitemap的方法。

示例 - 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，并在/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`

通过在content/site.txt中添加条目xmlsitemap并将此设置为false，可以在content/site.txt中显式禁用此插件。这可以通过在site/blueprints/site.yml中添加以下内容来实现

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

由于页面隐式包含在sitemap中，因此应在无法以其他方式显式排除页面时使用此机制（例如，使用excludePageWhenTemplateIs）。

PageMethods

headLinkAlternates

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

为了简化这个过程，此插件提供了一个页面方法来完成此操作。因此，在您的<head>中，只需添加

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

使用

此插件在/sitemap.xml处提供一个sitemap，以及关联的样式表'/sitemap.xls'。

因此，可以通过对这些端点进行简单的get请求来检索sitemap。

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

获取调试响应

如果网站处于调试模式，当设置了 debug 参数且其值与配置中的 debugqueryvalue 相匹配时，/sitemap.xml 将返回一个详细的调试信息响应，例如：

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

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

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 检查样式问题（使用 phpcs 从 PHP_CodeSniffer）与 omz13/coding-standard 中的 omz13-k3p 编码标准。
使用 composer fix 修复代码样式问题（使用 phpcbf 从 PHP_CodeSniffer）。
使用 composer mess 检查潜在问题（使用 phpmd 从 PHP Mess Detector）。
使用 composer stan 对源代码进行静态分析（使用 PHP Static Analysis Tool 的 phpstan）。
使用 composer sanity 依次运行所有上述命令。如果没有显示错误，则表示一切正常。

提供 makefile 是因为：

使用 make sanity 检查 composer 文件的正确性并运行完整性脚本（比直接输入 composer sanity 的键少，并且因为我经常误拼成 compsoer sanity）。
使用 make release 使用 liip/rmt 发布更新版本。

免责声明

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

许可协议

MIT

禁止您在推广种族主义、性别歧视、同性恋恐惧症、动物虐待、暴力或任何其他形式仇恨言论的项目中使用此插件。

omz13 / kirby3-xmlsitemap

维护者

详细信息

README

Coffee, Beer, etc.

文档

目的

相关插件

路线图

安装

配置

通过 `config.php`

示例 - Starter Kit的配置

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

通过`content/site.txt`

通过内容字段

PageMethods

headLinkAlternates

使用

获取调试响应

--dev

免责声明

许可协议

omz13 / kirby3-xmlsitemap

维护者

详细信息

README

Coffee, Beer, etc.

文档

目的

相关插件

路线图

安装

配置

通过 config.php

示例 - Starter Kit的配置

示例 2 - addPages的示例闭包

通过content/site.txt

通过内容字段

PageMethods

headLinkAlternates

使用

获取调试响应

--dev

免责声明

许可协议

通过 `config.php`

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

通过`content/site.txt`