README

使用此插件，您可以从您的页面生成包含资产、媒体和静态HTML文件的目录。您可以简单地将生成的文件上传到任何CDN，所有内容（除以下小例外外）仍然可以正常工作。结果是速度更快的网站，潜在漏洞更少。

示例

什么是Kirby？

Kirby 是一个高度 可定制 和 基于文件 的CMS（内容管理系统）。在安装此插件之前，请确保您已安装了最新版本的Kirby CMS，并且熟悉 插件基础知识。

如何安装插件

如果您使用composer，可以使用以下命令安装插件： composer require d4l/kirby-static-site-generator

或者，在 site/plugins 中创建一个 static-site-generator 文件夹，下载此存储库并将其内容提取到新文件夹中。

什么可以工作

• 多语言网站兼容性
• 翻译后的URL
• 资产
• 媒体（即使缩放；当使用时，文件将自动生成并复制）
• 可定制的基地址
• 可定制的复制路径
• 可定制的输出文件夹
• 在输出文件夹中保留单个文件/文件夹
• 自定义路由（点击 此处 获取更多信息）
• 自定义页面过滤（点击 此处 获取更多信息）

什么不能工作

• 动态路由（除非通过自定义路由调用 - 点击 此处 获取更多信息）
• 查询参数（除非通过javascript处理）
• 重定向/ die 或 exit 代码（这也影响了与其他某些插件的兼容性）
• Kirby 分页（只有通过自定义路由的手动分页）
• 使用文件协议直接在浏览器中打开HTML文件（绝对基地址 /）
• 与其他使用 file::version 和 file::url 组件的插件兼容

如何使用它

1) 直接（例如，从Kirby钩子中）

$staticSiteGenerator = new D4L\StaticSiteGenerator($kirby, $pathsToCopy = null, $pages = null);
$fileList = $staticSiteGenerator->generate($outputFolder = './static', $baseUrl = '/', $preserve = []);

• $pathsToCopy：如果没有提供，则使用 $kirby->roots()->assets()；设置为 [] 以跳过复制其他文件（除了媒体）
• $pages：如果没有提供，则渲染所有页面
• 使用 $preserve 保留输出文件夹中的单个文件或文件夹，例如，如果您想保留输出文件夹中的 README.md，请将 $preserve 设置为 ['README.md']；任何直接位于根级别的文件或文件夹（以 . 开头）始终保留（例如，.git）
• D4L\StaticSiteGenerator 类提供了一些公共方法，允许进行进一步的配置更改。

2) 通过触发端点

要使用此功能，请根据需要调整配置选项 d4l.static_site_generator.endpoint（应为字符串）

3) 通过使用 static-site-generator 字段

与选项2）执行相同的操作，然后在您的蓝图之一中添加一个 staticSiteGenerator 类型字段

fields:
  staticSiteGenerator:
    label: Generate a static version of the site
    # ... (see "Field options")

可用的配置选项

return [
    'd4l' => [
      'static_site_generator' => [
        'endpoint' => null, # set to any string like 'generate-static-site' to use the built-in endpoint (necessary when using the blueprint field)
        'output_folder' => './static', # you can specify an absolute or relative path
        'preserve' => [], # preserve individual files / folders in the root level of the output folder (anything starting with "." is always preserved)
        'base_url' => '/', # if the static site is not mounted to the root folder of your domain, change accordingly here
        'skip_media' => false, # set to true to skip copying media files, e.g. when they are already on a CDN; combinable with 'preserve' => ['media']
        'skip_templates' => [], # ignore pages with given templates (home is always rendered)
        'custom_routes' => [], # see below for more information on custom routes
        'custom_filters' => [], # see below for more information on custom filters
        'ignore_untranslated_pages' => false, # set to true to ignore pages without an own language
        'index_file_name' => 'index.html' # you can change the directory index file name, e.g. to 'index.json' when generating an API
      ]
    ]
];

