Add a note on the rendering process in the docs (#8291)

Merge pull request 8291
This commit is contained in:
Ashwin Maroli 2020-07-09 00:16:06 +05:30 committed by GitHub
parent 6c640012a2
commit a5b6602ffd
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 29 additions and 0 deletions

View File

@ -9,6 +9,7 @@
docs: docs:
- link: /docs/usage/ - link: /docs/usage/
- link: /docs/configuration/ - link: /docs/configuration/
- link: /docs/rendering-process/
- title: Content - title: Content
docs: docs:
- link: /docs/pages/ - link: /docs/pages/

View File

@ -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**<br/>
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**<br/>
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**<br/>
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.<br/><br/>
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.