Jekyll

by Roman Zolotarev

Jekyll is a static site generator. It converts your plain text files to web pages. You can publish those pages with a single command or few clicks.

For all my cases the combination of a text editor and Jekyll replaces Microsoft Word and Google Docs. A nice thing about Jekyll: you can run Jekyll on your Mac without installing or configuring anything.

Markdown

Markdown is plain text with few markup tricks. The following block of text is all you need to know to be productive.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# Start a heading with one hash

## Start a subheading with two hashes

Separate paragraphs by empty lines. Wrap **bold text in double asterisks**,
_italic in underscores_, `monospace in backticks`.

[A link](https://www.romanzolotarev.com/).
![An image](https://www.romanzolotarev.com/avatar.jpg)

    -- Indent code block
    f x y = x + y

A list of items:

- Each item is on its line
- Lines start with `-`

An ordered list:

1. The first item
1. The second item starts with `1.` too

Recipe

Ingredients: terminal, Ruby, and a keyboard.

If you are on a Mac, both Ruby and Jekyll are most likely installed. In case you don’t have it yet just run:

gem install jekyll

Create a new directory for your project and run Jekyll

mkdir hello-world
cd hello-world
jekyll s

Create index.md file in your favorite text editor with the following content:

---
---
# Hello, World!

Those dashes separate front matter from Markdown. Jekyll needs a front matter if it is just empty.

Open a web browser

open http://127.0.0.1:4000

Edit index.md. Jekyll detects changes and regenerates all files. To see changes reload the web page.

Add more files if needed.

Publish

One of the simplest ways is to push your project to GitHub. It will take care of running Jekyll to regenerate all files on push.

You can also publish your site on any web server.

By default, Jekyll renders all files to _site directory. So just copy those files, and you are good to go. No dependencies. It is just a static HTML files.

Layout (optional)

When you have multiple files and want to style your web pages, it makes sense to create a layout.

How to add a new layout?

  1. Choose any layout name. E.g., default.

  2. Create a file default.html in _layouts directory.

  3. Add any HTML you want and include {{content}} tag.

Live reload (advanced)

When I am editing wordy pages or tweaking layouts I use jekyll-livereload plugin. It triggers a page reload on every file save.

jekyll-reload injects JavaScript code into <head>. So make sure you have <head> tag in your layout.

Here are three steps how to enable live reload:

  1. Install Bundler

    gem install bundler
    
  2. Add Gemfile:

    source 'https://rubygems.org'
    gem 'jekyll', group: :jekyll_plugins
    group 'jekyll_plugins' do
      gem 'jekyll-livereload'
    end
    
  3. Install and run

    bundle install
    bundle exec jekyll serve -L
    

If you are interested in technical writing and text editors, please subscribe to my newsletter.



Further reading

A random illustration