Idea: allow transclusion via include tag

[cmegown]

• This is a feature request.
• I am on (or have tested on) Windows 10+

Hi everyone,

Right off the bat I want to say that this is less an official feature request as much as it's something I feel might merit a discussion. It's also worth noting that I'm creating this issue here first, rather than going straight to the liquid issues, even if that's where we end up.

I've been using Jekyll to build out a design system and while creating "living" components I'm seeing some room for improvement when it comes to including "dynamic" content. Here's a very simple version of what I'm talking about:

// _include/figure.html
<figure>
  <img src="{{ include.src }}" alt="{{ include.alt }}">
  {% if include.caption %}
  <figcaption>{{ include.caption }}</figcaption
  {% endif %}
</figure>

// somewhere in the documentation
{% include figure.html src="/path/to/image.jpg" alt="description of image goes here" caption="optional caption goes here" %}

The snippet above works just fine if you want the caption to be a simple string, but if you want to use additional HTML elements then you need to utilize a {% capture %} block:

// somewhere in the documentation
{% capture caption_sample %}
I want this to <strong>be more</strong> than a <em>very simple</em> string!
{% endcapture %}

{% include figure.html src="/path/to/image.jpg" alt="description of image goes here" caption=caption_sample %}

While this works fine as is, having to write an additional {% capture %} block frequently can be tedious and prone to error. Here's how allowing for a transclusion slot (here's an example of transclusion in Angular) might work:

// _include/figure.html
<figure>
  <img src="{{ include.src }}" alt="{{ include.alt }}">
  {% if include_content %}
  <figcaption>{{ include_content }}</figcaption
  {% endif %}
</figure>

// somewhere in the documentation
{% include figure.html src="/path/to/image.jpg" alt="description of image goes here" %}
I want this to <strong>be more</strong> than a <em>very simple</em> string!
{% endinclude %}

In the example above, you can see there's a new predefined variable called include_content being used for this purpose. Again, this is just an idea. Feel free to immediately disregard and close this issue but I'd love to hear some feedback and see what everyone else thinks.

[DirtyF]

I see what you mean. Hugo can do that: it allows you to access what you have called
{{ include_content }} via {{ .Inner }}.

[ashmaroli]

To summarize, this feature-request is enhance the include tag from being a simple inline-tag to be a compound-tag that can be used as both an inline-tag as well as a block-tag...

My initial impression is that this request is best handled as a separate plugin.. (or a new tag within the Core itself).

It can't be incorporated into the existing include tag because, the computation required to assess if a given include tag is an inline-tag or a block-tag followed by checking if the block-version has the include_content is going to unnecessarily hamper the overall build times especially in a large site that uses loads of include tag

[pathawks]

as both an inline-tag as well as a block-tag

Is that possible? Wouldn't it need to be something different like {% includeblock %} or something? Otherwise, how would an inline include be distinguished from an {% include %} start tag that just lacked a corresponding {% endinclude %}?

[ashmaroli]

Is that possible? Wouldn't it need to be something different..?

Yep the best bet is to implement a new tag altogether.
From my understanding of Liquid code, it's not possible to make a tag behave as both inline-form and a block-form.., but I can't say it's definitely not possible with surety either..

Either ways, this is best seen as a plugin-case.

[pathawks]

@ashmaroli Is right; this is probably best implemented as a plugin.

It wouldn’t make sense as an upstream feature request to Liquid, because the include tag is ours and is not present in vanilla Liquid.

[cmegown]

I initially assumed this may progress up to the Liquid repo since there's an include tag, but if that's different from what Jekyll is using then ultimately this idea will probably stay here.

I'm glad this issue is generating some conversation though. Here's another very practical example of how this sort of feature would be useful:

// _include/generate-component-sample.html
<div class="sample-wrapper">
  <div class="sample-live">
    {{ include_content }}
  </div>
  <div class="sample-code">
    {% highlight html %}
      {{ include_content }}
    {% endhighlight %}
  </div>
</div>

// button docs
{% include generate-component-sample.html %}
  <button class="c-btn">Button</button>
{% endinclude %}

// form docs
{% include generate-component-sample.html %}
  <select class="c-select">
    <option>Select...</option>
    <option>Alphja</option>
    <option>Bravo</option>
    <option>Charlie</option>
  </select>
{% endinclude %}

Would allow reuse of a generic component include that could easily be used hundreds of times in a project like a design system. Being able to avoid writing a {% capture %} block for each of these would be aces.

[ashmaroli]

@cmegown The include tag you're referring to is only available for use in themes for Shopify stores.
So, your suggestion won't find an audience there.

Coming back here, do note, there's no point discussing on the merits of the idea, any further.
We do not plan on altering existing include tag nor shall the Core have a new tag implemented for the idea.

Sorry.

[cmegown]

Yep, I understand this concept won't be rolled into the core but a couple of comments mentioned this could be implemented via plugin. I don't possess the ability to do the work myself, but if anyone else is interested in taking on the work I wanted to provide another example of how it might work.

[pathawks]

I initially assumed this may progress up to the Liquid repo since there's an include tag

As @ashmaroli mentioned, this is a custom Shopify tag, just like Jekyll has its own custom Liquid tag. Vanilla Liquid has no include tag.

Closing this as wont-fix, but would love to see a plugin take this up.

Edit: Not closing, since it seems @ashmaroli is plotting something

[ashmaroli]

@cmegown My sincere apologies if shot you down. The issue will remain open.. do send the word out to our enthusiastic community.. Somebody will take up on the challenge.

[cmegown]

@ashmaroli Nope, don't worry about it. I actually learned that the Shopify theme docs and the Liquid docs are different things 🙃

While I may not be able to write the plugin myself I would certainly be interested in helping any way I can.

[hugmanrique]

I'm two years late, but I needed something similar for my blog. I present to you jekyll-transclude.rb.

Credits go to Corey for the original idea and syntax. I'm a Ruby noob, so please don't judge me 😄