jekyll: 'Order of interpretation' document is incorrect
- I believe this to be a bug, not a question about using Jekyll.
The document here: https://jekyllrb.com/tutorials/orderofinterpretation/ describes how Jekyll processes sites in great detail. Unfortunately, it’s not correct!
It states clearly that site variables are read, then that Liquid formatting is interpreted for all pages, then that Markdown is processed for all pages, etc. However, what actually happens is that all these phases are run in order for each document before moving on to the next document.
$ jekyll build -V
[...]
Rendering: _pages/amidimap/index.html
Pre-Render Hooks: _pages/amidimap/index.html
Rendering Liquid: _pages/amidimap/index.html
Rendering Markup: _pages/amidimap/index.html
Rendering Layout: _pages/amidimap/index.html
Rendering: _pages/amstrad/index.html
Pre-Render Hooks: _pages/amstrad/index.html
Rendering Liquid: _pages/amstrad/index.html
Rendering Markup: _pages/amstrad/index.html
Rendering Layout: _pages/amstrad/index.html
This makes an enormous difference, as when the page gets rendered determines whether page.content contains the raw page content or the rendered HTML markup — right now the documentation says that layouts are processed after rendering happens, which means that I should be able to rely on page.content containing HTML; but that’s not the case. Instead I have to name my files so that anything which requires HTML gets rendered last.
Did the Jekyll render order change since the page was written? Either way, it needs updating…
About this issue
- Original URL
- State: open
- Created 7 years ago
- Comments: 17 (11 by maintainers)
@harry-hov Feel free to do so. We appreciate all the help we get. 👍
Thanks – I’ve now added a README.
@ashmaroli thanks for your follow-up to my query.
Regarding the reported issue with the Just-the-Docs remote theme, I wrote:
The theme implementation assumes that the file named
zzzz-search-data.jsonwill generally be the last one to be rendered. If that is not the case, it would be helpful to know exactly how Jekyll sorts the files. For example, can the folder hierarchy affect the sort order? (I gather that exploiting the sorting is the only way of deferring the rendering of a particular file.)Following up on the original bug report by a Just-the-Docs user, I have now created a MWE that demonstrates the issue: https://pdmosses.github.io/jtd/. Running Jekyll 4.2.0 locally (on macOS 11.4),
zzzz-search-data.jsonappears to be the first file rendered when I build the site – see the Markdown and Liquid content in https://github.com/pdmosses/jtd/blob/main/assets/jekyll-4.2.0/search-data.json. When I run Jekyll 3.8.7, 4.0.1, and 4.1.1, however, it is always rendered last: e.g., the Markdown and Liquid on the other pages does not appear in https://github.com/pdmosses/jtd/blob/main/assets/jekyll-4.1.1/search-data.json.@pdmosses Hello sir, The rendering process of a Jekyll site is not multi-threaded or random. In fact none of the stages making up the build process involves concurrency. Everything happens serially in a predefined order.
The build process always runs in the following sequence:
Pages, posts, static files, layouts are all read and sorted into a stack. Collection documents are also read and sorted (but the sorting is configurable).
During the rendering phase, the items of a stack are processed on a first-in, first-out (FIFO) basis. i.e. for the following stack:
"d"will always be rendered just before"e".The existing
Order of Interpretationwas written by a technical writer belonging to the community.I am planning on publishing a separate official version (I’m part of the core maintainers team, though not a tech writer) provided there’s no objection from fellow maintainers.
Hey, I would like to work on this.