README

要求: Kirby 3.0.0-RC3 或更高版本

咖啡，啤酒等

这最初是一个简单的插件，后来变得相当复杂，以应对在尝试从 Kirby 获取有意义的内容的同时，也试图在限制性的聚合格式中生成可接受的内容。

此插件是免费的，但如果您将其用于商业项目以表示支持，您可以通过以下方式捐赠

• 捐赠 🍻 或
• 买我 ☕☕ 或
• 使用此联盟链接购买 Kirby 许可证

文档

目的

对于 kirby3 网站，此插件（omz13/feeds）根据 Kirby3 的 "集合" 生成 RSS、ATOM 和 JSON 格式的聚合源。如果集合中给出一个页面，它将被包括在聚合源中；因此，请确保集合过滤器 "已发布" 或 "草稿" 符合您的要求，因为此插件根本不进行筛选（因为您可能想要有一个草稿源）。您控制着哪些内容被放入源中（这可以与网站上公开显示的内容不同）。

• Kirby3 "集合" 到 atom/json/rss-feed 方法。
• 基于默认集合生成 RSS 2.0 聚合源（在 /feeds/rss），参照 配置 中的 firehose。
• 基于默认集合生成 ATOM 聚合源（在 /feeds/atom）。
• 基于默认集合生成 JSON 1 聚合源（在 /feeds/json）。
• 在 feeds/<category>/atom|json|rss）生成子集聚合源，其中 <category> 映射到 Kirby 集合，参照 配置 中的 categories。
• 源将包含最多 60 个项目。
• 为了减轻服务器负载并快速响应，生成的源将在服务器上缓存一定时间，参照 配置 中的 cacheTTL。
• 支持 HTTP 条件获取（强验证）：即尊重 If-Modified-Since 和 If-None-Match 头部，并在适当的情况下返回 304 Not Modified 响应（节省带宽）。
• 以下数据是从页面字段（及其使用取决于所使用的源格式）推导出来的
  • 要归因的作者来自 author 字段：此字段可以是结构化字段或文本字段，但它应该是作者的电子邮件地址（并将用于将其映射到 Kirby 用户以获取其详细信息）。如果无法将作者映射到用户，则应用默认值，参照 配置 中的 author。
  • 标题来自 title，一个字符串。
  • 修改日期按优先级顺序来自：updatedat、date；注意：如果这两个都无法解决，则使用页面底层文件的修改时间属性。
  • 发布日期的优先顺序为：date，updatedat；注意：如果这些都不能解析，则使用页面底层文件的修改时间属性。
• 对于ATOM和JSON订阅源，作者细节通过其用户（按优先顺序）的website或twitter或instagram数据映射到uri。
• 如果项目有多个作者
  • 对于RSS和JSON订阅源，作者将使用作者的姓名连接（例如，如果作者是Ford和Zaphod，他们将归因于“Ford and Zaphod”）。
  • 对于RSS，每个作者还将在<dc:creator>中单独列出。
  • 对于JSON，每个作者的详细信息在brentsimmons/JSONFeed#120中给出。这是非常实验性的，可能会破坏某些东西 - 欢迎您的反馈。
• 对于RSS订阅源，还提供每个项目的<dc:date>和频道的<dc:rights>。
• 对于JSON订阅源，除了在content_html中提供HTML内容外，还提供了content_text中的Markdown版本；注意，Markdown版本是从HTML表示生成的，而不是简单的（Markdown + Kirbytext）页面内容。
• 出于调试目的，生成的网站地图可以包括额外的注释信息；参考配置中的debugqueryvalue。输出可能仍然可以用读者使用，但它的目的是调试而不是消费。

警告

• 已撤回的页面（即，方法issunset返回true）可以通过集合内的适当配置排除。
• 处于禁令下的页面（即，方法isunderembargo返回true）可以类似地管理。
• 可能存在错误，因为需要处理各种聚合规范中的边缘情况的代码非常多；尽可能生成尽可能好的内容（即，合理的假设）。

客户端支持

RSS订阅源通常得到客户端的良好支持；ATOM订阅源提供了一些额外的技术优点，但客户端支持各异；JSON格式非常新，客户端支持各异。以下是几个我使用的客户端的详细信息

关于OS X的客户端

• Readkit，支持RSS和ATOM，但不支持JSON；它对将名称解析为主机的做法非常挑剔（并且只会抱怨“无效源”而不是真正说出它认为哪里出错了）。
• ReederApp支持所有三种格式。
• Leaf支持RSS和ATOM - 注意：自2017年11月以来没有更新。
• NetNewsWire - 支持所有三种格式 - 注意：v5已经回到了Brent，所以目前非常alpha。
• NewsExplorer - 支持所有三种格式。
• Vienna支持RSS和ATOM，但不支持JSON。

