README

这是Pico官方robots插件的仓库。

Pico是一个非常简单、速度极快、基于平面文件的CMS。更多信息请访问 http://picocms.org/。

PicoRobots 是一个简单的插件，可以为您的网站添加 robots.txt 和 sitemap.xml 文件。robots exclusion protocol (robots.txt) 和 Sitemaps protocol (sitemap.xml) 都用于与网络爬虫和其他网络机器人通信。robots.txt 通知网络机器人不应处理或扫描您网站上的哪些区域。sitemap.xml 允许网络机器人更智能地爬取您的网站。sitemap.xml 是一个URL包含协议，与URL排除协议 robots.txt 相辅相成。

安装

PicoRobots 需要 Pico 2.0+

如果您使用的是基于 composer 的 Pico 安装（例如 picocms/pico-composer），只需在您的服务器上打开一个shell，导航到Pico的安装目录（例如 /var/www/html），然后运行 composer require phrozenbyte/pico-robots（通过 Packagist.org）。就这样！

如果您正在使用 Pico的预构建发布包 之一，您需要首先在您的服务器上的Pico安装目录（例如 /var/www/html）中创建一个空的 plugins/PicoRobots 目录。然后下载 PicoRobot 的最新源代码包，并将所有包含的文件（特别是 PicoRobots.php 和 theme 目录）上传到该 plugins/PicoRobots 目录。

就这样！您的 plugins 目录中的结构应该如下所示

plugins/
└── PicoRobots/
	 ├── PicoRobots.php
	 └── theme/
		 ├── robots.twig
		 └── sitemap.twig

您可以将 theme 目录复制到您自己的主题目录 ./themes/yourtheme 下。这使您能够在不修改插件文件的情况下覆盖插件模板。即使在这种情况下，您仍然需要保留该插件原始的 theme 目录及其内容在 ./plugins/PicoRobots 中。

配置

安装 PicoRobots 后，您可以使用您最喜欢的网络浏览器导航到您的 robots.txt（http://example.com/pico/robots.txt）和 sitemap.xml（http://example.com/pico/sitemap.xml）。如您所见，默认情况下，robots.txt 仅通过引用您的网站上的 sitemap.xml。默认的 sitemap.xml 列出您网站上的所有页面，其最后修改时间由您的服务器的操作系统报告的Markdown文件的最后修改时间指定。非常方便，对吧？

一如既往，您可以根据自己的需求调整 PicoRobot 的行为。首先，我们将从 robots.txt 开始

关于 robots.txt 的更多信息

《robots.txt》由任意数量的URL排除规则组成，这些规则由段落分隔（即一个空行）。一个规则由一个或多个User-agent行组成，用于指定哪些网络爬虫受影响，以及一个或多个Disallow行，用于指定哪些URL不应被该网络爬虫处理或扫描。可选地，您可以添加一个或多个Allow行来指定对Disallow行的例外。有关更多信息，请参阅维基百科关于robots排除协议的文章。

您可以通过Pico的config/config.yml（或任何位于config目录中的其他配置文件，例如config/PicoRobots.yml）来添加到您的robots.txt中的URL排除规则。与其广泛描述配置语法，不如一个示例胜过千言万语。因此，通过在您的config/config.yml中添加以下配置

PicoRobots:
  robots:
    - user_agents: "BadBot"
      disallow: "/"
    - user_agents: "*"
      disallow: [ "/private/", "/admin/" ]
      allow: "/private/about_me"

您将在您的robots.txt中得到以下两个规则

User-agent: BadBot
Disallow: /

User-agent: *
Disallow: /private/
Disallow: /admin/
Allow: /private/about_me

第一个规则（第1行和第2行）告诉BadBot（User-agent: BadBot）不要爬取您的网站（Disallow: /）。第二个规则（第4行至第7行）告诉任何其他网络爬虫（User-agent: *）不要爬取您的网站上的private（Disallow: /private/）和admin（Disallow: /admin/）文件夹。作为这个例外的例外，爬取private/about_me页面（Allow: /private/about_me）是可以的。这隐含地也告诉任何网络爬虫（除了BadBot）爬取您的网站基本上是允许的。

robots.txt不会以任何方式影响Pico的YAML Frontmatter中的Robots元标题（只要您的主题使用该信息向您的网站添加一个<meta name="robots" content="..." />标签）。您应该使用Robots元标题而不是robots.txt来拒绝爬取单个页面。

PicoRobots使用theme/robots.twig模板来创建robots.txt的内容。如果您想在robots.txt中添加一些自定义逻辑，只需在您的主题中添加一个robots.twig，并使用PicoRobot的theme/robots.twig作为起点。Pico将自动使用您的主题的robots.twig而不是默认的PicoRobot。

