Jekyll Asset Bundler

Jekyll Asset Bundler is a Jekyll plugin for... bundling assets. It is hacked onto... I mean, utilizes deep integration with Jekyll for a seamless deployment experience.

Installation

Copy or link asset_bundler.rb into your _plugins folder for your Jekyll project.

If your Jekyll project is in a git repository, you can easily manage your plugins by utilizing git submodules.

To install this plugin as a git submodule:

git submodule add git://github.com/moshen/jekyll-asset_bundler.git _plugins/asset_bundler

To update:

cd _plugins/asset_bundler
git pull origin master

Status

Currently only supports absolute asset paths in relation to your source directory. For example: /css/mystyle.css looks for a file in my_source_dir/css/mystyle.css.

Features

  • Works with Octopress
  • Custom commands for bundle compression
  • Compressed bundle caching
  • Bundling and caching of remote assets
  • Dev mode, for easy site development with all assets
  • Dev-only asset inclusion

TODO

  • Relative paths support
  • CoffeeScript and LessCSS compilation support

Notes

v0.05 - Changed from using Liquid::Tags to Liquid::Blocks. This will break on existing bundle markup if you upgrade.

Why change it? Well, Liquid::Tags have to be on one line, whereas Liquid::Blocks do not, also it opens up some more flexibility, as additional options could be included in the tag text.

v0.08 - Changed the cdn config parameter to server_url in order to be more generic. For the time being, cdn still works (see below).

Why change it? There seemed to be a little confusion about the parameter name and what the parameter does.

v0.11 - jekyll --watch now turns on dev mode. Removed code for compatibility with versions of Jekyll pre 1.0.

Why change it? jekyll --watch isn't really supported by the plugin anyway. Also, Jekyll is changing and I don't want this to be any more of an unmaintainable mess.

Is it production ready?

Consider this beta software, though for small Jekyll sites you should have no problem using it.

Usage

Once installed in your _plugins folder Jekyll Asset Bundler provides Liquid::Blocks to use which will generate the appropriate markup for including JavaScript and CSS. Each of the following blocks consumes a YAML formatted array.

Liquid::Blocks

bundle

{% bundle %} [/js/main.js, /js/somethingelse.js] {% endbundle %}

Is equal to:

{% bundle %}
- /js/main.js
- /js/somethingelse.js
{% endbundle %}

Remote assets can also be bundled:

{% bundle %}
- http://cdnjs.cloudflare.com/ajax/libs/jquery/1.7.2/jquery.min.js
- //cdnjs.cloudflare.com/ajax/libs/underscore.js/1.3.1/underscore-min.js
- https://cdnjs.cloudflare.com/ajax/libs/backbone.js/0.9.2/backbone-min.js
- /js/my_local_javascript.js
{% endbundle %}

Remote assets will be cached in the _asset_bundler_cache folder (in the same directory as your _plugins folder). If you want to regenerate cached items, delete the cache folder.

The bundle tag will concatenate the provided scripts and make a hash of the result. This hash is used as a filename. The Bundle is then compressed (if desired), and the final result cached in the _asset_bundler_cache folder. Therefore, the bundle is only recreated and compressed again if the source files have been modified. This greatly speeds up future site builds.

Note: Asset Bundler makes no attempt to clean up the cache folder. If it has grown too large, simply delete it.

The proper markup is finally inserted to include your bundle file.

bundle_glob

