Jekyll - Managing Code - Part One

   
   
 jekyll  plain  
 ssg  
Article Series

Jekyll in General

Jekyll Plain

Jekyll Bootstrap OC

Jekyll Bulma MD

Conclusions

Repository

Where to Discuss?

Local Group

Table of Content

Preface

Goal: Get organized with your theme.

Source Code

This article use tutor-04 theme. We will create it step by step.

1: Liquid Code Placement

The Issue: Where to Put Liquid Code?

So far we have three places to put liquid code:

  • pages as content, or

  • _layouts, or

  • _includes.

Layout, Include?

Be flexible!

Should I place code in _layouts or _includes? The rule is simple, if the code is reusable, the code is better placed in _includes.

You can use your own rule to manage your coding placement. Personally I’m using _layouts, to manage content placement using CSS layouts, such as main and aside, but there is no rule for this. You can put your code, depend on your situation.

What Code?

We are going to deal with our last custom pages.

  1. Archive

  2. Tags and Categories

  3. Blog (Article List)

Layout: Header

Since our site become more complex, and it need to be fitted in small screen. we need to prepare with a better navigation.

  <p>
    Menu:
    <ul>
      <li>
      [ <a href="/">Home</a> ]
      [ <a href="/pages/">Blog</a> ]
      [ <a href="/pages/about">About</a> ]
      </li>
      <li>
      [ <a href="/tags/">Archive by Tags</a> ]
      [ <a href="/categories/">Archive by Categories</a> ]
      </li>
      <li>
      [ <a href="/by-month/">Archive by Month</a> ]
      [ <a href="/by-year/">Archive by Year</a> ]
      </li>
    </ul>
  </p>

  <hr/>

Jekyll: Home Navigation

Rewrite Overview

We are going to use these file artefacts.

  1. Blog:

    • Content: pages/index.html
    • Layout: _layouts/index.html
    • Includes: _includes/index/blog-list.html

  2. Tags and Categories:

    • Content: pages/tags.html, pages/categories.html
    • Layout: _layouts/index.html
    • Includes: _includes/index/terms*.html

  3. Archive (by-year, by-month):

    • Content: pages/by-year.html, pages/by-month.html
    • Layout: _layouts/index.html
    • Includes: _includes/index/by-year.html, _includes/index/by-month.html

Notice, that all custom pages use the same index layout.

2: Layout Enhancement

Directory Tree: Includes

The _layouts directory contain files as below:

$ tree _layouts
_layouts
├── default.html
├── home.html
├── index.html
├── page.html
└── post.html

0 directories, 5 files

We are going to focus on these file artefacts above.

Layout: Liquid Default

Consider experiment with html5 tag main and aside.

<!DOCTYPE html>
<html>

<head>
  {% include site/head.html %}
</head>

<body>
  {% include site/header.html %}

  <main role="main">
    {{ content }}
  </main>

  <aside>
    <strong>{{ layout.aside_message }}</strong>
  </aside>

  {% include site/footer.html %}
</body>

</html>

Jekyll: Tutor-04: NERDTree

Notice that we now have layout.aside_message variable. This should be set in any child layout, in frontmatter.

Frontmatter: aside_message

How does it looks ?

Layout: Liquid Page

---
layout: default
aside_message : This is a page kind layout.
---

  <h2>{{ page.title | default: site.title }}</h2>

  {{ content }}

  <blockquote>Any question? <b>Good Luck</b>.</blockquote>

Layout: Liquid Post

---
layout: default
aside_message : This is a post kind layout.
---

  <h2>{{ page.title | default: site.title }}</h2>
  <pre>{{ page.date | date: "%B %d, %Y" }}</pre>

  {{ content }}

Layout: Liquid Home

---
layout : default
aside_message : This is a home kind layout, to show landing page.
---

  <h2>{{ page.title | default: site.title }}</h2>

  {{ content }}

Layout: Liquid Index

Add finally index layout, as a child of page.

---
layout: page
aside_message : This is an index kind layout, to show list of archive.
---

{{ content }}

You can use page layout directly, I’m using special index page, just to differ ordinary page and custom page that contain liquid loop.

Jekyll: Template Inheritance: Parent and Child

3: Custom Pages: Index

Consider move liquid code, from content in pages/ folder to partial in _includes/index/.

Partial Liquid: Blog List

  <ul>
  {% for post in posts %}
    <li>
      <a href="{{ site.baseurl }}{{ post.url }}">
        {{ post.title }}
      </a><br/>
      Tag: 
      {% for tag in post.tags %}
        [ <a href="{{ site.baseurl }}/tags/#{{ tag | slugify }}"
            >{{ tag }}</a> ]
      {% endfor %}
    </li>
  {% endfor %}
  </ul>

Separate Variable Initialization

But why would I want that?

Notice that we haven’t assign anything to posts variables. This variables should be set in pages or _layouts.

This means we can use the same view output, but using different variable initialization, such three choices below:

{% assign posts = site.posts %}
{% assign posts = paginator.posts %}
{% assign posts = page.posts %}

Or one variable initialization, to adapt for different view scenario, such three choices below:

{% assign posts = page.posts %}
{% include index/blog-list.html %}

{% comment %}
  Alternative view
  {% include index/by-month.html %}
  {% include index/by-year.html %}
  {% include index/blog-list.html %}
{% endcomment %}

Content: Blog

---
layout    : index
title     : Blog Posts
permalink : /pages/
---

{% assign posts = site.posts %}
{% include index/blog-list.html %}

Now see how this custom page looks like.

Jekyll: Custom Pages: Blog

What’s Next?

Consider continue reading [ Jekyll - Plain - Managing Code - Part Two ].

Thank you for reading.