jimhall.sh | grep "interesting things"

At least to me. Mostly tech / computing

Archive

About

Categories

Tags

Subscribe

2 July 2020

GitHub Pages 2020: Foundational Directories and Files (Part II)

by Jim Hall

After creating a repo in GitHub and enabling GitHub Pages for the repository, you have a to pick a “theme”. A theme is basically a display style for your website. In my case I chose the theme “Hacker”.

I took a look at the directory to see what was created and it turned out to be a very lonely _config.yml file. The contents of the file had a single entry of theme: jekyll-theme-hacker. No other directories or files. This post addresses what directories and files I created to make a sane blog (in my opinion).

Take a look at the ghpages tag page for all the posts in this series.

Overall Task Map (checked items in this post)

Theme Choice: An Aside

As mentioned above, I picked one of the default Jekyll theme’s for GitHub Pages called jekyll-theme-hacker. The black background and green font reminded me of my days starting out building and designing trading floors for financial services companies. When I first started the transition from “green screens” (stacks of small picture tube monitors using phosphorescence to “light up” the screen) to PCs and ethernet was kicking off. Think the movie Wall Street (see below):

Green Screen Image

While I was attracted to the aesthetics of the theme, in hindsite I probably should have picked a more complete theme like jekyll-theme-minimal. Ironically, jekyll-theme-hacker was more “minimal” then jekyll-theme-minimal in terms of the information it would display that would be helpful for blog site. On the bright side, the lack of display functionality helped capture a lot steps below on how to create a blog site.

Create Directory Structure for Blogging

Strictly speaking, most of the steps below are optional. As mentioned in Part I, you could create a blog entry in the _posts directory and have at it. But I take things a little bit further to create a more full featured blog.

Diagram of File and Directory Structure

Here is a simple layout to create a more full featured blog:

README.md
.gitignore
index.md
_config.yml
favicon.ico
about.md
_includes
      |_ head.html
      |_ footer.html
      |_ header.html
archive
      |_ index.md
_posts
      |_ <various posts reside here>
_layouts
      |_ post.html
      |_ tags.html
      |_ default.html
      |_ archive.html
      |_ categories.html
tags
      |_ index.md
_sass
      |_ jekyll-theme-hacker-local.scss
      |_ jekyll-theme-hacker.scss
assets
      |_ images
categories
      |_ index.md

Table Describing Diagram

File or Dir Description
README.md Standard repo description of site. I use it as a changelog
.gitignore Since on a Macbook I skip all the .DS files
_config.yml Jekyll config file
index.md Jekyll compiles/changes into index.html
favicon.ico Graphic for bookmarks and URL bar
about.md Jekyll compiles/changes into about.html (who am i?)
_includes/head.html Jekyll template for <head> html metadata
_includes/footer.html Jekyll template for <footer> (shown at the bottom of every page on my site)
_includes/header.html Jekyll template for <header> (shown at the top of every page on my site)
archive/index.md Jekyll template that generates a date sorted list of my blog posts
_posts Blog posts in markdown format that are then compiled into an html page
_layouts/post.html HTML that renders blog post
_layouts/tags.html HTML that renders tag summary page post
_layouts/default.html HTML that is default rendering for a web page for the blog
_layouts/archive.html HTML that renders the archive page
_layouts/categories.html HTML that renders a category web page for the blog
tags/index.html HTML that renders a summary of tags web page for the blog
_sass/jekyll-theme-hacker.scss CSS & SASS from the default hacker theme
_sass/jekyll-theme-hacker-local.scss CSS & SASS from added by me
assets/images/ HTML that renders a summary of tags web page for the blog
categories/index.md HTML that renders a summary of categories web page for the blog

Understanding How Pages Get Built

As I started to build some draft blog posts, I found it made sense to “break up” the rendering to avoid repeating markdown and html for various pages. Let me walk through my methods and thought process below.

  1. Write the blog post in the _posts directory with Markdown. Add Front Matter keyword layout: post. This means it will refer to _layouts/post.html to begin the process of creating the blog post html. post.html also has some html to set page date, title, and some Jekyll Liquid to display category and tags.
  2. _layouts/post.html refers to _layouts/default.html. _layouts/default.html with some simple html and Jekyll Liquid include tags to build the <head>, <header> and <footer> sections of the html doc.
  3. _includes/[head|header|footer].html contain the html that will render the relevant section of the html document for the site.
  1. archive/index.md contains the FrontMatter keyword layout: archive. This page is using some Jekyll Liquid for a loop that lists all the posts put up on the site so far.
  2. The front matter in archive/index.md will pull in _layouts/archive.html which has similar Jekyll Liquid include tags as _layouts/default.html, just missing the <div> tag because are general content being developed for the page.
  3. Similar rendering as seen in step three for blog posts
  1. tags/index.md and categories/index.md have Jekyll Liquid logic that lists out all the tags or categories and the blog posts associated with them. It also calls Front Matter keyword layout: default.
  2. Similar rendering as seen in step three for blog posts for aspects of the standard html doc for the site.

Review _includes requirements

When building the site, it seemed to make most sense to have separate include files for the <head>, <header> and <footer> sections of the sites web pages and just keep it consistent. Leveraged the idea from the work of @tocttou and their hacker-blog repo. Here are some notes:

_includes/head.html

_includes/header.html

_includes/footer.html

Review _layouts requirements

Looking at other example websites, I used _includes files for fundamental page sections that apply to all page types, and I used _layouts to control how a page type is displayed. default.html layout contained the components with the most commonality. I will walk through post.html in detail, other layouts are very similar.

Here is a gist of post.html:

Code Highlights:

Other Layouts

The other layouts have similar logic, I will detail in follow on posts. _layouts/post.html is probably the most complicated.

Review _sass requirements

I am torn on the best approach regarding how to customize SASS and CSS with GitHub Pages. I will outline two approaches to customizing SASS: my current approach and alternate method that has potential advantages:

Current Approach

Alternate approach

Next post will show examples of both.

Create an index.md

Here is a listing of the index.md I created for the blog site.


---
layout: default
title: Welcome to my blog
---

<!-- Begin code @ index.md -->

# Welcome to my blog

I'm glad you are here. Thanks for stopping by!

Send constructive points or constructive criticism by clicking the social links in the
footer.

<ul>
{% for post in site.posts %}
  <li><span>{{ post.date | date_to_string }}</span> » <a href="{{ post.url | relative_url }}" title="{{ post.title }}">{{ post.title }}</a></li>
  {{ post.excerpt }}
{% endfor %}
</ul>

<!-- End code @ index.md -->

It does the following:

I am going to stop here as it gets a user to reasonable point. Stay tuned for the final post on this topic which brings GitHub Pages to what I consider to be a reasonable point for blogging.

categories: blog - computing - github
tags: ghpages - jekyll