The Lean TECHniques Website: the Basics — Lean TECHniques

The Lean TECHniques Website: the Basics

By Brandon M Carlson

The LT Web inner workings and creating a rant.

What is Jekyll?

Jekyll is a static site generator that was created to make creating a website easier, it is more popularly associated with blogs. I mean, why wouldn’t it be? It includes a file path for blog posts! Speaking of files, maybe we should start with the Jekyll file tree.

The File Tree

Below is an example file tree for a simple website. This bad boy came straight from the Jekyll Docs:

.
├── _config.yml
├── _data
|   └── members.yml
├── _drafts
|   ├── begin-with-the-crazy-ideas.md
|   └── on-simplicity-in-technology.md
├── _includes
|   ├── footer.html
|   └── header.html
├── _layouts
|   ├── default.html
|   └── post.html
├── _posts
|   ├── 2007-10-29-why-every-programmer-should-play-nethack.md
|   └── 2009-04-26-barcamp-boston-4-roundup.md
├── _sass
|   ├── _base.scss
|   └── _layout.scss
├── _site
├── .jekyll-metadata
└── index.html # can also be an 'index.md' with valid front matter

Here we see seven basic folders: _data, _drafts, _includes, _layouts, _posts, _sass, and _site. While site is empty, it is very important.

The Folders and the Files

Now, most of the folders are fairly self explanatory. I doubt I need to talk about _posts, _drafts, _data, or _sass. The remaining folders are _includes, _layouts, and _site. Quickly, before we get into the folders, let’s use a post template for the LT Website.

---
layout: rants/rant
title:                                      # Your post title goes here
author:                                     # Don't write anything here
  name:                                     # Who's writing/wrote this?
  image: ../../assets/images/team-members/  # You work for LT? Add your image file.
date: [YYYY-MM-DD] [HH:MM:SS]
permalink: rants/                           # Add the article title, or ':title' if you want
categories:                                 # How would you categorize this?
tags:                                       # How would you tag this?
excerpt_separator: <!--more-->              # This divides where your synopsis from the rest of your article.
pdf_link: ../../assets/pdf/                 # What's the file name?
---

<!-- This is what is shown on the /rants/ page -->
<div class="first-line">Hey, check me out! I'm the stuff you see on the /rants/ page!</div>
<!--more-->

Hello, { {page.author.name}}. You look very nice today. Did you know that your article is called "{ {page.title}}"? Nothing that you're reading here will show up on the `/rants/` page, just the line above "<!--more-->"

<!--
<iframe class="article-frame" src=<!--"{ {page.pdf_link}}"-->></iframe> 
<div class="pdf-things">
  <a class="download-PDF" href=<!--"{ {page.pdf_link-->}}" download>Download The PDF</a>
  <a class="view-PDF" href=<!--"{ {page.pdf_link-->}}" target="_blank">View in New Tab</a>
</div>
-->

Toward the top of the template, we notice three dashes, and then eventually another three. This is what Jekyll uses to add details to pages. Everything in between these dashes is part of the Front Matter. Any variables you add to the front matter will be available for use on the post with {{page.[FRONTMATTER-VARIABLE]}}. We can also use the data from the front matter in the layout of the rant’s page.

“_layouts” is nice becuse it allows you to create a template for how you want your pages to look. We’ll continue using the example of an LT rant. This is how we have each individual rant templated:

# I have added spaces in-between each couple curly braces and before each "%" in order to stop them from including actual items. 

<!DOCTYPE html>
<html>
<title>{ {page.title}} &mdash; { {page.author.name}}</title>
{ % include _head.html %}

<body>
  { % include _nav.html %}
  <div class="rant-container content-fluid">
    <div class="rant">
      <h4 class="rant-title">{ {page.title}}</h4>
      <div class="rant-author">
        { % if page.author.image != undefined %}
        <div class="author-image-container">
          <a src="/team/{ {member.image}}">
            <img class="author-image" src="{ {page.author.image}}" />
          </a>
        </div>
        { % endif %}
        <h5 class="author-name">By { {page.author.name}}</h5>
      </div>
      { { content }}
      <h6 class="rant-date">Published: { {page.date | date_to_string: "%m %d %Y"}}</h6>
    </div>
    <button type="button" class="btn-default btn-info" onclick="javascript:history.back()">Take me back!</button>
  </div>
  { % include _footer.html %}
  { % include _scripts.html %}
</body>

</html>

As you can see, it pulls the data from whichever rant was clicked on. You might have noticed that there’s a spot marked {{content}}. Everything outside of the Front Matter is considered the “content” of the post. We use layouts in everything, including every page on the website. Although, the standard pages are much easier to deal with than the “rant” page. For example: this is what the /rants/ page looks like, which is the page before this one.

<!DOCTYPE html>
<html>
{ % include _head.html %}

<body>
    { % include _nav.html %}
    { { content }}
    { % include _footer.html %}
    { % include _scripts.html %}
</body>

</html>

See how much more simple it is? How much easier it is to read and understand? Now, you might be thinking to yourself “You know, I’ve been seeing a lot of this ‘include’ keyword, it’s even got it’s own syntax. Why?” Well I won’t tell you. … Alright fine, you’ve convinced me.

“_includes” is a really nice way to build your website. Anything under the includes folder is able to be called anywhere in the file trees with ease. The curly brace and percent are an indicator for Jekyll to start working it’s magic. I’ll use an example of includes here… Who would like to see the services section of the home screen?

Here’s how we’ll include it:

{ % include _services-section.html %} (Without the space between ”{ %” ) Renders…

How we help

Our people are nerdy but cool problem solvers

Whether you're trying to take advantage of the benefits of cloud computing, get the project out the door on time, or create the next market-disrupting product, we can guide you down the road to success.

BOOM! Like magic it’s on the screen in front of you. With proper use of includes tags, pages will look much less cluttered. Less clutter = easier to read = easier to maintain. Plus, the way that we do it, we don’t have a database to maintain. To read more on that, check out Tim’s Article.

Now, previously I mentioned the folder called _site, and I told you that it was important. Well, here’s why: when you start up your local Jekyll server using jekyll build; jekyll serve; jekyll build will compile all of your folder’s data and translate it into html within the _site folder. Jekyll serve makes the _site folder visible, and available to view at localhost:4000.

I Want To Write a Rant On the LT Website

Already? Wow, I sure appreciate your enthusiasm! Well, creating a rant is fairly easy. At this point I’m assuming you have already cloned the website from gitlab. If you’re yet to do so, I suggest that you do that now. I said before that we have a rant template that makes it easy to create a new rant. All you have to do is make a copy of it in _drafts and then move that copy to _posts.

Real quick, maybe we should look over the Front Matter and make sure we know what everything is, just in case.

I should also note that the posts are written in markdown. If you’re not familiar with markdown, or you need a refresher, you should check out Markdown Guide. If I didn’t do a well enough job explaining Jekyll, you should check that out too. After you’ve ensured that everything you need is in order and ready, just begin typing! The only additions that you need to worry about are PDFs, and the things you need for that are already included in the template. I’m sure that in the end, your rant will end up better than this one. Good luck, let’s see what we can do!

Published: 19 Feb 2019