arch-wiki-md-repo
Version:
All arch-wiki articles in markdown format, updated every two days.
236 lines (160 loc) • 10.7 kB
Markdown
[Jekyll](https://jekyllrb.com/) is a simple, blog aware, static site generator written in Ruby and developed by GitHub co-founder [Tom Preston-Werner](http://tom.preston-werner.com/). 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](https://pages.github.com/).
Werner announced the release of Jekyll on his website on November 17, 2008\. [[1]](http://tom.preston-werner.com/2008/11/17/blogging-like-a-hacker.html)
## Contents
* [1 Installation](#Installation)
* [1.1 RubyGems (recommended)](#RubyGems_.28recommended.29)
* [1.2 AUR (alternate)](#AUR_.28alternate.29)
* [1.3 Rubygems binary repository](#Rubygems_binary_repository)
* [2 Select a markup language](#Select_a_markup_language)
* [2.1 Textile](#Textile)
* [2.2 Markdown](#Markdown)
* [3 Configuration](#Configuration)
* [4 Usage](#Usage)
* [4.1 Create index layout](#Create_index_layout)
* [4.2 Create general website layout](#Create_general_website_layout)
* [4.3 Create post layout](#Create_post_layout)
* [4.4 Creating a post](#Creating_a_post)
* [5 Test](#Test)
* [6 See also](#See_also)
## Installation
Jekyll can be installed in Arch Linux with the [RubyGems](https://en.wikipedia.org/wiki/RubyGems "wikipedia:RubyGems") package manager or using the applicable packages in the [AUR](/index.php/AUR "AUR"). Both methods require the Ruby package in the official repositories to be installed.
### RubyGems (recommended)
**Note:** RubyGems 1.8 and above are displaying [numerous uncritical warnings](https://github.com/rspec/rspec-core/issues/345).
The best way to install Jekyll is with [RubyGems](/index.php/Ruby#RubyGems "Ruby"), which is a package manager for the [Ruby](/index.php/Ruby "Ruby") programming language. RubyGems comes with the [ruby](https://www.archlinux.org/packages/?name=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](/index.php/Ruby#RubyGems "Ruby") page.
Before installing Jekyll make sure to update RubyGems.
```
$ gem update
```
Then install Jekyll using the `gem` command.
```
$ gem install jekyll
```
See [Ruby#RubyGems](/index.php/Ruby#RubyGems "Ruby") for more information on Gem management in Arch.
### AUR (alternate)
Alternately, [jekyll](https://aur.archlinux.org/packages/jekyll/) can be installed from the [AUR](/index.php/AUR "AUR").
### Rubygems binary repository
[Install](/index.php/Install "Install") *ruby-jekyll* from the unofficial [quarry](/index.php/Unofficial_user_repositories#quarry "Unofficial user repositories") 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](https://en.wikipedia.org/wiki/Textile_(markup_language) and [Markdown](http://daringfireball.net/projects/markdown/). Implementations of both are required as dependencies of Jekyll.
### Textile
[Textile](https://en.wikipedia.org/wiki/Textile_(markup_language) 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: [RedCloth Ticket 215](http://jgarber.lighthouseapp.com/projects/13054/tickets/215-native-ext-compilation-failure) and [219](http://jgarber.lighthouseapp.com/projects/13054/tickets/219-427-installation-issue-on-arch-linux-x64)).
It is recommended that you install the current stable version 4.2.2 by `gem install RedCloth --version 4.2.2`.
### Markdown
[Markdown](http://daringfireball.net/projects/markdown/) is a markup language and text-to-HTML conversion tool developed in Perl by [John Gruber](http://daringfireball.net/). A Perl and a Python implementation of Markdown can be found in the official repositories, while numerous other implementations are available in the [AUR](https://aur.archlinux.org/packages.php?O=0&K=markdown&do_Search=Go). The [default implementation](https://github.com/jekyll/jekyll/pull/1988) of Markdown in Jekyll is [kramdown](http://kramdown.gettalong.org/).
Additionally, it has been implemented in C as [Discount](http://www.pell.portland.or.us/~orc/Code/discount/) by [David Parsons](http://www.pell.portland.or.us/~orc/) and a Ruby extension was written by [Ryan Tomayko](http://tomayko.com/) as [RDiscount](https://github.com/rtomayko/rdiscount). You can install RDiscount with Rubygems as root **or** through [ruby-rdiscount](https://www.archlinux.org/packages/?name=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](http://daringfireball.net/projects/markdown/basics) presents an excellent introduction. Additionally, you can try out Markdown using Gruber's online [conversion tool](http://daringfireball.net/projects/markdown/dingus).
## 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](https://github.com/danielmcgraw/Jekyll-Base) page on GitHub.
**Note:** McGraw has also setup a more extensive default file structure on [GitHub](https://github.com/danielmcgraw/danielmcgraw.com.git).
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 [GitHub](https://github.com/mojombo/jekyll/wiki/Configuration).
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](http://jekyllrb.com/docs/variables/).
Additionally, each file besides `/_layouts/layout.html` requires a [YAML Front Matter](https://github.com/mojombo/jekyll/wiki/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](https://en.wikipedia.org/wiki/YAML "wikipedia:YAML") Front Matter blocks of each file (see: [Creating a Post](#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](https://en.wikipedia.org/wiki/YAML "wikipedia:YAML") Front Matter blocks of each file (see: [Creating a Post](#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](https://github.com/mojombo/jekyll/wiki/Permalinks).
## 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](https://en.wikipedia.org/wiki/YAML "wikipedia:YAML")
* [Textile](https://en.wikipedia.org/wiki/Textile_(markup_language) "wikipedia:Textile (markup language)")
* [Installation Tutorial](http://danielmcgraw.com/2011/04/14/The-Ultimate-Guide-To-Getting-Started-With-Jekyll-Part-1/) by Daniel McGraw
* [Configuration Tutorial](http://danielmcgraw.com/2011/04/18/The-Ultimate-Guide-To-Getting-Started-With-Jekyll-Part-2/) by Daniel McGraw
* [Jekyll vs. Hyde](http://philipm.at/2011/jekyll_vs_hyde.html) by Philip Mateescu
* Websites created with Jekyll can be found on [GitHub](https://github.com/mojombo/jekyll/wiki/sites)
* **Required software:**
* [http://redcloth.org](http://redcloth.org) - RedCloth
* [http://www.liquidmarkup.org/](http://www.liquidmarkup.org/) - Liquid
* [http://classifier.rubyforge.org/](http://classifier.rubyforge.org/) - Classifier
* [http://maruku.rubyforge.org/maruku.html](http://maruku.rubyforge.org/maruku.html) - Maruku
* [http://pygments.org/](http://pygments.org/) - Pygments
* [http://rubygems.org/gems/directory_watcher](http://rubygems.org/gems/directory_watcher) - Directory Watcher