CODEWITHSUNDEEP
rubymarkdownjekyllliquid
crowhill
crowhill

Reputation: 2558

How does Jekyll use post.html to generate pages?

I'm having some difficulty getting Jekyll to use a particular theme and I think there's something fundamental I'm missing about how {{ content }} works with posts.

So, in a generic Jekyll site, index.html has a layout specified in its front matter. When the site is generated, the layout includes index.html as {{ content }}. It's kind of inverted, where the page specifies the layout and then the layout calls the page, but simple enough.

Posts, on the other hand, are all generated via a file, post.html, which resides in the _layouts folder even though it isn't really a layout. Like index.html it's essentially just a for loop. This is where I'm running into trouble.

Is post.html a required file? Could I rename it story.html?

Why does post.html require a layout in the front matter? The actual post, that is, the markdown that contains the text for said post, also requires a layout in its front mater. Is there a circumstance where post.html would have a different layout than the layout specified in the markdown file?

Edit: one other question. Why is {{ content }} called in multiple places? index.html and the layout file both have {{ content }}. Why doesn't the layout simply {% include %} index.html and let index.html call {{ content }}

Upvotes: 4

Views: 1923

Answers (2)

Christian Specht
Christian Specht

Reputation: 36441

I think you largely figured it out by yourself, but I'll still explain it in my own words.

You're right that {{ content }} is the placeholder in the layout file where the content of the actual page will go.

What probably confused you is the fact that you can build a set of nested layout files where one "inherits" from the other, and each layout has its own {{ content }}.
And yes, I didn't find anything about this in the docs, I figured it out by myself or better, by looking at examples.

So here's an example for you.
First, a default layout and a page:

/_layouts/default.html:

<!DOCTYPE html>
<html>
<head>
    <title>{{ page.title }}</title>
</head>
<body>
<h1>{{ page.title }}</h1>

{{ content }}

</body>
</html>

/index.md:

---
title: example page
layout: default
---

This is the page content.

The generated HTML will look like this:

<!DOCTYPE html>
<html>
<head>
    <title>example page</title>
</head>
<body>
<h1>example page</h1>

<p>This is the page content.</p>

</body>
</html>

Now let's create another layout file that "inherits" from the first one.
You'll probably want to use something like this if you're building a blog with Jekyll.
The layout file shown above is the default for all pages, blog posts and regular ones.
When you want all blog posts to contain additional information like post date and user, tags and so on.

For this, you can create a second layout file which uses the first one:

/_layouts/post.html:

---
layout: default
---

<div class="blogpost">
    <i>post date: {{ page.date }}</i>

    {{ content }}
</div>

And a blog post which uses this layout:

/_posts\2015-04-08-example-post.md:

---
title: example post
layout: post
---

This is the post content.

And the generated HTML:

<!DOCTYPE html>
<html>
<head>
    <title>example post</title>
</head>
<body>
<h1>example post</h1>

<div class="blogpost">
    <i>post date: 2015-04-08 00:00:00 +0200</i>

    <p>This is the post content.</p>
</div>

</body>
</html>

In other words, something like this happened:

  1. Jekyll used the post layout and put the content of the post into {{ content }}
  2. Jekyll used the default layout and put the complete generated HTML from step 1 into {{ content }}

(no idea if Jekyll really does things in this order under the hood, but you get the idea)

You can see another example if you create a new Jekyll project as shown in the "Quick-start Instructions" on the home page of the Jekyll site.
The example site that Jekyll (version 2.1.1 on my machine) creates has three layout files, two of which (page and post) inherit from the default one.

Upvotes: 5

crowhill
crowhill

Reputation: 2558

I have an answer for myself, sort of. Each markdown file is assigned a layout in the front matter. But this "layout" isn't really a layout at all or it's a partial layout?

The terminology escapes me, so I'll just list the steps.

1) The markdown file has layout: post

2) Whatever is in the markdown file gets processed and then sent over to the logic residing in post.html. Here's the part that I wasn't getting right off: post.html has it's own layout. That's what's up in the front matter. Essentially we have the layout's layout.

3) The outer "layout" (default.html in a vanilla jekyll install), wraps itself around the inner "layout" (post.html), which wraps itself around the actual {{ content }}.

post.html could be named whatever, so long as the various layout lines are properly set.

I still don't know why {{ content }} winds up at the top of the layout stack only to be passed all the way back down. I'm not even sure "passed" is the right word when dealing with liquid. I like Jekyll, but it's kind of a nest of snakes.

Upvotes: 0

Related Questions