Loading...

My First Markdown Post Using Jekyll

This is my first crack at generating a static site from markdown using Jekyll. The post itself will be the first user test of what I have built. I know I am doing far too many things at once here, but sometimes that is how I roll when learning something new.

More...
Fri, 05 May 2017 00:00:00 +0000 Jaron Sampson

This is my first crack at generating a static site from markdown using Jekyll. The post itself will be the first user test of what I have built. I know I am doing far too many things at once here, but sometimes that is how I roll when learning something new.

Later, I will put the details and code into a Lab. To that end, I want to keep track of what I did, while I am doing it.

Objective

I’ve built nice looking websites before from Bootstrap templates. One of the appeals of these is you get a lot of functionality by packing a lot of content into a single page design, but for Robot Sandbox I want something between a blog and a wiki. I want it to be attractive and responsive but I also need to be able to manage a lot of content. I don’t want to deal with databases so content management systems like WordPress and MediaWiki are out. I want it in a git repository for revision control and collaboration, but also so it will fit nicely into a continuous delivery toolchain. Markdown seems like the right choice for the data, and Jekyll seems like the right tool to marry that with a Bootstrap site.

Getting started

First, for $8 I bought a one page Bootstrap theme called Synero. Bootstrap is HTML5, CSS3, and javascript, and results in a clean, modern interface which is responsive; this allows it to look good on the desktop as well as on mobile devices. It is actually two pages, an index.html and a blog-post.html. After customizing the theme with the Robot Sandbox brand, I pulled those two pages apart into a header and footer file in the Jekyll conventional _includes folder, and I placed the rest of the content into two layout files in the _layouts folder.

I created a Jekyll configuration yaml file, explaining when to use each layout.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
defaults:
  -
    scope:
      path: ""
      type: "posts"
    values:
      layout: "default"
  -
    scope:
      path: ""
      type: "pages"
    values:
      layout: "main-site" # overrides previous default layout
      author: "Jaron Sampson"
  -
    scope:
      path: "labs"
      type: "pages"
    values:
      layout: "lab" # overrides previous default layout
      author: "Dr. Jekyll"

I also created a markdown file to represent a post in the _posts directory. This leaves me with an empty index.html file, since all the interesting bits are in the layout file (i.e. there is no content per se). That doesn’t feel right but we shall see. Let’s try to generate this site. I expect to have a web site with a single blog post.

Mostly successful!

Robot Sandbox's Inception

I ended up with a blog post! But that is all, there is no home page. Using an empty file will not work. I modified the “main-site” template to use a Liquid object for the page title, and then added some Jekyll front matter to the index.html file and regenerate the site.

1
2
3
---
title: Robot Sandbox DevOps
---

Bingo. Bingo

Findings

This approach will indeed work well. The resulting directory and code structures are easy to comprehend. The data will be easily managed within a git repository, and authored in simple markup. Development is made simpler by the built in server, just run jekyll serve in the project’s root directory, and as you make changes the site will be regenerated and ready to test on the localhost. Deployment and release concerns are the same as publishing any static website, we just have to add Jekyll to the toolchain.

Leave Comments