Partials: Includes with layouts #32

koraktor opened this Issue May 5, 2009 · 22 comments


None yet

koraktor commented May 5, 2009

Call it partials, subpages or whatever. I came to a point where I wanted to generate multiple similar sections in a page and found no way to achieve this with Jekyll. Instead of writing lots of "copy & paste" code, I'd like to use some kind of partial (like in Rails).

I created a new tag for this, called import. It's more or less the same as the include tag, but it uses Jekyll::Page for rendering, not just Liquid::Template.


Please note that this isn't perfect yet - e.g. you can't use this in Markdown or Textile files as line wraps and indentation are interpreted.


koraktor commented May 6, 2009

Another easier way to accomplish this is to make Post.output available to Liquid. But this still creates the "standalone" HTML files.
I would really appreciate any implementation of this feature on GitHub pages.


koraktor commented May 7, 2009

To work around this on GitHub pages I let Jekyll render standalone HTML files and include them via prototype's Ajax.Updater. This is far from optimal, but it works.



qrush commented May 8, 2009

Great idea, definitely needs tests. On hold until that happens.


koraktor commented May 8, 2009

Partials in jekyll would be great.

I would love that feature :)
I have quite a lot of "partials" on my blog
and so far I've been cheating around it with some "include ..."
and "assign ...".
But I still have to do some "if ..." to work around unformatted content.


koraktor commented Feb 3, 2010

The changes now reside in koraktor/jekyll@import-tag.

bronson commented Nov 17, 2010

Another vote for partials! I'm needing it a lot on my site. Any idea what still needs to happen for this to be merged and released?


koraktor commented Nov 18, 2010

Just rebased my branch on the lasted changes.

doolin commented Dec 25, 2010

@koraktor - looking at your import tag right now. Nice work, thanks!

@mojombo Any hints on if/when partials will be supported on Github Pages?

It feels like such a core feature of a templating system...

Is there anything the community can do to help push this feature request along?


koraktor commented Apr 7, 2011

Just rebased my topic branch.

I won't start a pull request, because I don't want to duplicate things. Nevertheless I really hope this will be merged soon.

Wow, so jekyll can't do partials yet? I'm about to migrate my blog from wordpress, and this seems like a bit of a deal-breaker...

kenliu commented Sep 15, 2011

I'd love to use jekyll but can't use it without this feature.

I've solved my problem by generating the liquid templates with HAML. You could do the same with ERB.
i.e. HAML/ERB → Liquid → HTML

I used a modified version of haml-jekyll-extension, so that a template at _haml/_layouts/default.html.haml is rendered to _layouts/default.html.

Since base templates aren't edited as often as blog posts, I think this is a good workaround.

what about just

    {% include _left_nav.html %}

this works for me.


qrush commented Jan 1, 2013

Yeah just use includes. Partials might be a smell that Jekyll isn't enough for what you need.

qrush closed this Jan 1, 2013

ldamon referenced this issue in mborsare/ Aug 4, 2014


Refined project footer navigation, responsive styles #6

I know this is an old thread but it was the top Google result and I faced this problem recently. I wanted an include to use a particular layout when calling that include. A fairly simple way I found around not having this functionality, was to use the 'layout' as an 'include' (let's call it the layout-include.html) and pass a 'src' variable when calling the layout-include ('src' could be called anything of course but I think this fits well with normal html semantics).

So, this would be your layout-include.html file which contains all your layout markup etc. Nested inside is another include, where the source for the include is set to the variable {{include.src}}.


<div class="layout">
    {% include {{include.src}} %}

Here's the include-content.html file

<h2>Here is my content</h2>
<p>all here....</p>

Then, when you call 'include-layout.html' from the file you want Jekyll to output, you pass in the include.src variable as follows:
(e.g. source/index.html)

layout: default
{% include include-layout.html src="include-content.html" %}

Unfortunately, markdown in the 'include-content' file won't be rendered (at least in my environment it wasn't) so it will have to be an html file.

The nice thing about it is that you can still use different layouts for different parts and not have duplicate code when you want to use the same layout.

Hope it helps someone out!


gesa commented Oct 19, 2015

@ChrisSargent I'm curious what version of Jekyll you're using. When I try to use this solution, I get the error Liquid Exception: Invalid syntax for include tag. File contains invalid characters or sequences: Valid syntax: {% include file.ext param='value' param2='value' %} in _layouts/white-container.html

Also, it's a little convoluted, but to get Markdown, perhaps you could do

{% include include-layout.html src="" %}
<div class="layout">
{% capture thisPage %}
    {% include {{include.src}} %}
{% endcapture %}
{{ thisPage | markdownify }}

@gesa, it seems I have Jekyll 2.5.3 installed.

I just updated my comment too to make it a little clearer.

The suggestion you made for the markdown didn't work for me but, I was able to get it working actually, I just couldn't use any front matter in the content file (because it was also getting rendered). Here's what I ended up with:

## Here is my content

all here....


<div class="layout">
{% include {{include.src}} %}

layout: default

{::options parse_block_html="true" /}
{% include include-layout.html src="" %}

So all I had to do was change the file extensions and add the line {::options parse_block_html="true" /} in to the index file (This is assuming using Kramdown, the default markdown renderer in Jekyll).

davidgoli commented Jun 3, 2016 edited

@qrush I don't think include addresses the use case for import. Consider:

layout: some-nested-thing
{% import section-wrapper %}
Some really long block of text
{% endimport %}

{% import section-wrapper %}
Another long block of text
{% endimport %}

Unless I'm missing something, I don't see how this is possible to accomplish with include without assigning the text blocks to page variables (a stinky stinky code smell).

I'm low-key shocked that this templating system doesn't support this as it's a really basic feature supported by haml, handlebars, and many other popular templating languages and not at all a power-user feature as you suggest.

I too would love for this to be reopened.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment