From ArchWiki
Revision as of 16:38, 9 May 2011 by Thayer (Talk | contribs) (link to project page in the first sentence.)

Jump to: navigation, search

This template has only maintenance purposes. For linking to local translations please use interlanguage links, see Help:i18n#Interlanguage links.

Local languages: Català – Dansk – English – Español – Esperanto – Hrvatski – Indonesia – Italiano – Lietuviškai – Magyar – Nederlands – Norsk Bokmål – Polski – Português – Slovenský – Česky – Ελληνικά – Български – Русский – Српски – Українська – עברית – العربية – ไทย – 日本語 – 正體中文 – 简体中文 – 한국어

External languages (all articles in these languages should be moved to the external wiki): Deutsch – Français – Română – Suomi – Svenska – Tiếng Việt – Türkçe – فارسی

Template:Article summary start Template:Article summary text Template:Article summary heading Template:Article summary link Template:Article summary heading Template:Article summary wiki Template:Article summary end

Jekyll is "a simple, blog aware, static site generator. 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. This is also the engine behind GitHub Pages, which you can use to host your project’s page or blog right here from GitHub." [1]

Werner announced the release of Jekyll on his website on November 17, 2008.


Jekyll can be installed in Arch Linux with the RubyGems package manager or using the applicable packages in the Arch User Repository. Both methods require the Ruby package in [extra] to be installed.

RubyGems (Recommended)

The best way to install Jekyll is with RubyGems, a package manager for the Ruby programming language. RubyGems is installed alongside the Ruby package, which is located in the extra repository.

$ pacman -S ruby ruby-docs

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.

$ gem update --system

Then install Jekyll using the gem command.

$ gem install jekyll

Arch User Repository (Alternate)

Jekyll is also packaged independently of RubyGems in the AUR. Installation through AUR allows all packages to be maintained with Pacman rather than RubyGems.

Select a Markup Language

There are numerous different markup languages that are used to define text-to-HTML conversion tools.

Textile (Default)

Textile is the default markup language used by Jekyll.

Markdown (Alternate)

Markdown is a markup language and text-to-HTML conversion tool developed in Perl by John Gruber. A perl and a pyhton implementation of Markdown can be found in [community], while numerous other implementations are available in the AUR.

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 the AUR.

$ gem install rdiscount -s

Then add the following line to your Template:Filename.

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.


A default Jekyll directory tree looks like the following, where "." denotes the root directory of your Jeykll 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

The default file structure is available from Jekyll-Base on GitHub.

Note: Daniel McGraw has setup a more extensive default file structure on GitHub.

The Template:Filename 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 GitHub.

Once you have configured your Template:Filename to your liking you need to create the files that will be processed by Jekyll to generate the website.


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 Template:Filename requires a YAML Front Matter heading.

Create Index Layout

This is a basic template for your Template:Filename, which is used to render your website's index page. Template:File

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). Template:File

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). Template:File

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. Template:Filename). 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.


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 --server flag.

$ jekyll --server

It is recommended to define server options in your Template:Filename. The default will start a server on port 4000, which can be accessed in your web browser at localhost:4000.

External Links



Websites created with Jeykll by Arch Linux users. Further examples can be found on GitHub.