{{Article summary text|Jekyll is a simple static site generator written in Ruby and developed by GitHub co-founder [http://tom.preston-werner.com/ Tom Preston-Werner]. This page provides a verbose tutorial to install and configure Jekyll for both inexperienced and advanced users.}}

+

[[ja:Jekyll]]

−

{{Article summary heading|Required software}}

+

[http://jekyllrb.com/ Jekyll] is a simple, blog aware, static site generator written in Ruby and developed by GitHub co-founder [http://tom.preston-werner.com/ 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 [http://pages.github.com/ GitHub Pages].

[http://jekyllrb.com/ 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 [http://pages.github.com/ GitHub Pages], which you can use to host your project’s page or blog right here from GitHub." [https://github.com/mojombo/jekyll/wikiGitHub]

+

Werner announced the release of Jekyll on [http://tom.preston-werner.com/2008/11/17/blogging-like-a-hacker.html his website] on November 17, 2008.

Werner announced the release of Jekyll on [http://tom.preston-werner.com/2008/11/17/blogging-like-a-hacker.html his website] on November 17, 2008.

== Installation ==

== Installation ==

−

Jekyll can be installed in Arch Linux with the [[Wikipedia:RubyGems|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)===

+

Jekyll can be installed in Arch Linux with the [[Wikipedia:RubyGems|RubyGems]] package manager or using the applicable packages in the [[AUR]]. Both methods require the Ruby package in the official repositories to be installed.

The best way to install Jekyll is with [[Ruby#RubyGems|RubyGems]], a package manager for the Ruby programming language. RubyGems is installed alongside the [[Ruby]] package, which is located in the [https://www.archlinux.org/packages/?sort=&repo=Extra&q=ruby&maintainer=&last_update=&flagged=&limit=50 extra repository].

The best way to install Jekyll is with [[Ruby#RubyGems|RubyGems]], a package manager for the [[Ruby]] programming language. RubyGems is installed alongside the {{Pkg|ruby}} package, which is located in the [[official repositories]].

Jekyll can then be installed for all users on the machine using the {{ic|gem}} command as root. Alternative installation methods are available on the [[Ruby#RubyGems|Ruby]] page.

Jekyll can then be installed for all users on the machine using the {{ic|gem}} command as root. Alternative installation methods are available on the [[Ruby#RubyGems|Ruby]] page.

Before installing Jekyll make sure to update RubyGems.

Before installing Jekyll make sure to update RubyGems.

−

# gem update --system

+

+

$ gem update

+

Then install Jekyll using the {{ic|gem}} command.

Then install Jekyll using the {{ic|gem}} command.

−

# gem install jekyll

−

=== Arch User Repository (Alternate) ===

+

$ gem install jekyll

−

Alternately, {{AUR|ruby-jekyll}} can be installed from the [[Arch User Repository]].

There are numerous different markup languages that are used to define text-to-HTML conversion tools. Jekyll has two defaults; [[Wikipedia:Textile (markup language)|Textile]] and [http://daringfireball.net/projects/markdown/ Markdown]. Implementations of both are required as dependencies of Jekyll.

There are numerous different markup languages that are used to define text-to-HTML conversion tools. Jekyll has two defaults; [[Wikipedia:Textile (markup language)|Textile]] and [http://daringfireball.net/projects/markdown/ Markdown]. Implementations of both are required as dependencies of Jekyll.

=== Textile ===

=== Textile ===

+

[[Wikipedia:Textile (markup language)|Textile]] is a markup language used by Jekyll.

[[Wikipedia:Textile (markup language)|Textile]] is a markup language used by Jekyll.

{{note|RedCloth, a module for using the Textile markup language in Ruby, fails to install with gcc 4.6.0 (see: [http://jgarber.lighthouseapp.com/projects/13054/tickets/215-native-ext-compilation-failure RedCloth Ticket 215] and [http://jgarber.lighthouseapp.com/projects/13054/tickets/219-427-installation-issue-on-arch-linux-x64 219]). It is recommended that you install the current stable version 4.2.2 by {{ic|gem install RedCloth --version 4.2.2}}.}}

{{note|RedCloth, a module for using the Textile markup language in Ruby, fails to install with gcc 4.6.0 (see: [http://jgarber.lighthouseapp.com/projects/13054/tickets/215-native-ext-compilation-failure RedCloth Ticket 215] and [http://jgarber.lighthouseapp.com/projects/13054/tickets/219-427-installation-issue-on-arch-linux-x64 219]). It is recommended that you install the current stable version 4.2.2 by {{ic|gem install RedCloth --version 4.2.2}}.}}

=== Markdown ===

=== Markdown ===

−

[http://daringfireball.net/projects/markdown/ Markdown] is a markup language and text-to-HTML conversion tool developed in Perl by [http://daringfireball.net/ John Gruber]. A Perl and a Python implementation of Markdown can be found in [community], while numerous other implementations are available in the [https://aur.archlinux.org/packages.php?O=0&K=markdown&do_Search=Go AUR]. The default implementation of Markdown in Jekyll is [http://maruku.rubyforge.org/index.html Maruku].

−

Additionally, it has been implemented in C as [http://www.pell.portland.or.us/~orc/Code/discount/ Discount] by [http://www.pell.portland.or.us/~orc/ David Parsons] and a Ruby extension was written by [http://tomayko.com/ Ryan Tomayko] as [https://github.com/rtomayko/rdiscount RDiscount]. You can install RDiscount with Rubygems as root '''or''' through the [https://aur.archlinux.org/packages.php?ID=34706 AUR].

+

[http://daringfireball.net/projects/markdown/ Markdown] is a markup language and text-to-HTML conversion tool developed in Perl by [http://daringfireball.net/ 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 [https://aur.archlinux.org/packages.php?O=0&K=markdown&do_Search=Go AUR]. The [https://github.com/jekyll/jekyll/pull/1988 default implementation] of Markdown in Jekyll is [http://kramdown.gettalong.org/ kramdown].

+

+

Additionally, it has been implemented in C as [http://www.pell.portland.or.us/~orc/Code/discount/ Discount] by [http://www.pell.portland.or.us/~orc/ David Parsons] and a Ruby extension was written by [http://tomayko.com/ Ryan Tomayko] as [https://github.com/rtomayko/rdiscount RDiscount]. You can install RDiscount with Rubygems as root '''or''' through {{Pkg|ruby-rdiscount}} package.

# gem install rdiscount -s <nowiki>http://gemcutter.org</nowiki>

# gem install rdiscount -s <nowiki>http://gemcutter.org</nowiki>

Then add the following line to your {{ic|_config.yml}}.

Then add the following line to your {{ic|_config.yml}}.

Line 50:

Line 55:

== Configuration ==

== Configuration ==

−

A default Jekyll directory tree looks like the following, where "." denotes the root directory of your Jeykll generated website.

+

+

A default Jekyll directory tree looks like the following, where "." denotes the root directory of your Jekyll generated website.

.

.

|-- _config.yml

|-- _config.yml

Line 70:

Line 76:

== Usage ==

== 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 [https://github.com/mojombo/jekyll/wiki/template-data GitHub].

+

+

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 [http://jekyllrb.com/docs/variables/ GitHub].

This is a basic template for your {{ic|index.html}}, which is used to render your website's index page.

This is a basic template for your {{ic|index.html}}, which is used to render your website's index page.

{{bc|<nowiki>

{{bc|<nowiki>

Line 95:

Line 103:

</nowiki>}}

</nowiki>}}

−

=== Create General Website Layout ===

+

=== Create general website layout ===

−

This is a basic template for your website's general layout. It will be referenced in the [[Wikipedia:YAML|YAML]] Front Matter blocks of each file (see: [[#Creating a Post|Creating a Post]]).

+

+

This is a basic template for your website's general layout. It will be referenced in the [[Wikipedia:YAML|YAML]] Front Matter blocks of each file (see: [[#Creating a post|Creating a Post]]).

{{hc|_layouts/layout.html|<nowiki>

{{hc|_layouts/layout.html|<nowiki>

<!DOCTYPE HTML>

<!DOCTYPE HTML>

Line 117:

Line 126:

</nowiki>}}

</nowiki>}}

−

=== Create Post Layout ===

+

=== Create post layout ===

−

This is a basic template for each of your posts. Again, this will be referenced in the [[Wikipedia:YAML|YAML]] Front Matter blocks of each file (see: [[#Creating a Post|Creating a Post]]).

+

+

This is a basic template for each of your posts. Again, this will be referenced in the [[Wikipedia:YAML|YAML]] Front Matter blocks of each file (see: [[#Creating a post|Creating a Post]]).

{{hc|_layouts/post.html|<nowiki>

{{hc|_layouts/post.html|<nowiki>

---

---

Line 133:

Line 143:

</nowiki>}}

</nowiki>}}

−

=== Creating a Post ===

+

=== Creating a post ===

+

The content of each blog post will be contained within a file inside of the {{ic|_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. {{ic|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 [https://github.com/mojombo/jekyll/wiki/Permalinks GitHub].

The content of each blog post will be contained within a file inside of the {{ic|_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. {{ic|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 [https://github.com/mojombo/jekyll/wiki/Permalinks GitHub].

== Test ==

== Test ==

−

To generate a static HTML website based on your Textile or Markdown documents run {{ic|jekyll}}. To simultaneously test the generated HTML website run Jekyll with the {{ic|--server}} flag.

+

+

To generate a static HTML website based on your Textile or Markdown documents run {{ic|jekyll}}. To simultaneously test the generated HTML website run Jekyll with the {{ic|--serve}} flag.

* Websites created with Jekyll can be found on [https://github.com/mojombo/jekyll/wiki/sites GitHub]

+

* '''Required software:

+

** http://redcloth.org - RedCloth

+

** http://www.liquidmarkup.org/ - Liquid

+

** http://classifier.rubyforge.org/ - Classifier

+

** http://maruku.rubyforge.org/maruku.html - Maruku

+

** http://pygments.org/ - Pygments

+

** http://rubygems.org/gems/directory_watcher - Directory Watcher

Latest revision as of 07:00, 20 July 2016

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.

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 official repositories.
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.

AUR (alternate)

Rubygems binary 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

Note: RedCloth, a module for using the Textile markup language in Ruby, fails to install with gcc 4.6.0 (see: RedCloth Ticket 215 and 219). 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.

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.

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.