Web Assets：Pelican 插件

此 Pelican 插件允许您使用 webassets 模块在您的网站上执行许多有用的资产管理功能，例如

• CSS 压缩（cssmin、yui_css、...）
• CSS 编译（less、sass、...）
• JS 构建（uglifyjs、yui_js、closure、...）

webassets 的其他一些有趣功能包括

• URL 过期或“缓存破坏”，允许您为您的资产设置长期缓存头，节省带宽并减少页面加载时间
• 一个 spritemapper 函数，可以自动将多个图标组合成一个大的图像，并带有相应的位置切片
• 一个 datauri 函数，通过将您的样式表中的 url() 引用替换为内部内联 data URI 来最小化 HTTP 请求的数量

要查看 webassets 可以做什么的完整列表，请查看 webassets 文档中的内置过滤器部分。

安装

由于 pip 的存在，使用 webassets 开始使用变得非常简单

python -m pip install pelican-webassets

有关插件安装的更详细说明，请参阅 Pelican 插件文档。

💡 注意：您在 {% asset filters %} 参数中使用的每个函数（稍后将有更多介绍）都需要单独安装。例如，如果您想使用 libsass 过滤器，您需要运行 pip install libsass。如果您想的话，甚至可以创建一个自定义过滤器。

使用方法

安装插件后，将一个或多个 {% assets %} 标签包含到您的网站模板中，以生成网页所需的所有内容。例如，在您的模板中如下所示...

{% assets filters="libsass,cssmin", output="css/style.min.css", "css/style.scss" %}
  <link rel="stylesheet" href="{{SITEURL}}/{{ASSET_URL}}">
{% endassets %}

…将会告诉 webassets 使用 libsass 和 cssmin 编译和压缩您的主题中的 css/style.scss 文件，并将编译后的样式表保存为 css/style.min.css 在您的完成网站输出中，以及您的网页中的如下 link 元素

<link href="{SITEURL}/{THEME_STATIC_DIR}/css/style.min.css?b3a7c807" rel="stylesheet">

🌠 更多信息：变量 ASSET_URL 是 Pelican 的 THEME_STATIC_DIR 设置、output 参数和之前提到的“缓存破坏”变量的连接。

JavaScript 示例

作为另一个例子，我们可以使用 webassets 的 closure_js 函数来合并、压缩您的网站主题中的两个文件，js/jQuery.js 和 js/widgets.js

{% assets filters="closure_js", output="js/packed.js", "js/jQuery.js", "js/widgets.js" %}
 <script src="{{SITEURL}}/{{ASSET_URL}}"></script>
{% endassets %}

生成的输出将是一个单独的 script 标签以及您的网站生成输出中的相应文件

<script src="{SITEURL}/{THEME_STATIC_DIR}/js/packed.js?00703b9d"></script>

配置

作为一个围绕 webassets 模块的非常小的包装器，您可能只需要几个选项。

WEBASSETS_DEBUG

默认情况下，如果 Pelican 在 DEBUG 模式下（pelican -D ...），此插件将把 webassets 放入 DEBUG 模式，以帮助您进行调试。要覆盖此行为，设置 WEBASSETS_DEBUG = False 以始终处理文件而不管 Pelican 的 DEBUG 标志如何，或者设置为 True 以始终强制 webassets 进入 DEBUG 模式。

# put webassets into DEBUG mode if Pelican is
WEBASSETS_DEBUG = logger.getEffectiveLevel() <= logging.DEBUG

WEBASSETS_CONFIG

某些 webassets 过滤器需要额外的配置选项才能正常工作。您可以使用 WEBASSETS_CONFIG 在一个 (键, 值) 元组列表中指定这些选项，这些元组将被传递给 webassets 环境。

WEBASSETS_CONFIG = [
  ("closure_compressor_optimization", "ADVANCED_OPTIMIZATIONS"),
  ("libsass_style", "compressed")
]

WEBASSETS_BUNDLES

资源包 是将一组资源及其文件处理信息组合在一起的一种便捷方式。通过提供一个 (name, args, kwargs) 参数列表，WEBASSETS_BUNDLES 选项允许我们创建这些资源包，并将这些参数传递给 webassets 环境。

WEBASSETS_BUNDLES = (
     ("my_bundle", ("colors.scss", "style.scss"),
     {"output': "style.min.css", "filters": ["libsass", "cssmin"]}),
)

允许您简化您网站模板中的如下内容…

{% assets filters="libsass,cssmin", output="style.min.css", "colors.scss", "style.scss" %}

…变成这样

{% assets 'my_bundle' %}

WEBASSETS_SOURCE_PATHS

如果您的原始资源不在 THEME_STATIC_PATHS 目录中，您可以使用 WEBASSETS_SOURCE_PATHS 提供额外的目录进行搜索。

WEBASSETS_SOURCE_PATHS = ["stylehseets", "javascript"]

贡献

欢迎并非常感谢贡献。每一份帮助都很有价值。您可以通过改进文档、添加缺失功能、修复错误等方式进行贡献。您还可以通过审阅和评论 现有问题 来帮忙。

要开始为这个插件做出贡献，请阅读 Pelican 贡献指南，从 贡献代码 部分开始。

许可证

本项目遵循 AGPL-3.0 许可。