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 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
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
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
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 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
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?
Choose any layout name. E.g.,
Create a file
Add any HTML you want and include
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.
<head>. So make sure you
<head> tag in your layout.
Here are three steps 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
If you are interested in technical writing and text editors, please subscribe to my newsletter.
- Jekyll Minimalist is a minimalist boilerplate.
- Jekyll is an official Jekyll website.
- GitHub Pages provides free hosting for Jekyll sites.