Define semantics for include directive

[epage]

@gnunicorn pointed this out on gitter.

Prior Art

Jekyll

• https://jekyllrb.com/docs/includes/
• _includes folder is flat (include dir/menu.liquid grabs _includes/dir/menu.liquid)

Hugo

• https://gohugo.io/templates/partials/
• layouts/partials is the root
• _layouts beat themes (consistent with hugo's theme override policy, see RFC Reusable themes #301)
• no non-layout partial support

[gnunicorn]

May suggest renaming the Issue? Because this isn't about _layouts but _includes-path. I think our _layouts behaviour is fine as is. Just for includes it is annoying to prefix it every time from the root folder (and partials like the menu shouldn't be in _layouts IMHO).

[epage]

Ok, went and gave it a more general name

I haven't seen snippets being used in the wild in that kind of idea...

The idea is you have two different kind of partials

• theme/layout partials for sharing design elements (e.g. headers) between layouts (posts, pages, etc)
• content partials like menus that pages or layouts may include

My current thought:

• _theme/includes for theme-defined layout partials
• Treat _layouts as
  • A way to override a theme like Hugo
  • A less formal way of doing design without a theme
• Therefore, _layouts/includes that occupies the same include "namespace" as _theme/includes
• _includes folder for content (like menus) partials, rather than layout partials, in a potentially distinct namespace or directive
  • As you mention, there isn't much precedence for this but a reasonable use case (menus)
    • I'd consider skipping this for now but I'd at least like to have the namespace/directive question answered so I don't break compatibility if we add it later
  • Jekyll only has themes or _includes, so _include looks overloaded.
  • Hugo only seems to have layout-focused partials

This will break compatibility with the current lookup path. Initially, I will submit a lookup that will merge the source dir in with a "" namespace to keep compatibility. cobalt will issue deprecation warnings when these lookups occur. Then in my planned breaking release, I'll drop support for this.

But I think I am moving a bit away from your initial question. I'd keep layouts and includes separate, with layouts being flat and not included in the include-directive. and includes have a few, ordered templates-directories, but under that have a full hierarchy (this is also how many template system, like Django or Ember, do it afaik)

My proposal above is a halfway ground. We aren't mixing layouts and layout partials but they are kept near each other.

So include "namespace" or directive

IF the snippet and layout folder behave different (or have different hierarchy) I'd be in favor of reflecting that to the template users, by actually having an include and a snippet directive respectively (though internally they might be going to the same function just having a different search path).

If not, I wonder, why have to distinct ones in the first place. It's just semantics at this point, is it not? So why not just make the included_dir a list of _snippets, _includes, _theme/default (or something) on a first-match-win-basis. This would also easily allow people to replace any include for their local thing by putting their own custom-folder first and still have distinct reusable and sharable snippets, includes and themes ...

So you recommend _includes, _layouts/includes, and _theme/includes all occupy the root ("") namespace, meaning that include menu.liquid will look in each of those folders?

I like the simplicity of it. I'm also torn because my goal is to encourage a separation of layout and content, I like the idea of distinguishing _includes somehow.

Hmm, in thinking about this more, if _layouts is a less formal way (with assets like css being in the regular source), maybe it is fine for _layouts to not have its own includes directory.