关于iOS

• Readkit - 参见OS X
• ReederApp - 参见OS X
• NewsExplorer（也支持Apple TV！）

关于通用服务/客户端

• FeedBin
• Feedly支持RSS
• FeedWrangler
• NewsBlur支持所有三种格式。

关于Windows客户端：抱歉，我住在OS X/iOS的世界里，对此一无所知。

相关插件

对于提供 issunset 和 isunderembargo 方法的插件，请参阅 omz13/kirby3-suncyclepages。

路线图

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

• MVP
• 链接博客
• 拆分
• 按集合来源
• 语言
• 作者进入项流
• 分类进入项流
• 生成订阅源发现头
• 为 RSS 生成 dc

安装

根据您的认知模型选择以下之一

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

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

配置

需要配置四个方面

• site/config/config.php
• content/site.txt 通过蓝图（可选）
• 订阅源发现
• 集合

site/config/config.php

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

• disable - 可选 - 布尔 - 默认 false - 一个布尔值，如果为 true，则禁用服务聚合源。此类页面的请求将收到 503 Service Unavailable。
• cacheTTL - 可选 - 整数 - 默认 10 - 在重新生成之前应该缓存聚合源的时间（分钟数）；如果明确设置为零，则禁用缓存。如果没有指定，则假定默认值为10分钟。
• firehose - 可选 - 字符串 - 默认 'articles' - 用于 'firehose' 聚合源 /feeds/atom|json|rss 的 kirby 集合的名称。
• categories - 可选 - 数组 - 默认 [ 'articles' ] - 可以通过 uri /feeds/<category>/atom|json|rss 访问的 kirby 集合的名称。如果指定为空数组（[]），则禁用此功能。
• debugqueryvalue - 可选 - 字符串 - 返回包含调试信息的聚合源（作为响应中的注释）的查询参数 debug 的值。必须将全局 kirby debug 配置设置为 true 才能使用此功能。请注意，如果适用，调试信息将显示被排除的任何页面的详细信息（因此，如果您在生产中使用此功能并且不想泄露信息，请将 debugqueryvalue 设置为随机的值）。此外，还需要设置站点调试标志（即 site/config.php 中的 debug 标志）。
• author - 可选 - 字符串 - 默认 'Staff Writer' - 当作者未知或聚合格式不允许作者名称时（看着你 RSS2）用于聚合源中每个项目的名称。

content/site.txt（通过蓝图 site/blueprints/site.yml）

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

type:          fields
fields:
  feeds:
    label:     Syndication
    type:      toggle
    default:   off
    text:
      - RSS disabled
      - RSS enabled

如果 content/site.txt 中没有 feeds 的条目，则假设插件未禁用（即默认为 false）。

订阅源发现

至少需要将适当的订阅源发现链接添加到您网站的首页。

此插件提供两个代码片段以动态生成必要的元数据

• feeds-header - 提供所有订阅源（数据洪流和基于类别的）的链接
• firehose-feeds-header - 仅提供数据洪流订阅源的链接。

或者对于那些喜欢使用 pageMethods 的人来说，上面的等效代码是

• headFeeds
• headFirehoseFeeds

示例

在 site/snippets/header.php - 或生成您的 <head> 数据的任何文件 - 在最合适的位置添加 <?php snippet('feeds-header') ?> 或 <?= $page->headFeeds() ?>。

如果插件被禁用，这些代码片段将不会生成适当的订阅源发现链接。

集合

对于默认（数据洪流）聚合订阅源，您需要确保您有一个集合并已对其进行配置。通常这将是“文章”集合，例如：

<?php

return function ($site) {
    return $site->find('blog')->children()->listed()->flip();
};

如果您使用 omz13/suncyclepages 进行封存和撤回，那么它将是：

<?php

return function ($site) {
	    return $site->find('blog')->children()->listed()->isunderembargo(false)->issunset(false)->flip();
};

使用

例如，对于 Kirby Starter Kit，以下内容适用：

<?php

return [
  'omz13.feeds.cacheTTL' => 60,
  'omz13.feeds.firehose' => 'articles',
  ],
];

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

<?php

return [
  'omz13.feeds' => [
    'cacheTTL' => 60,
    'firehose' => 'articles',
  ],
];

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

免责声明

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