{% bundle_glob %}
- /js/*.js
- /css/*.css
{% endbundle_glob %}

The bundle_glob tag uses the Ruby Dir.glob method to include multiple assets. WARNING: assets will be included in alphanumeric order, this may screw something up.

dev_assets

{% dev_assets %}
- /js/less.js
{% enddev_assets %}

The dev_assets tag includes the normal markup for the referenced assets only in 'dev mode'. The array items can either be local files or urls for external scripts and are included as-is. At any other time, it does nothing. In a future version (hopefully soon), this will play a role in utilizing things like LessCSS and CoffeeScript.

Configuration

Some behavior can be modified with settings in your _config.yml. The following represents the default configuration:

asset_bundler:
  compress:
    js: false
    css: false
  base_path: /bundles/
  server_url:
  remove_bundled: false
  dev: false
  bundle_name: false
  markup_templates:
    js: "<script type='text/javascript' src='{{url}}'></script>\n"
    css: "<link rel='stylesheet' type='text/css' href='{{url}}' />\n"

Here is a breakdown of each configuration option under the top level asset_bundler key.

compress:

Compresses nothing by default. Change the js and css keys to modify compression behavior.

js:

To compress with the yui-compressor gem, use 'yui' here, to compress with the closure compiler gem, use 'closure' here.

compress:
  js: yui

To compress with a system command, enter it for the appropriate asset type:

compress:
  js: uglifyjs :infile -o :outfile -c

This example will run a uglifyjs command from your PATH while substituting :outfile and :infile for temporary files stored in _asset_bundler_cache.

If either :outfile or :infile are omitted, stdout and stdin will be used. WARNING, stdin and stdout are done with IO.popen , which doesn't work on Windows

Note: Some have reported other issues when using the yui-compressor or closure compiler gems on Windows. If you having trouble on windows, try specifying a command as outlined above.

css:

Takes the exact same arguments as js:, with the exception of the Google Closure Compiler ( it's JavaScript only ).

base_path:

Where the bundles will be copied within your destination folder.

Default: /bundles/.

server_url:

NOTE: In v0.07 and earlier this setting was cdn. The cdn key still works and will act as an alias. However, if the server_url key is set, it will override cdn.

The root path of your server_url or CDN (if you use one). For example: http://my-cdn.cloudfront.net/

Jekyll Asset Bundler checks to make sure that this setting ends in a slash.

Default: (blank).

remove_bundled:

If set to true, will remove the files included in your bundles from the destination folder.

Default: false.

dev:

NOTE: In v0.10 and earlier, dev mode was not enabled automatically for --auto or --watch mode.

If set to true, enables dev mode. When dev mode is active, no bundles are created and all the referenced files are included individually without modification.

Dev mode is also automatically enabled when using jekyll server, jekyll --watch or when a top level configuration key: dev is set to true.

Default: false.

bundle_name:

Overrides bundle name. When false, MD5 hash of the content is used instead.

Default: false.

markup_templates:

Use the relevant markup_template options to override the default templates for inserting bundles. Each option is parsed with Liquid::Template.parse and passed a url (String) parameter.

Note: if you want newlines to be passed in properly, be sure to quote your templates in _config.yml.

js:

The default JavaScript markup is fairly verbose. If you would like a modern replacement, try "<script src='{{url}}'></script>\n".

Default: "<script type='text/javascript' src='{{url}}'></script>\n"

css:

The default CSS is also verbose. If you would like a modern replacement, try "<link rel=stylesheet href='{{url}}'>\n".

Default: "<link rel='stylesheet' type='text/css' href='{{url}}' />\n"

Dependencies

Jekyll Asset Bundler uses the yui-compressor or closure-compiler gems (when configured) and (obviously) Jekyll.

Author

Colin Kennedy, moshen on GitHub

License

MIT, see LICENSE file.



Jekyll Asset Bundler

Jekyll Asset Bundler是捆绑资产的Jekyll插件。 它被黑客攻击…我的意思是,利用与Jekyll的深度整合 以实现无缝部署体验。

安装

asset_bundler.rb 复制或链接到您的 _plugins 文件夹中 为您的Jekyll项目。

如果您的Jekyll项目位于git仓库中,您可以轻松实现 通过使用git子模块管理您的插件。

要将此插件安装为git子模块:

git submodule add git://github.com/moshen/jekyll-asset_bundler.git _plugins/asset_bundler

要更新:

cd _plugins/asset_bundler
git pull origin master

状态

目前仅支持与您相关的绝对资产路径 源目录。例如: /css/mystyle.css 寻找一个文件 在 my_source_dir / css / mystyle.css

Features

  • 适用于 Octopress
  • 用于捆绑包压缩的自定义命令
  • 压缩包缓存
  • 远程资源的捆绑和缓存
  • 开发模式,便于使用所有资源进行网站开发
  • 仅限开发资产包含

TODO

  • 相对路径支持
  • CoffeeScript和LessCSS编译支持

Notes

v0.05 - 从使用Liquid :: Tags更改为Liquid :: Blocks。 如果升级,这将破坏现有的捆绑包标记。

为什么要改变它?那么,Liquid ::标签必须在一行, 而Liquid :: Blocks并不会打开更多 灵活性,因为附加选项可以包括在 标签文字。

v0.08 - 将 cdn 配置参数更改为 server_url 以便成为 更通用。目前, cdn 仍然有效(见下文)。

为什么要改变它?对参数名称似乎有点混乱 以及参数的作用。

v0.11 - jekyll –watch 现在打开开发模式。已删除代码 兼容版本的Jekyll pre 1.0。

为什么要改变它?无论如何,插件还没有真正支持 jekyll –watch 。 此外,Jekyll正在改变,我不希望这样做 不可维护的混乱。

Is it production ready?

考虑这个beta软件,虽然对于小Jekyll网站你 应该没有问题。

用法

一旦安装在您的 _plugins 文件夹Jekyll Asset Bundler中 液体::块使用会产生适当的 包含JavaScript和CSS的标记。 以下每个块都将使用 YAML 格式化的数组。

液体::块

bundle

{% bundle %} [/js/main.js, /js/somethingelse.js] {% endbundle %}

等于:

{% bundle %}
- /js/main.js
- /js/somethingelse.js
{% endbundle %}

远程资源也可以捆绑在一起:

{% bundle %}
- http://cdnjs.cloudflare.com/ajax/libs/jquery/1.7.2/jquery.min.js
- //cdnjs.cloudflare.com/ajax/libs/underscore.js/1.3.1/underscore-min.js
- https://cdnjs.cloudflare.com/ajax/libs/backbone.js/0.9.2/backbone-min.js
- /js/my_local_javascript.js
{% endbundle %}

远程资源将被缓存在 _asset_bundler_cache 文件夹中 (与您的 _plugins 文件夹相同的目录)。如果你想 重新生成缓存的项目,删除缓存文件夹。

bundle 标签将连接提供的脚本并创建一个哈希值 结果。此散列用作文件名。然后捆绑包被压缩 (如果需要),最终结果缓存在 _asset_bundler_cache 文件夹中。 因此,只有重新创建并重新压缩包,如果源 文件已被修改。这大大加快了未来的网站建设。

注意:资产Bundler不会尝试清理缓存文件夹。如果它 已经变得太大了,只需删除它。

最后插入适当的标记以包含您的包文件。

bundle_glob

{% bundle_glob %}
- /js/.js
- /css/.css
{% endbundle_glob %}

bundle_glob 标签使用 Ruby Dir.glob 方法包括多个资产。 警告:资产将以字母数字的顺序包含, 这可能会使某些东西出现。

dev_assets

{% dev_assets %}
- /js/less.js
{% enddev_assets %}

dev_assets 标签包含引用的标准标记 资产仅在’开发模式’。数组项可以是本地文件 或URL用于外部脚本,并按原样包括。 在任何其他时间,它什么都不做。 在未来的版本(希望很快),这将起到一定的作用 利用LessCSS和CoffeeScript。

配置

可以使用 _config.yml 中的设置修改某些行为。的 以下代表默认配置:

asset_bundler:
  compress:
    js: false
    css: false
  base_path: /bundles/
  server_url:
  remove_bundled: false
  dev: false
  bundle_name: false
  markup_templates:
    js: "<script type='text/javascript' src='{{url}}'></script>\n"
    css: "<link rel='stylesheet' type='text/css' href='{{url}}' />\n"

以下是顶级每个配置选项的细目 asset_bundler 键。

compress:

默认情况下不压缩任何内容。将 js css 键更改为 修改压缩行为。

js:

要用压缩机宝石压缩,在这里使用’yui’ 用封闭编译器gem来压缩,在这里使用’closure’。

compress:
  js: yui

要使用系统命令压缩,请输入 适当的资产类型:

compress:
  js: uglifyjs :infile -o :outfile -c

此示例将从PATH中运行 uglifyjs 命令 而代替:outfile和:infile的临时文件 存储在 _asset_bundler_cache 中。

如果任意一个:outfile或:infile被省略,stdout和 将使用stdin。 警告,stdin和stdout完成 与IO.popen,它不适用于Windows

注意:有些报告使用yui-compressor或者其他问题 在Windows上关闭编译器宝石。如果您在Windows上遇到问题,请尝试 指定如上所述的命令。

css:

js:完全相同的参数,但有异常 的Google Closure编译器(仅限JavaScript)。

base_path:

捆绑包将在目的地内复制 文件夹。

默认值: / bundles /

server_url:

注意:在v0.07及更早版本中,此设置为 cdn cdn 键仍然 作品将作为一个别名。但是,如果设置了 server_url 键 将覆盖 cdn

您的server_url或CDN的根路径(如果使用的话)。 例如: http://my-cdn.cloudfront.net/

Jekyll Asset Bundler检查以确保此设置以斜杠结尾。

默认值: (空白)。

remove_bundled:

如果设置为true,将删除包含在您的文件中的文件 从目的地文件夹捆绑。

默认值: false

dev:

注意:在v0.10及更早版本中,未自动启用开发模式 - auto - watch 模式

如果设置为true,则启用dev模式。当dev模式激活时, 不会创建任何包,并且所有引用的文件都是 单独包含,无需修改。

使用时也会自动启用开发模式 jekyll server jekyll –watch 或顶级配置密钥: dev 设置为true。

默认值: false

bundle_name:

覆盖包名称。如果为false,则使用MD5哈希的内容。

默认值: false

markup_templates:

使用相关的markup_template选项覆盖默认模板 用于插入束。每个选项都被解析为 Liquid :: Template.parse 并传递了一个 url (String)参数。

注意:如果您希望换行符正确传递,请务必引用 _config.yml 中的模板。

js:

The default JavaScript markup is fairly verbose. If you would like a modern replacement, try "<script src='{{url}}'></script>\n".

Default: "<script type='text/javascript' src='{{url}}'></script>\n"

css:

The default CSS is also verbose. If you would like a modern replacement, try "<link rel=stylesheet href='{{url}}'>\n".

Default: "<link rel='stylesheet' type='text/css' href='{{url}}' />\n"

依赖关系

Jekyll Asset Bundler使用 yui-compressor 关闭编译器宝石 (配置时)和(显然) Jekyll

作者

Colin Kennedy,moshen on GitHub

许可证

麻省理工学院, 请参阅LICENSE文件。




相关问题推荐