# Web Assets: A Plugin for Pelican
[](https://github.com/pelican-plugins/webassets/actions)
[](https://pypi.org/project/pelican-webassets/)
[](https://pypi.org/project/pelican-webassets/)
This [Pelican](https://github.com/getpelican/pelican) plugin allows you to use
the [webassets][] module to perform a number
of useful asset management functions on your web site, such as:
* CSS minification (`cssmin`, `yui_css`, ...)
* CSS compiling (`less`, `sass`, ...)
* JS building (`uglifyjs`, `yui_js`, `closure`, ...)
Some other interesting abilities of [webassets][] include:
* [URL Expiry or
"cache-busting"](https://webassets.readthedocs.io/en/latest/expiring.html),
allowing you to set the cache headers for your assets long into the
future, saving bandwidth and reducing page load-times
* a [`spritemapper`](https://yostudios.github.io/Spritemapper/) function to
automatically combine multiple icons into one large image with corresponding
position slices
* a `datauri` function to minimize the number of HTTP requests by
replacing `url()` references in your stylesheets with internal
in-line [data URIs](https://en.wikipedia.org/wiki/Data_URI_scheme)
For the complete list of what [webassets][] can do, check out the **included
filters** section in the [webassets
documentation](https://webassets.readthedocs.io/en/latest/builtin_filters.html).
## Installation
Getting started with [webassets][] couldn't be easier thanks to `pip`:
```shell-session
python -m pip install pelican-webassets
```
For more detailed plugin installation instructions, please refer to the
[Pelican Plugin Documentation](https://docs.getpelican.com/en/latest/plugins.html).
💡 **Keep in Mind:** Each function you use in your `{% asset filters %}`
arguments (more on this later) will need to be installed
separately. For example, if you wanted to use the `libsass` filter, you
will need to `pip install libsass`. You can even [create a custom
filter](https://webassets.readthedocs.io/en/latest/custom_filters.html)
if you wanted.
## Usage
With the plugin installed, include one or more `{% assets %}` tags
into your web site's templates to generate everything your web page will
need. For example, something like this in your template…
```html+jinja
{% assets filters="libsass,cssmin", output="css/style.min.css", "css/style.scss" %}
<link rel="stylesheet" href="{{SITEURL}}/{{ASSET_URL}}">
{% endassets %}
```
… will tell [webassets][] to use `libsass` and `cssmin` to compile and
minify the `css/style.scss` file in your theme, and save the compiled
stylesheet as `css/style.min.css` in the output of your finished
website, along with the `link` element like this in your web page:
```html+jinja
<link href="{SITEURL}/{THEME_STATIC_DIR}/css/style.min.css?b3a7c807" rel="stylesheet">
```
🌠 **The More You Know:** The `ASSET_URL` variable is the concatenation
of your Pelican `THEME_STATIC_DIR` setting, the `output` argument, and
the "cache-busting" variable we already talked about.
### JavaScript Example
As another example, we can use the [webassets][] `closure_js` function to
combine, minify, and compress two files in your web site's theme, `js/jQuery.js`
and `js/widgets.js`:
```html+jinja
{% assets filters="closure_js", output="js/packed.js", "js/jQuery.js", "js/widgets.js" %}
<script src="{{SITEURL}}/{{ASSET_URL}}"></script>
{% endassets %}
```
The resulting output will be a single `script` tag and its
corresponding file in your web site's generated output:
```html+jinja
<script src="{SITEURL}/{THEME_STATIC_DIR}/js/packed.js?00703b9d"></script>
```
## Configuration
Being a very small wrapper around the [webassets][] module, there are
only a few options that you may need.
#### WEBASSETS_DEBUG
By default, if Pelican is in DEBUG mode (`pelican -D ...`), this
plugin will put [webassets][] in DEBUG mode, to help you with
debugging. To override this behavior, set `WEBASSETS_DEBUG = False` to
always process files regardless of Pelican's DEBUG flag, or `True`
to always force [webassets][] into DEBUG mode.
```python
# put webassets into DEBUG mode if Pelican is
WEBASSETS_DEBUG = logger.getEffectiveLevel() <= logging.DEBUG
```
#### WEBASSETS_CONFIG
Some [webassets][] filters require extra configuration options to function
properly. You can use `WEBASSETS_CONFIG` to specify these options in a
list of `(key, value)` tuples that are passed along to the [webassets][]
environment.
```python
WEBASSETS_CONFIG = [
("closure_compressor_optimization", "ADVANCED_OPTIMIZATIONS"),
("libsass_style", "compressed")
]
```
#### WEBASSETS_BUNDLES
[Bundles](https://webassets.readthedocs.io/en/latest/bundles.html) are
a convenient way to group a collection of assets together along with
the information on how to properly process the files. The
`WEBASSETS_BUNDLES` option allows us to make these Bundles by taking a
list of `(name, args, kwargs)` arguments that will be passed to the
[webassets][] environment.
```python
WEBASSETS_BUNDLES = (
("my_bundle", ("colors.scss", "style.scss"),
{"output": "style.min.css", "filters": ["libsass", "cssmin"]}),
)
```
Allowing you to simplify something like this in your web site's templates…
```html+jinja
{% assets filters="libsass,cssmin", output="style.min.css", "colors.scss", "style.scss" %}
```
… into this:
```html+jinja
{% assets 'my_bundle' %}
```
#### WEBASSETS_SOURCE_PATHS
If your raw assets are in directories other than your
`THEME_STATIC_PATHS`, you can supply additional directories to search
in with `WEBASSETS_SOURCE_PATHS`.
```python
WEBASSETS_SOURCE_PATHS = ["stylehseets", "javascript"]
```
## Contributing
Contributions are welcome and much appreciated. Every little bit
helps. You can contribute by improving the documentation, adding
missing features, and fixing bugs. You can also help out by reviewing
and commenting on [existing issues][].
To start contributing to this plugin, review the [Contributing to
Pelican][] documentation, beginning with the **Contributing Code**
section.
[existing issues]: https://github.com/pelican-plugins/webassets/issues
[Contributing to Pelican]: https://docs.getpelican.com/en/latest/contribute.html
## License
This project is licensed under the [AGPL-3.0
license](https://tldrlegal.com/license/gnu-affero-general-public-license-v3-(agpl-3.0))
[webassets]: https://github.com/miracle2k/webassets
Raw data
{
"_id": null,
"home_page": null,
"name": "pelican-webassets",
"maintainer": null,
"docs_url": null,
"requires_python": "~=3.9",
"maintainer_email": null,
"keywords": "compilation, css, js, minimization, pelican, plugin, webassets",
"author": "Pelican Dev Team <authors@getpelican.com>",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/a1/22/6241f976879780ec6f89bf45df36952169f305cdddbaabcba2ae797e699e/pelican_webassets-2.1.0.tar.gz",
"platform": null,
"description": "# Web Assets: A Plugin for Pelican\n\n[](https://github.com/pelican-plugins/webassets/actions)\n[](https://pypi.org/project/pelican-webassets/)\n[](https://pypi.org/project/pelican-webassets/)\n\n\nThis [Pelican](https://github.com/getpelican/pelican) plugin allows you to use\nthe [webassets][] module to perform a number\nof useful asset management functions on your web site, such as:\n\n* CSS minification (`cssmin`, `yui_css`, ...)\n* CSS compiling (`less`, `sass`, ...)\n* JS building (`uglifyjs`, `yui_js`, `closure`, ...)\n\nSome other interesting abilities of [webassets][] include:\n\n* [URL Expiry or\n \"cache-busting\"](https://webassets.readthedocs.io/en/latest/expiring.html),\n allowing you to set the cache headers for your assets long into the\n future, saving bandwidth and reducing page load-times\n* a [`spritemapper`](https://yostudios.github.io/Spritemapper/) function to\n automatically combine multiple icons into one large image with corresponding\n position slices\n* a `datauri` function to minimize the number of HTTP requests by\n replacing `url()` references in your stylesheets with internal\n in-line [data URIs](https://en.wikipedia.org/wiki/Data_URI_scheme)\n\nFor the complete list of what [webassets][] can do, check out the **included\nfilters** section in the [webassets\ndocumentation](https://webassets.readthedocs.io/en/latest/builtin_filters.html).\n\n## Installation\n\nGetting started with [webassets][] couldn't be easier thanks to `pip`:\n\n```shell-session\npython -m pip install pelican-webassets\n```\n\nFor more detailed plugin installation instructions, please refer to the\n[Pelican Plugin Documentation](https://docs.getpelican.com/en/latest/plugins.html).\n\n\ud83d\udca1 **Keep in Mind:** Each function you use in your `{% asset filters %}`\narguments (more on this later) will need to be installed\nseparately. For example, if you wanted to use the `libsass` filter, you\nwill need to `pip install libsass`. You can even [create a custom\nfilter](https://webassets.readthedocs.io/en/latest/custom_filters.html)\nif you wanted.\n\n## Usage\n\nWith the plugin installed, include one or more `{% assets %}` tags\ninto your web site's templates to generate everything your web page will\nneed. For example, something like this in your template\u2026\n\n```html+jinja\n{% assets filters=\"libsass,cssmin\", output=\"css/style.min.css\", \"css/style.scss\" %}\n <link rel=\"stylesheet\" href=\"{{SITEURL}}/{{ASSET_URL}}\">\n{% endassets %}\n```\n\n\u2026\u00a0will tell [webassets][] to use `libsass` and `cssmin` to compile and\nminify the `css/style.scss` file in your theme, and save the compiled\nstylesheet as `css/style.min.css` in the output of your finished\nwebsite, along with the `link` element like this in your web page:\n\n```html+jinja\n<link href=\"{SITEURL}/{THEME_STATIC_DIR}/css/style.min.css?b3a7c807\" rel=\"stylesheet\">\n```\n\n\ud83c\udf20 **The More You Know:** The `ASSET_URL` variable is the concatenation\nof your Pelican `THEME_STATIC_DIR` setting, the `output` argument, and\nthe \"cache-busting\" variable we already talked about.\n\n### JavaScript Example\n\nAs another example, we can use the [webassets][] `closure_js` function to\ncombine, minify, and compress two files in your web site's theme, `js/jQuery.js`\nand `js/widgets.js`:\n\n```html+jinja\n{% assets filters=\"closure_js\", output=\"js/packed.js\", \"js/jQuery.js\", \"js/widgets.js\" %}\n <script src=\"{{SITEURL}}/{{ASSET_URL}}\"></script>\n{% endassets %}\n```\n\nThe resulting output will be a single `script` tag and its\ncorresponding file in your web site's generated output:\n\n```html+jinja\n<script src=\"{SITEURL}/{THEME_STATIC_DIR}/js/packed.js?00703b9d\"></script>\n```\n\n## Configuration\n\nBeing a very small wrapper around the [webassets][] module, there are\nonly a few options that you may need.\n\n#### WEBASSETS_DEBUG\n\nBy default, if Pelican is in DEBUG mode (`pelican -D ...`), this\nplugin will put [webassets][] in DEBUG mode, to help you with\ndebugging. To override this behavior, set `WEBASSETS_DEBUG = False` to\nalways process files regardless of Pelican's DEBUG flag, or `True`\nto always force [webassets][] into DEBUG mode.\n\n```python\n# put webassets into DEBUG mode if Pelican is\nWEBASSETS_DEBUG = logger.getEffectiveLevel() <= logging.DEBUG\n```\n\n#### WEBASSETS_CONFIG\n\nSome [webassets][] filters require extra configuration options to function\nproperly. You can use `WEBASSETS_CONFIG` to specify these options in a\nlist of `(key, value)` tuples that are passed along to the [webassets][]\nenvironment.\n\n```python\nWEBASSETS_CONFIG = [\n (\"closure_compressor_optimization\", \"ADVANCED_OPTIMIZATIONS\"),\n (\"libsass_style\", \"compressed\")\n]\n```\n\n#### WEBASSETS_BUNDLES\n\n[Bundles](https://webassets.readthedocs.io/en/latest/bundles.html) are\na convenient way to group a collection of assets together along with\nthe information on how to properly process the files. The\n`WEBASSETS_BUNDLES` option allows us to make these Bundles by taking a\nlist of `(name, args, kwargs)` arguments that will be passed to the\n[webassets][] environment.\n\n```python\nWEBASSETS_BUNDLES = (\n (\"my_bundle\", (\"colors.scss\", \"style.scss\"),\n {\"output\": \"style.min.css\", \"filters\": [\"libsass\", \"cssmin\"]}),\n)\n```\n\nAllowing you to simplify something like this in your web site's templates\u2026\n\n```html+jinja\n{% assets filters=\"libsass,cssmin\", output=\"style.min.css\", \"colors.scss\", \"style.scss\" %}\n```\n\n\u2026 into this:\n\n```html+jinja\n{% assets 'my_bundle' %}\n```\n\n#### WEBASSETS_SOURCE_PATHS\n\nIf your raw assets are in directories other than your\n`THEME_STATIC_PATHS`, you can supply additional directories to search\nin with `WEBASSETS_SOURCE_PATHS`.\n\n```python\nWEBASSETS_SOURCE_PATHS = [\"stylehseets\", \"javascript\"]\n```\n\n## Contributing\n\nContributions are welcome and much appreciated. Every little bit\nhelps. You can contribute by improving the documentation, adding\nmissing features, and fixing bugs. You can also help out by reviewing\nand commenting on [existing issues][].\n\nTo start contributing to this plugin, review the [Contributing to\nPelican][] documentation, beginning with the **Contributing Code**\nsection.\n\n[existing issues]: https://github.com/pelican-plugins/webassets/issues\n[Contributing to Pelican]: https://docs.getpelican.com/en/latest/contribute.html\n\n## License\n\nThis project is licensed under the [AGPL-3.0\nlicense](https://tldrlegal.com/license/gnu-affero-general-public-license-v3-(agpl-3.0))\n\n\n\n\n[webassets]: https://github.com/miracle2k/webassets\n",
"bugtrack_url": null,
"license": null,
"summary": "Pelican plugin to manage web assets such as CSS and JS files",
"version": "2.1.0",
"project_urls": {
"Funding": "https://donate.getpelican.com/",
"Issue Tracker": "https://github.com/pelican-plugins/webassets/issues"
},
"split_keywords": [
"compilation",
" css",
" js",
" minimization",
" pelican",
" plugin",
" webassets"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "42d6844e251c8da875d6ff4a86715394f43f8ad2141d70577f7e77e4058576b2",
"md5": "b5712fce8ce7722bfc796aedf2911a2b",
"sha256": "9df6659ecb565af88df55df4aac27cafc948299ef3d4fc743f7385db2e274475"
},
"downloads": -1,
"filename": "pelican_webassets-2.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b5712fce8ce7722bfc796aedf2911a2b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.9",
"size": 149769,
"upload_time": "2024-11-03T01:41:03",
"upload_time_iso_8601": "2024-11-03T01:41:03.253193Z",
"url": "https://files.pythonhosted.org/packages/42/d6/844e251c8da875d6ff4a86715394f43f8ad2141d70577f7e77e4058576b2/pelican_webassets-2.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a1226241f976879780ec6f89bf45df36952169f305cdddbaabcba2ae797e699e",
"md5": "c23af42e23ee83550f89dd314d7cad84",
"sha256": "0a418b88ebd6d96efae4d666394552bcacc8d30d2f0abb5bb4db26064e8cfed0"
},
"downloads": -1,
"filename": "pelican_webassets-2.1.0.tar.gz",
"has_sig": false,
"md5_digest": "c23af42e23ee83550f89dd314d7cad84",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.9",
"size": 133756,
"upload_time": "2024-11-03T01:41:05",
"upload_time_iso_8601": "2024-11-03T01:41:05.387199Z",
"url": "https://files.pythonhosted.org/packages/a1/22/6241f976879780ec6f89bf45df36952169f305cdddbaabcba2ae797e699e/pelican_webassets-2.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-03 01:41:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pelican-plugins",
"github_project": "webassets",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pelican-webassets"
}
JSON
