Jekyll v5 Roadmap

[ashmaroli]

Breaking Changes

Primary aim:       Have as much consistent behavior to reduce interference from various moving parts.
Secondary aim:   Reduce maintenance / development overhead by improving intuitiveness.

Ruby API

• Consider initializing core-primitives with **kwargs instead of positional parameters.
• Introduce a common superclass for pages, documents, layouts, inclusions (include_files), data_files.
• Make pages and documents behave similarly using inheritance.
• Introduce a StaticFile subclass for static files in a collection.
• Consider making Liquid drops immutable.
• Remove deprecated features / code.

Liquid API

• Rename Liquid variable {{ page }} to {{ view }}.

Build

• Incremental regeneration based on SHA digests.

Configuration

• Dedicated (default) collection_dir: _collections.
• collections have to be a map of key-value pairs. Lists or anything else will ignored (or errored?).
• Simpler syntax for defaults.

Collections

• Dedicated collection_dir: _collections.
• Register collections based on existence in collection_dir instead of configuration.
• Reduce special status of posts collection.
  • Make front matter mandatory for all documents (incl. posts).
  • Remove support for superdirectory-based categories. Consider only front matter data.
  • Treat Categories and Tags of every collection equally.
  • Allow having static files within posts collection.

[yboulkaid]

Since this is one of the few times where it's okay to introduce breaking changes, what do you think of biting the bullet and removing support for empty and blank so we can support liquid 5?

[arghc]

If by {{ page }} you mean page of page, post, collection then I must object vigorously to renaming it view.

[fauno]

What about supporting Liquid 5's {% render %}? (I thought I've seen an issue about this but couldn't find it)

https://shopify.github.io/liquid/tags/template/#render

[fauno]

If by {{ page }} you mean page of page, post, collection then I must object vigorously to renaming it view.

In my experience the name is not intuitive, why is it called page rather than post, when you are working on a post and not a page? Even in your examples the name comes up inconsistent.

I've helped people learn and work with Jekyll and this is always confusing. I'd keep it for backwards compatibility though, also for this reason.

I'm not sure where view comes from, are there drawbacks to just have the frontmatter variables available as liquid variables? So instead of {{ page.title }} you can do {{ title }}, like with {{ content }} (that can also be accessed as {{ page.content }}).

[fauno]

May I add deprecating SafeYAML? I think Psych can provide same functionality #8772

[ashmaroli]

I'm not sure where view comes from, are there drawbacks to just have the frontmatter variables available as liquid variables? So instead of {{ page.title }} you can do {{ title }}, like with {{ content }} (that can also be accessed as {{ page.content }}).

I decided to rename {{ page }} for similar reasons as well: causing confusion with like named internal type especially for new users. In context, the variable page refers to the current webpage being rendered and has nothing to do with its internal Jekyll type. view conveys the same semantic yet being neutral and of same character length as page.

The problem with exposing {{ page.title }} as {{ title }} is practicality. Top-level variables such as site, page, content, paginator etc are predefined objects that have a set role (and hence deterministic). User-defined variables have variable values and therefore non-deterministic.

Unlocking Liquid v5 is definitely a desirable goal for Jekyll v5 from users' POV, but not a critical one, since there isn't much internal changes required to support it. The other entries in the roadmap have a significant effect on current architecture of Jekyll.

[yboulkaid]

I see the point for renaming {{ page }}, now that we also have posts and collection items. I however think view would be even more confusing for beginners, as I find it quite technical and vague.

Some suggestions:

• current_page (I like "page" in this context as people are familiar with web pages)
• post, page (maybe even item) all aliased to the same object? This way one could use whatever makes more sense in the current context, but it might also confuse people?

Regardless, should we maybe move this discussion outside of the main roadmap thread to avoid cluttering this one?

[ashmaroli]

view would be even more confusing for beginners, as I find it quite technical and vague..
current_page (I like "page" in this context as people are familiar with web pages)..

@yboulkaid I didn't choose current_page because it requires more keystrokes than page unlike view which I think will catch on with repeated use. However, I do agree with you that it is quite technical, because I had the (Model-Controller-View) thought at the back of my head at the time.

should we maybe move this discussion outside of the main roadmap thread to avoid cluttering this one?

As of now, I'd rather not fragment the discussion thread. If it does get unmanageable, I'll open a dedicated ticket.

P.S. I'm 👎 on the idea of aliasing a variable for every primitive type because it will only lead to more maintenance overhead.

[Xaymar]

Rename Liquid variable {{ page }} to {{ view }}.

Is this about page or a new variable introduced in Liquid? If it is the former, I would suggest self or this, as both names describe the current content, instead of a specific type of content.

[ashmaroli]

Is this about page...

@Xaymar Yes, this is indeed about the top-level variable page but this or self could cause confusion when referenced inside a partial such as an inclusion / include_file.

[Xaymar]

but this or self could cause confusion when referenced inside a partial such as an inclusion / include_file.

