Mercurial > piecrust2

comparison docs/docs/05_asset-pipeline.md @ 310:c7e9001c74c2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
docs: Add documentation on the asset pipeline.
author Ludovic Chabant <ludovic@chabant.com>
date Wed, 25 Mar 2015 23:04:42 -0700
parents
children 31f2964d034a
comparison
equal deleted inserted replaced
309:93cd57e2b074 310:c7e9001c74c2
1 ---
2 title: Asset Pipeline
3 ---
4
5 PieCrust comes with a simple, yet efficient, asset pipeline. If you have
6 advanced requirements, or want to use something familiar, you can of course use
7 well known systems like [Grunt][] or [Gulp][], but you should definitely give
8 the PieCrust asset pipeline a try.
9
10 The PieCrust asset pipeline doesn't require a build file: asset processors are
11 enabled more or less globally, and will affect all assets the same way inside a
12 given asset directory.
13
14
15 ## Assets directories
16
17 By default, the asset pipeline will process only one assets directory, `assets/`.
18 You can change or add directories with the `baker/assets_dirs` setting in the
19 website configuration.
20
21 For each file found in an assets directory, the pipeline will either:
22
23 * Ignore it, if it matches the `baker/ignore` patterns. By default, those
24 patterns include common temporary files like `.DS_Store` and `Thumbs.db`
25 files, and common source control files like `.git`, `.hg`, and `.svn`.
26
27 * Process it, if it matches any of the active asset processors. The output of
28 the processing phase will be put in the output directory.
29
30 * Copy it as is, if not asset processor was found. Just like for processing, the
31 relative path of the asset is preserved in the output directory.
32
33
34 ## Asset Processing
35
36 As mentioned in the previous section, each asset file will be matched against
37 available asset processors. Most processors will accept a file based on its
38 extension, although some processors use other conditions. Processors have a
39 priority, so for instance the `copy` processor, which accepts _all_ files, will
40 be matched last.
41
42 The key element however is that the PieCrust pipeline is a _multi-step_
43 processing pipeline. The output of the first matched processor will be itself
44 matched again against all the other processors... and so on, until no more
45 processors match and the `copy` processor copies the result to the output(s)
46 directory.
47
48 So for instance, you if you have a LessCSS file, it will be processed like so:
49
50 foo.less -> foo.css -> foo.min.css
51
52 The `.less` extension gets matched to the LessCSS processor, which outputs a
53 standard `.css` file. This file gets picked up by the CleanCSS processor, which
54 minifies the file, and can optionally add the `.min` suffix. There's no other
55 processors that can handle a `.css` file, so the resulting `foo.min.css` is
56 copied to the output directory.
57
58
59
60
61 [Grunt]: http://gruntjs.com/
62 [Gulp]: http://gulpjs.com/
63 [procref]: {{docurl('reference/asset-processors')}}
64