Getting Started with Jekyll

Jekyll is a static site generator that’s perfect for GitHub Pages and works well with various other hosting suites. It allows you to, among other things, write clean content in Markdown… and save yourself the trouble of writing hundreds of html files by hand if you want to make a blog. It is of course usable for other things, blogs just happen to be an easy example.

It’s how we get from nothing to a fancy blog in 5 minutes.

Okay, maybe not 5 minutes, but it’s pretty quick.

It’s this easy

Steps to Starting out a Blog with Jekyll

1. Grab a template?

Jekyll has a surprisingly substantial community of developers and designers who have created templates for themselves and are willing to let you use. For free. Or for somewhat small fee.

Save yourself the trouble of starting afresh and browse some themes. Once you’ve found your favorite, clone the starter repo from GitHub and check it out in your code editor.

2. Install Dependencies

Dependencies, dependencies, dependencies… You know the story.

Framework Dependencies

Jekyll is a Ruby gem so you’ll need to have Ruby installed if you don’t already have it.

        
  ruby -v
  # if this prints something greater than 2.0.0
  # then you're good.
  
  # if not...
  brew install ruby       # mac
  sudo apt install ruby   # linux

While at it, also install the Ruby package manager, bundler.

  gem install bundler

Site Dependencies

Now install the dependencies for the Jekyll theme you chose.

        
  cd "<path to your local clone>"
  bundle install

Launch the Dev Server

  bundle exec jekyll s

If you prefer to start from scratch;

        
  # create a new Jekyll site
  jekyll new site-name
  cd site-name

  # start the server
  bundle exec jekyll s

3. Write some content

Head into the _posts directory and create a new Markdown file named YYYY-MM-DD-title.md and drop in some content.

Front Matter

The first thing you’ll notice is that the file starts with a front matter section. This is a YAML section that tells Jekyll important context about the file and what it needs to do with it, such as:

The title of the post/page.
Which layout needs to be applied.
The date of the post.
Post metadata, such as categories and tags.

        
      


---
title: Starting Up
date: 2023-04-13 16:32 -500
categories: [tutorial,presentation]
tags: [jekyll, static-site-generators, blog]
---

Content

The rest of the file is just regular Markdown. Try to keep it sane — you know, spaces around your headings and other Markdown whatnots. You can also add extensions, such as jemoji, which adds GitHub-flavored emoji support to your Markdown (example, :point_right: = ).

Refresh your browser and you should see your new post.

Jekyll allows you to also write your own HTML components and style them as appropriate, then use them in your Markdown content.

4. Customize

Most themes are extensible and customizable. But…

It’s up to you to figure out how each theme dev designed their theme.
You don’t have access to the source code of the theme.
Figuring out how to customize some existing components (that you’ve not written yourself) will take some work. Customizing/generating content is easy. Customizing some aspects of the theme is hard. If you’re a control freak, you may want to start from scratch.

For the much that you can do, though,

_config.yml is the main Jekyll configuration file for your site.
Gemfile tracks all your dependencies and their versions. (Think package.json for Ruby).
Support for SASS and SCSS is built-in (nice!).

Lots of toggles! With controlled effects.

Writing Your Own `HTML` Components

You know it. Eventually you’ll want to. Here’s how to:

All HTML components go in the _includes directory.
CSS / SCSS goes in the assets/css directory.
“link” your CSS file in your HTML template.

See example in about tab.

5. Data APIs?

Put data in a filename.yaml file in the _data directory, and it will be accessible through site.data.filename variable.
Nice composability!