所有这些选项仅在您使用实施选项2）或3）时相关。当直接使用D4L\StaticSiteGenerator类时，不需要配置选项。在这种情况下，可以通过调用$staticSiteGenerator->skipMedia(true)来实现如skip_media之类的选项。

字段选项

label: Generate static site
help: Custom help text
progress: Custom please-wait message
success: Custom success message
error: Custom error message

自定义路由

您还可以使用此插件来渲染自定义路由。这样，例如，可以通过程序创建分页。

自定义路由作为数组传递。每个项目必须至少包含一个path属性，如果路径不匹配路由，则必须设置page或route属性。

以下是一个示例数组，显示不同的配置选项

$customRoutes = [
  [ // minimal configuration to render a route (must match, else skipped)
    'path' => 'my/route',
  ],
  [ // minimal configuration to render a page
    'path' => 'foo/bar',
    'page' => 'some-page-id'
  ],
  [ // advanced configuration to render a route (write to different path)
    'path' => 'sitemap.xml',
    'route' => 'my/sitemap/route'
  ],
  [ // advanced configuration to render a page
    'path' => 'foo/baz',
    'page' => page('some-page-id'),
    'languageCode' => 'en',
    'baseUrl' => '/custom-base-url/',
    'data' => [
      'foo' => 'bar'
    ]
  ]
];

仅支持不带language范围的GET路由（您当然可以为多种语言添加多个自定义路由）。支持模式和操作参数。

page作为包含页面ID的字符串提供，或作为页面对象。

如果没有提供languageCode，则默认语言将渲染给定的页面。

如果没有提供baseUrl，则使用默认的基本URL。

path也可能以文件名结尾，在这种情况下，将创建给定的文件而不是使用<path>/index.html方案。

要向控制器或模板传递自定义数据，请使用data。有关更多信息，请点击此处。

⚠️ 如果您想根据特定页面动态生成自定义路由或将页面指向配置中的页面，请查看此处。Kirby为此目的提供了一个ready选项。

定义自定义路由有两种方式

1) 直接使用此插件时

$staticSiteGenerator->setCustomRoutes($customRoutes);

2) 通过配置使用端点或static-site-generator字段

'd4l.static_site_generator.custom_routes' => $customRoutes

自定义过滤器

当使用端点或static-site-generator字段时，此插件默认会渲染所有页面及其子页面（使用pages()->index()）。您可以通过在配置选项custom_filters中提供自定义过滤器数组来过滤要渲染的页面。

'd4l.static_site_generator.custom_filters' => $customFilters

此数组中的每个元素都必须是$pages->filterBy()方法接受的参数数组。以下是一个示例数组，显示您可以使用的一些过滤器（不完整）

$customFilters = [
  ['slug', '==', 'foo'], // will render page if its slug is exactly 'foo'
  ['url', '!*=', 'bar'], // will render page if its url doesn't contain 'bar'
  ['uri', '*', '/[1-9]/'], // will render page if its uri match regex '/[1-9]/'
  ['depth', '>', '2'], // will render page if its depth is greater than 2
  ['category', 'bar'], // will render page if its value in 'category' field is 'bar' ('category' being a single value field)
  ['tags', 'bar', ','], // will render page if its value in 'tags' field includes 'bar' ('tags' being a field accepting a comma-separated list of values)
  ['date', 'date >', '2018-01-01'], // will render page if its date is after '2018-01-01'
];

⚠️ 同样，您可以使用Kirby的ready选项来动态生成自定义过滤器。

警告

指定输出文件夹时要小心，因为给定的路径（除以.开头的文件外）将在生成之前被删除！已设置安全检查以避免在指定现有非空文件夹时意外删除。

贡献

欢迎反馈和贡献！

对于提交信息，我们遵循gitmoji指南 😃 以下是一个修复错误的示例提交信息：🐛修复单个文件的复制

请在我们的问题跟踪器中发布所有错误报告。我们已准备好模板，这将使描述错误变得更加容易。