此外，插件还提供了一个简单的API，允许其他插件访问并添加到您的robots.txt中的URL排除规则。作为插件开发者，您可以使用PicoRobots::getRobots()方法获取所有URL排除规则的列表。PicoRobots还触发自定义的onRobots(array &$robots)事件，以下载载数据，允许您向网站的robots.txt添加自定义规则。

$robots = [
    [
        'user_agents' => string[],  /* list of user agents, or '*' to match all web robots */
        'disallow'    => string[],  /* list of URLs that shouldn't be crawled */
        'allow'       => string[]   /* list of disallowed URLs that are allowed to be crawled even though */
    ],
    …
]

请注意，您的robots.txt中的URL排除规则不会以任何方式影响由PicoRobots创建的您的网站sitemap.xml。

更多关于sitemap.xml

sitemap.xml是一种基于XML的协议，用于帮助网络爬虫更智能地爬取您的网站。它包含一个或多个<url>记录，告诉网络爬虫哪些URL（<loc>标签）应该被爬取。您可以可选地告诉网络爬虫页面最后修改的时间（<lastmod>标签）以及页面可能更改的频率（<changefreq>标签，可能的值有always、hourly、daily、weekly、monthly、yearly和never）。通过添加可选的<priority>标签，您可以建议网络爬虫哪些页面被认为比其他页面更重要（有效范围是0.0到1.0，其中1.0是最重要的；默认值是0.5）。有关更多信息，请参阅维基百科关于Sitemaps协议的文章。

PicoRobot 的默认 sitemap.xml 列出了您网站的所有页面，并使用服务器操作系统中 Markdown 文件的最后修改时间指定的最后修改时间。如果您不希望某个页面出现在 sitemap.xml 中，只需将该页面的 YAML 前置元信息中的 Sitemap: false 添加到页面即可。PicoRobots 会自动排除不可访问的页面（文件名以 _ 开头的页面）以及具有 Robots: noindex 元信息的页面。

Sitemap 元信息还可以用来指定一个页面的更改频率和优先级，以及覆盖页面的最后修改时间。如果您想告诉网络爬虫一个页面通常每周更改一次，最后更改于 2017 年 12 月 1 日，并且优先级提高至 0.7，请将以下内容添加到该页面的 YAML 前置元信息中：

Sitemap:
    lastmod: 2017-12-01
    changefreq: weekly
    priority: 0.7

您还可以使用 Pico 的 config/config.yml（或 config 目录中的任何其他配置文件，例如 config/PicoRobots.yml）来向您的 sitemap.xml 添加更多记录。如果您想将动态创建的页面 team/max-mustermann（该页面由插件动态创建，没有 content/team/max-mustermann.md，因此默认不在 sitemap.xml 中）的记录添加到您的 sitemap.xml 中，请将以下内容添加到您的 config/config.yml 中：

PicoRobots:
  sitemap:
    - url: %base_url%?team/max-mustermann
      changefreq: yearly

以在您的 sitemap.xml 中获得以下记录：

    <url>
        <loc>http://example.com/pico/team/max-mustermann</loc>
        <changefreq>yearly</changefreq>
    </url>

如您所见，PicoRobots 解释 %base_url% 占位符的方式与 Markdown 文件中相同，并将其替换为网站的基准 URL。与页面 YAML 前置元信息中的 Sitemap 元信息一样，您可以在配置中添加 lastmod、changefreq 和 priority 键来指定 URL 的最后修改时间、更改频率和优先级。

PicoRobots 使用 theme/sitemap.twig 模板来创建 sitemap.xml 的内容。如果您想在 sitemap.xml 中添加一些自定义逻辑，只需将 sitemap.twig 添加到您的主题中，并使用 PicoRobot 的 theme/sitemap.twig 作为起点。Pico 会自动使用您的主题中的 sitemap.twig 而不是默认的 PicoRobot。

此外，该插件还公开了一个简单的 API，允许其他插件访问并向您的 sitemap.xml 添加 sitemap 记录。作为插件开发者，您可以使用 PicoRobots::getSitemap() 方法获取所有 sitemap 记录的列表。PicoRobots 此外还会触发自定义的 onSitemap(array &$sitemap) 事件，带有以下有效负载，允许您向网站的 sitemap.xml 中添加自定义记录。

$sitemap = [
    [
        'url'              => string,   /* URL of the concerned page, including the protocol */
        'modificationTime' => int,      /* Unix timestamp of the page's last modification time */
        'changeFrequency'  => string,   /* how frequently the contents of the page may change */
        'priority'         => float     /* priority of that URL relative to other URLs on the site */
    ],
    …
]