How to use Jekyll for documentation, blogs, or any kind of website. You may like it.

Jekyll

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

The combination of a text editor and Jekyll can replace Microsoft Word and Google Docs for every case I have come across. And the nice thing about Jekyll is that you can run it on your Mac without installing or configuring anything. But first, a quick introduction to Markdown.

Markdown

Markdown is plain text with a few markup tricks. The following 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 can start with `1.` too --- Markdown handles the numbering for you.

Recipe

Ingredients: terminal, Ruby, and a keyboard.

If you are on a Mac, both Ruby and Jekyll are most likely installed. If you don’t have Jekyll 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 an index.md file in your favorite text editor with the following content:

---
---
# Hello, World!

Those dashes separate the Jekyll front matter from your Markdown content. Jekyll needs front matter even if it’s 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 to publish 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 the _site directory, so just copy those files and you’re good to go. No dependencies, just static HTML files.

Layout (optional)

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

To add a new layout:

  1. Choose any layout name, say, default.

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

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

Live reload (advanced)

When I’m editing wordy pages or tweaking layouts I use the jekyll-livereload plugin. It triggers page reload every time I save a file.

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

Here’s 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
    

Further reading