According to Liquids documentation, includes use include, so there shouldn't be any confusion. But I can see the problem if someone where to only skim all the documentations instead of reading them entirely. Personally not a fan of view, as what the data is actually on is the model.

If you do want to align things to an MVC perspective, it would be like this: layouts are view, posts/pages/articles/... are model, and whatever editor you use is the controller. This would be one extra character for posts/pages/articles/..., but three less characters for layouts.

None of the options are great though and can describe things without any drawbacks or confusion at this character length. page works for posts, pages and collections, since it can be interpreted as "the content of the current page".

[ashmaroli]

According to Liquids documentation, includes use include, so there shouldn't be any confusion.

Agreed. But if someone (regardless of familiarity with Jekyll) were to find, say {{ self.title }} or {{ this.title }} inside an include_file, they're going to take a minute wondering if self (or this) is referring to the include_file itself (front matter in include_file ???) or the parent template ???
include just references the parameter data object.

[kslstn]

Introduce a common superclass for pages, documents, layouts, inclusions (include_files), data_files.

Would that mean that there would no longer be special treatment for directories like _includes and _data? I'd love that, as it would make a single file component approach (or actually: single folder approach) to organizing files possible. For reusable 'widgets' I want to adopt a structure like:

- _includes
  ∟ components
    ∟ my_component
       ∟ my_component.liquid
       ∟ my_component.js
       ∟ _my_component.scss
       ∟ _my_component_strings.yml
       ∟ _my_component_settings.yml

In Jekyll 4, we can't put the data yml files there though (or can we?!).

I wouldn't mind _layouts keeping its special status, as its contents would make obvious what files can be picked as a layout.

[ashmaroli]

@kslstn The idea behind having a common superclass for various Jekyll primitives is to use "inheritance" to provide a base of common functionality for desired types. Sort of like an implementation-detail, without affecting end-user experience.
Includes and Data Files will continue to behave as is for the end-user.

[y377]

Jekyll does not support jekyll build and jekyll serve for multi-core CPUs, except for incremental regeneration.
I would like a technique to efficiently use multi-core CPUs for both build or Jekyll serve.
This is my biggest expectation for V5, now with chatgpt, I can easily cope with Jekyll's various advanced uses

[ashmaroli]

Jekyll does not support jekyll build and jekyll serve for multi-core CPUs, except for incremental regeneration.
I would like a technique to efficiently use multi-core CPUs for both build or Jekyll serve.

@y377 Jekyll is written using Ruby language. Ruby doesn't have stable built-in mechanism to use multiple cores. Additionally, before Jekyll can adopt true concurrency and parallelism, Ruby has to support the ability realiably across the major OS platforms: Ubuntu, macOS, Windows.

[y377]

@ashmaroli Just tried jruby-head, a bunch of errors, forget it, or honestly use ruby3.0

[y377]

sourcemap default parameter is 'always', brought after the build in the mobile browser will appear unexpected errors, PC browser occasionally appear, I have carefully troubleshooting, only to find this parameter and value, I thought it was bootstrap, in addition, the development environment is now recommended to close the official version of the site, this point is a lot of Jekyll's novice do not know, so it is recommended that the default **off **, I also troubleshooting to find out!

Or it is clearly marked in the official default configuration document of jekyll. This shutdown trick was not discovered through jekyll-sass-converter.
Because Jekyll mode uses sass, novices who are new to Jekyll are confused about the relationship, let alone how to solve this error when the browser console appears.
This error will also appear in self-built "CDN"

[fauno]

Something that's weird about the include tag is that the filename is an unquoted string, so if you want to include dynamically generated filename, you need to nest a liquid variable, but can't do anything more complex than that:

{% comment %}
  Regular usage
{% endcomment %}
{% include file.html param="quoted param" %}

{% comment %}
  This doesn't work, it'll say there's no "variable" file inside _includes
{% endcomment %}
{% assign variable = "file.html" %}
{% include variable param="quoted param" %}

{% comment %}
  This works, but looks weird
{% endcomment %}
{% assign variable = "file.html" %}
{% include {{ variable }} param="quoted param" %}

{% comment %}
  This doesn't work
{% endcomment %}
{% assign variable = "file" %}
{% include {{ variable }}.html param="quoted param" %}

Proposal:

1. Make the first param of include a variable
2. So it can take a string either as a string literal or a variable containing a string
3. The fourth example with liquid-style interpolation still won't work but at least it's clear the syntax doesn't work like that

{% include "file.html" param="quoted param" %}

{% assign variable = "file.html" %}
{% include variable param="quoted param" %}

{% assign variable = "file" | append: ".html" %}
{% include variable param="quoted param" %}

I finished writing this and remembered Liquid 5 has the render tag with a more natural liquid syntax: https://shopify.github.io/liquid/tags/template/#render

I remember there was some discussion about this here on Jekyll, probably related to include global variable scope, but I can't seem to find it now.

[fauno]

What about supporting Liquid 5's {% render %}? (I thought I've seen an issue about this but couldn't find it)

https://shopify.github.io/liquid/tags/template/#render

Hehe... but also #9030 and #8535