diff --git a/docs/_data/docs_nav.yml b/docs/_data/docs_nav.yml index 8aac2bef..43aefb08 100644 --- a/docs/_data/docs_nav.yml +++ b/docs/_data/docs_nav.yml @@ -9,6 +9,7 @@ docs: - link: /docs/usage/ - link: /docs/configuration/ + - link: /docs/rendering-process/ - title: Content docs: - link: /docs/pages/ diff --git a/docs/_docs/rendering-process.md b/docs/_docs/rendering-process.md new file mode 100644 index 00000000..6657bc52 --- /dev/null +++ b/docs/_docs/rendering-process.md @@ -0,0 +1,28 @@ +--- +--- + +For any Jekyll site, a *build session* consists of discrete phases in the following order --- *setting up plugins, +reading source files, running generators, rendering templates*, and finally *writing files to disk*. + +While the phases above are self-explanatory, the one phase that warrants dissection is *the rendering phase*. + +The rendering phase is further divisible into three optional stages. Every file rendered, passes through one or more of +these stages as determined by the file's content string, front matter and extension. The stages are akin to an assembly +line, with the *output* from a stage being the *input* for the succeeding stage: +- **Interpreting Liquid expressions in the file**
+ This stage evaluates Liquid expressions in the current file. By default, the interpretation is *shallow* --- in that + any Liquid expression in resulting output is not further interpreted. Moreover, any Liquid expression in the file's + front matter is left untouched. +- **Unleashing the converters**
+ This stage invokes the converter mapped to the current file's extension and converts the input string. This is when + Markdown gets converted into HTML and Sass / Scss into CSS or CoffeeScript into JavaScript, etc, etc. Since this stage + is determined by the file's extension, Markdown or Sass inside a `.html` file will remain untouched. +- **Populating the layouts**
+ By this stage, *the source file* is considered rendered and it will not be revisited. However, based on the file's + extension and consequently based on the front matter, it is determined whether to take the *output* string from + the preceding stage and place into layouts or not. Whereas output from Sass files or CoffeeScript files are *never* + placed into a layout, regular text output can go either ways based on whether a layout has been assigned via the front + matter.

+ Placement into layouts work similar to how Russian dolls encase the smaller ones within itself or how an oyster + generates a pearl --- the converted output from the preceding stage forms the core and layout(s) are successively + *rendered* separately onto the core.