Getting Started with Jekyll

#codenewbie #jekyll #githubpages #ruby

I started working with Jekyll this weekend past; it's exceptionally beginner friendly, and it's essentially just a tool to build out static sites and blogs. It's built off of ruby and can run its own development environment, so it's very easy to make changes and see them rapidly.

I thought it would be a decent enough staring point since to date, my first experience with Ruby web frameworks was Rails - this is far more lightweight - to the point that making an analogy with Rails actually makes no sense. Since it's so simple, there is no model or database management. Essentially, Jekyll uses a combination of Markdown, HTML, CSS and a template language "Liquid" to render the sites.

Setting up is very fast - let's assume you already have Ruby ready to use on your machine.

In the terminal I simply ran

$ gem install bundler jekyll
$ jekyll new blog-post-site

where 'blog-post-site' was just the name of the new directory that I was making. That generated a whole lot for me:

 Bundler: Fetching gem metadata from https://rubygems.org/...........
  Bundler: Fetching gem metadata from https://rubygems.org/.
  Bundler: Resolving dependencies...
  Bundler: Using public_suffix 3.0.2
  Bundler: Using addressable 2.5.2
  Bundler: Using bundler 1.16.2
  Bundler: Using colorator 1.1.0
  Bundler: Using concurrent-ruby 1.0.5
  Bundler: Using eventmachine 1.2.7
  Bundler: Using http_parser.rb 0.6.0
  Bundler: Using em-websocket 0.5.1
  Bundler: Using ffi 1.9.25
  Bundler: Using forwardable-extended 2.6.0
  Bundler: Using i18n 0.9.5
  Bundler: Using rb-fsevent 0.10.3
  Bundler: Using rb-inotify 0.9.10
  Bundler: Using sass-listen 4.0.0
  Bundler: Using sass 3.5.6
  Bundler: Using jekyll-sass-converter 1.5.2
  Bundler: Using ruby_dep 1.5.0
  Bundler: Using listen 3.1.5
  Bundler: Using jekyll-watch 2.0.0
  Bundler: Using kramdown 1.17.0
  Bundler: Using liquid 4.0.0
  Bundler: Using mercenary 0.3.6
  Bundler: Using pathutil 0.16.1
  Bundler: Using rouge 3.1.1
  Bundler: Using safe_yaml 1.0.4
  Bundler: Using jekyll 3.8.3
  Bundler: Using jekyll-feed 0.10.0
  Bundler: Using jekyll-seo-tag 2.5.0
  Bundler: Using minima 2.5.0
  Bundler: Bundle complete! 4 Gemfile dependencies, 29 gems now installed.
  Bundler: Use `bundle info [gemname]` to see where a bundled gem is installed.
New jekyll site installed in /Users/jarretbryan/Development/blog-post-site.

So once I jump into the created directory, the absolute basics of the static site have been created for me. The basic file directory looks like this:

The most important file here is the _config.yml, which written in YAML (YAML Ain't Markup Language, the most obnoxious recursive initialism ever) manages settings for the entire site or blog. YAML is just a data oriented language (not unlike JSON) that can manage data structures for web applications - but it's meant to be human friendly. In theory, you absolutely never have touch HTML or CSS for the rest of the site - it can all be managed through the this config file.

The default config files looks something like this:

and if I run

$jekyll serve --livereload

this will setup my server at localhost:4000.

$jekyll serve

sets up the server, and the livereload flag refreshes it every time an edit is made to any file that isn't the config. And the page itself at the localhost looks little like this:

And that's a basic static website! It's really that simple. And any content necessary content need can be modified through the config file.

The file structure allows you to build out the site for blog posts or other pages with static html layouts. The 'posts' default to markdown language, making it exceptionally easy to blog (just like here on dev.to!). Each blog post can just be another markdown page. And since the site is so lightweight, it can be hosted in its entirety on GitHub Pages! I believe it's actually the engine behind GitHub pages

Now the default theme, which is specified in _config.yml is called 'minima' and while it gets the job done, it's not that interesting. But there is no shortage of themes available (for free or to pay for), put together by other designers and developers, with default file structures and layouts. I did a quick cursory search, and found some, and they're all generally easy to install (provided they are well documented). More often than not, there is an extra line of code provided to add to your gemfile, and then just changing the theme in your YAML config file. Then run $bundle and suddenly your site is transformed!

Here are some examples of sites I created, and I touched little to no HTML in the process using themes:
Jekyll Material Theme

Swiss Theme

There's a lot of room for customization that I need to dive into. But Jekyll is so lightweight and flexible that it's really easy to build out the basics of what you need without getting bogged down in web app architecture.