The Build Pipeline¶
Engineer goes through a number of steps when building a site. Understanding this order and the steps that are taken might be helpful when building your site. At the very least, it might be interesting.
Engineer operates almost entirely on something called the ‘output cache.’ This is a location in the
CACHE_DIR. Engineer essentially ‘stages’ all content there during
processing. Once that’s all done, then it synchronizes the actual
OUTPUT_DIR with the cache.
With that in mind, these are the basic steps that Engineer goes through. You might also find it interesting to look at
the code for the
engineer.engine.build() function - it is the primary entry point for the build process.
Copy base Engineer static content
First, any static content from the core Engineer libraries is copied to the output cache. This includes things like the built-in jQuery, Modernizr, and Foundation libraries.
Copy theme static content
Any static content needed by the theme is copied to the output cache.
Generate template pages
Template Pages are generated and copied to the output cache.
Posts are loaded from the post cache and
POST_DIRand stored in memory in a
Based on settings like
PUBLISH_PENDING, the list of posts is trimmed to those that should be output, then they are rendered and placed in the output cache.
Generate rollup pages
The front page and other ‘rollup’ pages are generated and placed in the output cache.
Generate archive page
The archive page is generated and placed in the output cache.
Generate tag pages
Tag pages are generated and placed in the output cache.
Generate feed and sitemap
The RSS feed and sitemap are generated and placed in the output cache.
Copy raw content to output cache
Any site-specific Raw Content is copied to the output cache.
COMPRESSOR_ENABLEDsetting is on, then any CSS or JS files used in the site will be compressed.
Remove source LESS files from output cache
PREPROCESS_LESSsetting is on, then the source LESS files will be removed from the output cache. This is safe to do since the LESS preprocessing happens during rendering, so at this point the corresponding CSS file has already been generated. The LESS source file is no longer needed.
Synchronize output directory with output cache
Finally, the contents of the
OUTPUT_DIRis synchronized with the output cache. This approach ensures that the actual site output is disturbed as little as possible. All the major copying/generating/rendering has already happened separately on the output cache, so the actual site output directory has only changes/additions/deletions propagated to it.
Raw content should be placed in your site’s
and since it’s the last thing copied in the build pipeline, it will overwrite any content that was generated by the
other phases of the build pipeline. Keep this in mind.
The structure of
CONTENT_DIR should match your site’s. In other words,
if you want something to wind up in the root of your site, you would put it at the root of your
CONTENT_DIR. Similarly, if you want something to wind up in
your site, you’d put it in a
foo folder inside your