Support a new relative_include tag

[gjtorikian]

This PR aims to solve a problem reported here and elsewhere.

When it comes to assets, I'm perfectly happy with the following import strategy:

---

---

{% include assets/javascript/jquery.min.js %}
{% include assets/javascript/foo.js %}
{% include assets/javascript/whatever.js %}

What bothers me, though, is that I must place my assets in the _includes folder. Given that SASS has its own import notation, and that I want to be a good citizen and use Bower for imports, it becomes impossible to keep all my assets tidy and in a single location.

With relative_include, I should be able to include files relative to the file they're defined in. I should not be able to do ../ and go somewhere else--that's bad. Most of this checking--along with evil symlinks--is already accomplished by the current IncludeTag, which is very nice.

Please let me know how you feel about this. 💟

[parkr]

I like it. Feels like it overlaps with collections, though... Collection documents are meant to be pieces of include-able stuff. That's why collections are optionally rendered. Have you tried this with collections?

[gjtorikian]

I've just tried working it out in collections, here's my experience so far.

I create an _assets directory to start with. As I would like to keep my SASS and JS/CS in separate, but within one directory, I create two subfolders for each of them.

As you pointed out, I can flip output to false to not have these files in the rendered output. Now, to collect the content, I can do something like the following in a layout:

{% for asset in site.assets %}
  {{ asset.output }}
{% endfor %}

And here's the rub (as I see it): we're just dumping the contents straight into the HTML. We're not able to compress it, or even generate a single file. Well, that's not entirely true: I can create a separate file outside of my _assets directory, whose sole purpose it is to collect the CSS and JS within the loop, so that it can be included in the project. Now I have two assets directories.

I can push to a dummy repo to show what I mean, but I'm trying to work out a way for there to be just a single assets directory that contains all the assets. For Sass, this is pretty easy. Create assets/stylesheets, then create a file called application.scss, with these contents:

---
---
@import 'globals';
@import 'plugins';
@import 'sections';
@import 'shared';

In _config.yml, write the following and you're done:

sass:
    sass_dir: assets/stylesheets/
    style: :compressed

For JS, you can create a single file like the one above. And with relative_include, you can create subfiles within the same directory. And all of it would be output as a single JS file.

Am I mistaken somewhere?

[parkr]

Why use case statements instead of just overwrite certain methods based on the tag class? If you have a separate class, you may as well separate the class-specific code from each other. 😉

[gjtorikian]

true.dat

[parkr]

If you want me to do that, I am happy to submit a PR to your PR. Or something? #howtogithub

[gjtorikian]

Well, I was planing on just killing this and relying more on tag_name to do the weight. There's only two spots that need to change. Does that make sense? #howdoiprogram

[doktorbro]

Please note, that all includes run through the Liquid parser. I remember issues in the past with including sass files, because Liquid fails on invalid {% abc.

Is include_relative a stupid concatenation or is the Liquid parser involved?

[parkr]

dir_to_include? Are we including the whole dir? Or is it resolved_includes_dir?

[gjtorikian]

The second one. 😊

[parkr]

Lookin' preeeeety good! Just a couple comments above. ❤️

[parkr]

MERGED. 🎯

Would you mind writing some docs for this? There are docs already for the include tag – we should be able to latch onto those.

[gjtorikian]

@parkr More than these? gjtorikian@afd30b0

☕

[parkr]

Yeah -- there will be confusion (probably) around how relativity is applied there. Relative to site source? To includes dir? A bit more verbiage might halp :)

[brianzelip]

yes please more verbiage. i'm studying this right now (via github.com/jekyll/site/_includes/docs_ul.html):

{% assign items = include.items %}

<ul>
{% for item in items %}
  {% assign item_url = item | prepend:"/docs/" | append:"/" %}

  {% if item_url == page.url %}
    {% assign c = "current" %}
  {% else %}
    {% assign c = "" %}
  {% endif %}

  {% for p in site.docs %}
    {% if p.url == item_url %}
      <li class="{{ c }}"><a href="{{ site.url }}{{ p.url }}">{{ p.title }}</a></li>
    {% endif %}
  {% endfor %}

{% endfor %}
</ul>

I figure it's got something to do with this PR, but still don't get it.

[parkr]

The above code has nothing to do with this PR.

[mhulse]

+1 for relative includes! Any idea when this will make it into the gh-pages gem?

[gjtorikian]

Any idea when this will make it into the gh-pages gem?

It already is! We shipped Jekyll 2.4.0, which includes this, a few weeks ago.

[mhulse]

It already is! We shipped Jekyll 2.4.0, which includes this, a few weeks ago.

OMG, nice! 👍

That just made my weekend. Thanks @gjtorikian!!!

[ryanburnette]

Are there any docs for this?

[parkr]

http://jekyllrb.com/docs/templates/#including-files-relative-to-another-file

[ryanburnette]

Thanks!