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 is plain text with a few markup tricks. The following is all you need to know to be productive.
# 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`.
-- 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.
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
index.md file in your favorite text editor with the following
--- --- # 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
index.md. Jekyll detects changes and regenerates all files. To see
changes, reload the web page.
Add more files if needed.
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.
When you have multiple files and want to style your web pages, it makes sense to create a layout.
To add a new layout:
Choose any layout name, say,
Create a file
Add any HTML you want and include the
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
<head>. So make sure you
<head> tag in your layout.
Here’s how to enable live reload:
gem install bundler
source 'https://rubygems.org' gem 'jekyll', group: :jekyll_plugins group 'jekyll_plugins' do gem 'jekyll-livereload' end
Install and run
bundle install bundle exec jekyll serve -L