Jekyll
Jekyll is a simple, blog aware, static site generator written in Ruby and developed by GitHub co-founder Tom Preston-Werner. It takes a template directory (representing the raw form of a website), runs it through Textile or Markdown and Liquid converters, and spits out a complete, static website suitable for serving with Apache or your favorite web server. It is the engine behind GitHub Pages.
Werner announced the release of Jekyll on his website on November 17, 2008. [1]
Installation
Jekyll can be installed in Arch Linux with the RubyGems package manager or using the applicable packages in the AUR. Both methods require the Ruby package in the official repositories to be installed.
RubyGems (recommended)
bundle-2.7 instead of bundle [3]).The best way to install Jekyll is with RubyGems, which is a package manager for the Ruby programming language.
RubyGems comes with the ruby package. Jekyll can then be installed for all users on the machine using the gem command as root.
Alternative installation methods are available on the Ruby page.
Before installing Jekyll make sure to update RubyGems (note that all the following gem commands install for your user only; please do not use gem as root = no sudo here).
$ gem update
Then install Jekyll and bundler using the gem command.
$ gem install jekyll bundler
and update
$ bundle update
See Ruby#RubyGems for more information on Gem management in Arch.
AUR (alternate)
Alternately, jekyllAUR can be installed from the AUR.
RubyGems binary repository
Install jekyll from the unofficial archlinuxcn repository.
Install ruby-jekyll from the unofficial quarry repository.
Select a markup language
There are numerous different markup languages that are used to define text-to-HTML conversion tools. Jekyll has two defaults; Textile and Markdown. Implementations of both are required as dependencies of Jekyll.
Textile
Textile is a markup language used by Jekyll.
It is recommended that you install the current stable version 4.2.2 by gem install RedCloth --version 4.2.2.
Markdown
Markdown is a markup language and text-to-HTML conversion tool developed in Perl by John Gruber. A Perl and a Python implementation of Markdown can be found in the official repositories, while numerous other implementations are available in the AUR. The default implementation of Markdown in Jekyll is kramdown.
Additionally, it has been implemented in C as Discount by David Parsons and a Ruby extension was written by Ryan Tomayko as RDiscount. You can install RDiscount with Rubygems as root or through ruby-rdiscount package.
# gem install rdiscount -s http://gemcutter.org
Then add the following line to your _config.yml.
markdown: rdiscount
If you are unfamiliar with Markdown, Gruber's website presents an excellent introduction. Additionally, you can try out Markdown using Gruber's online conversion tool.
Configuration
A default Jekyll directory tree looks like the following, where "." denotes the root directory of your Jekyll generated website.
. |-- _config.yml |-- _layouts | |-- default.html | `-- post.html |-- _posts | |-- 2010-02-13-early-userspace-in-arch-linux.textile | `-- 2011-05-29-arch-linux-usb-install-and-rescue-media.textile |-- _site `-- index.html
A default file structure is available from Daniel McGraw's Jekyll-Base page on GitHub.
The _config.yml file stores configuration data. It includes numerous configuration settings, which may also be called as flags. Full explanation and a default configuration can be found on
jekyllrb.
Once you have configured your _config.yml to your liking you need to create the files that will be processed by Jekyll to generate the website.
Usage
Next you need to create templates that Jekyll can process. These templates make use of the Liquid templating system to input data. For a full explanation check GitHub.
Additionally, each file besides /_layouts/layout.html requires a YAML Front Matter heading.
Create index layout
This is a basic template for your index.html, which is used to render your website's index page.
---
layout: layout
title: Jekyll Base
---
<div class="content">
<div class="related">
<ul>
{% for post in site.posts %}
<li>
<span>{{ post.date | date: "%B %e, %Y" }}</span> <a href="{{ post.url }}">{{ post.title }}</a>
</li>
{% endfor %}
</ul>
</div>
</div>
Create general website layout
This is a basic template for your website's general layout. It will be referenced in the YAML Front Matter blocks of each file (see: Creating a Post).
_layouts/layout.html
<!DOCTYPE HTML>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta name="author" content="Your Name" />
<title>{{ page.title }}</title>
</head>
<body>
<header>
<h1><a href="/">Jekyll Base</a></h1>
</header>
<section>
{{ content }}
</section>
</body>
</html>
Create post layout
This is a basic template for each of your posts. Again, this will be referenced in the YAML Front Matter blocks of each file (see: Creating a Post).
_layouts/post.html
---
layout: layout
title: sample title
---
<div class="content">
<div id="post">
<h1>{{ post.title }}</h1>
{{ content }}
</div>
</div>
Creating a post
The content of each blog post will be contained within a file inside of the _posts directorys.
To use the default naming convention each file should be saved with the year, month, date, post title
and end with the *.md or *.textile depending on the markup language used (e.g. 2010-02-13-early-userspace-in-arch-linux.textile).
The date defined in the filename will be used as the published date in the post. Additionally, the filename
will be used to generate the permalink (i.e. /categories/year/month/day/title.html).
To use an alternate permalink style or create your own review the explanation on GitHub.
Troubleshooting
gem-2.7 is missing various libraries
gem-2.7 might throw errors of missing libraries, like the following.
/usr/lib/ruby/2.7.0/rubygems/core_ext/kernel_require.rb:83:in `require': libruby.so.2.7: cannot open shared object file: No such file or directory - /home/<user>/.gem/ruby/2.7.0/extensions/x86_64-linux/2.7.0/psych-3.3.0/psych.so (LoadError)
To fix this, run
$ rm -r ~/.gem/ruby/2.7.0/ $ gem update
Test
To generate a static HTML website based on your Textile or Markdown documents run jekyll.
To simultaneously test the generated HTML website run Jekyll with the --serve flag.
$ jekyll serve
or if you want jekyll to watch for file changes
$ jekyll serve --watch
It is recommended to define server options in your _config.yml.
The default will start a server on port 4000, which can be accessed in your web browser at localhost:4000.
if you want to further test your work on other local machines use
$ jekyll serve --host=0.0.0.0
otherwise only the default localhost will work.
See also
- YAML
- Textile
- Installation Tutorial by Daniel McGraw
- Configuration Tutorial by Daniel McGraw
- Jekyll vs. Hyde by Philip Mateescu
- Websites created with Jekyll can be found on GitHub