github/jekyll
1
1
Fork 0
mirror of https://github.com/jekyll/jekyll.git synced 2026-04-28 03:01:03 -04:00
Code Issues Packages Projects Releases Wiki Activity

Merge benbalter:docs-pages #985

Browse Source
This commit is contained in:
Parker Moore
2013-05-10 22:11:36 +02:00
parent 65a1b33f6c e1f04968e8
commit 628f8280d0
24 changed files with 21 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

305
site/docs/configuration.md Normal file
View File

@@ -0,0 +1,305 @@
---
layout: docs
title: Configuration
prev_section: structure
next_section: frontmatter
permalink: /docs/configuration/
---
Jekyll allows you to concoct your sites in any way you can dream up, and it’s
thanks to the powerful and flexible configuration options that this is possible.
These options can either be specified in a `_config.yml` file placed in your
site’s root directory, or can be specified as flags for the `jekyll` executable
in the terminal.
## Configuration Settings
### Global Configuration
The table below lists the available settings for Jekyll, and the various <code
class="option">options</code> (specified in the configuration file) and <code
class="flag">flags</code> (specified on the command-line) that control them.
<div class="mobile-side-scroller">
<table>
<thead>
<tr>
<th>Setting</th>
<th>
<span class="option">Options</span> and <span class="flag">Flags</span>
</th>
</tr>
</thead>
<tbody>
<tr class='setting'>
<td>
<p class='name'><strong>Site Source</strong></p>
<p class='description'>Change the directory where Jekyll will read files</p>
</td>
<td class="align-center">
<p><code class="option">source: DIR</code></p>
<p><code class="flag">-s, --source DIR</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Site Destination</strong></p>
<p class='description'>Change the directory where Jekyll will write files</p>
</td>
<td class="align-center">
<p><code class="option">destination: DIR</code></p>
<p><code class="flag">-d, --destination DIR</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Safe</strong></p>
<p class='description'>Disable <a href="../plugins">custom plugins</a>.</p>
</td>
<td class="align-center">
<p><code class="option">safe: BOOL</code></p>
<p><code class="flag">--safe</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Exclude</strong></p>
<p class="description">Exclude directories and/or files from the conversion</p>
</td>
<td class='align-center'>
<p><code class="option">exclude: [DIR, FILE, ...]</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Include</strong></p>
<p class="description">
Force inclusion of directories and/or files in the conversion.
<code>.htaccess</code> is a good example since dotfiles are excluded
by default.
</p>
</td>
<td class='align-center'>
<p><code class="option">include: [DIR, FILE, ...]</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Time Zone</strong></p>
<p class="description">
Set the time zone for site generation. This sets the <code>TZ</code>
environment variable, which Ruby uses to handle time and date
creation and manipulation. Any entry from the
<a href="http://en.wikipedia.org/wiki/Tz_database">IANA Time Zone
Database</a> is valid, e.g. <code>America/New_York</code>. The default
is the local time zone, as set by your operating system.
</p>
</td>
<td class='align-center'>
<p><code class="option">timezone: TIMEZONE</code></p>
</td>
</tr>
</tbody>
</table>
</div>
### Build Command Options
<div class="mobile-side-scroller">
<table>
<thead>
<tr>
<th>Setting</th>
<th><span class="option">Options</span> and <span class="flag">Flags</span></th>
</tr>
</thead>
<tbody>
<tr class='setting'>
<td>
<p class='name'><strong>Regeneration</strong></p>
<p class='description'>Enable auto-regeneration of the site when files are modified.</p>
</td>
<td class="align-center">
<p><code class="flag">-w, --watch</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Configuration</strong></p>
<p class="description">Specify a config file. Overrides settings in <code>_config.yml</code></p>
</td>
<td class='align-center'>
<p><code class="flag">--config FILE</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Drafts</strong></p>
<p class="description">Process and render draft posts.</p>
</td>
<td class='align-center'>
<p><code class="flag">--drafts</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Future</strong></p>
<p class="description">Publish posts with a future date.</p>
</td>
<td class='align-center'>
<p><code class="option">future: BOOL</code></p>
<p><code class="flag">--future</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>LSI</strong></p>
<p class="description">Produce an index for related posts.</p>
</td>
<td class='align-center'>
<p><code class="option">lsi: BOOL</code></p>
<p><code class="flag">--lsi</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Limit Posts</strong></p>
<p class="description">Limit the number of posts to parse and publish.</p>
</td>
<td class='align-center'>
<p><code class="option">limit_posts: NUM</code></p>
<p><code class="flag">--limit_posts NUM</code></p>
</td>
</tr>
</tbody>
</table>
</div>
### Serve Command Options
In addition to the options below, the `serve` sub-command can accept any of the options
for the `build` sub-command, which are then applied to the site build which occurs right
before your site is served.
<div class="mobile-side-scroller">
<table>
<thead>
<tr>
<th>Setting</th>
<th><span class="option">Options</span> and <span class="flag">Flags</span></th>
</tr>
</thead>
<tbody>
<tr class='setting'>
<td>
<p class='name'><strong>Local Server Port</strong></p>
<p class='description'>Listen on the given port.</p>
</td>
<td class="align-center">
<p><code class="option">port: PORT</code></p>
<p><code class="flag">--port PORT</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Local Server Hostname</strong></p>
<p class='description'>Listen at the given hostname.</p>
</td>
<td class="align-center">
<p><code class="option">host: HOSTNAME</code></p>
<p><code class="flag">--host HOSTNAME</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Base URL</strong></p>
<p class='description'>Serve the website from the given base URL</p>
</td>
<td class="align-center">
<p><code class="option">baseurl: URL</code></p>
<p><code class="flag">--baseurl URL</code></p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="note warning">
<h5>Do not use tabs in configuration files</h5>
<p>
This will either lead to parsing errors, or Jekyll will revert to the
default settings. Use spaces instead.
</p>
</div>
## Default Configuration
Jekyll runs with the following configuration options by default. Unless
alternative settings for these options are explicitly specified in the
configuration file or on the command-line, Jekyll will run using these options.
{% highlight yaml %}
source: .
destination: ./_site
plugins: ./_plugins
layouts: ./_layouts
include: ['.htaccess']
exclude: []
keep_files: ['.git','.svn']
timezone: nil
future: true
show_drafts: nil
limit_posts: 0
pygments: true
permalink: date
paginate_path: 'page:num'
markdown: maruku
markdown_ext: markdown,mkd,mkdn,md
textile_ext: textile
excerpt_separator: "\n\n"
safe: false
watch: false # deprecated
server: false # deprecated
host: 0.0.0.0
port: 4000
baseurl: /
url: http://localhost:4000
lsi: false
maruku:
use_tex: false
use_divs: false
png_engine: blahtex
png_dir: images/latex
png_url: /images/latex
rdiscount:
extensions: []
redcarpet:
extensions: []
kramdown:
auto_ids: true
footnote_nr: 1
entity_output: as_char
toc_levels: 1..6
smart_quotes: lsquo,rsquo,ldquo,rdquo
use_coderay: false
coderay:
coderay_wrap: div
coderay_line_numbers: inline
coderay_line_numbers_start: 1
coderay_tab_width: 4
coderay_bold_every: 10
coderay_css: style
redcloth:
hard_breaks: true
{% endhighlight %}

104
site/docs/contributing.md Normal file
View File

@@ -0,0 +1,104 @@
---
layout: docs
title: Contributing
prev_section: deployment-methods
next_section: troubleshooting
permalink: /docs/contributing/
---
So you've got an awesome idea to throw into Jekyll. Great! Please keep the
following in mind:
* If you're creating a small fix or patch to an existing feature, just a simple
test will do. Please stay in the confines of the current test suite and use
[Shoulda](http://github.com/thoughtbot/shoulda/tree/master) and
[RR](http://github.com/btakita/rr/tree/master).
* If it's a brand new feature, make sure to create a new
[Cucumber](https://github.com/cucumber/cucumber/) feature and reuse steps
where appropriate. Also, whipping up some documentation in your fork's `site`
directory would be appreciated, and once merged it will also appear in
the next update of the main site.
* If your contribution adds or changes any Jekyll behavior, make sure to update
the documentation. It lives in `site/_posts`. If the docs are missing
information, please feel free to add it in. Great docs make a great project!
* Please follow the [GitHub Ruby Styleguide](https://github.com/styleguide/ruby)
when modifying Ruby code.
<div class="note warning">
<h5>Contributions will not be accepted without tests</h5>
<p>
If you’re creating a small fix or patch to an existing feature, just
a simple test will do.
</p>
</div>
Test Dependencies
-----------------
To run the test suite and build the gem you'll need to install Jekyll's
dependencies. Jekyll uses Bundler, so a quick run of the `bundle` command and
you're all set!
{% highlight bash %}
$ bundle
{% endhighlight %}
Before you start, run the tests and make sure that they pass (to confirm your
environment is configured properly):
{% highlight bash %}
$ rake test
$ rake features
{% endhighlight %}
Workflow
--------
Here's the most direct way to get your work merged into the project:
* Fork the project.
* Clone down your fork:
{% highlight bash %}
git clone git://github.com/<username>/jekyll.git
{% endhighlight %}
* Create a topic branch to contain your change:
{% highlight bash %}
git checkout -b my_awesome_feature
{% endhighlight %}
* Hack away, add tests. Not necessarily in that order.
* Make sure everything still passes by running `rake`.
* If necessary, rebase your commits into logical chunks, without errors.
* Push the branch up:
{% highlight bash %}
git push origin my_awesome_feature
{% endhighlight %}
* Create a pull request against mojombo/jekyll and describe what your change
does and the why you think it should be merged.
Gotchas
-------
* If you want to bump the gem version, please put that in a separate commit.
This way, the maintainers can control when the gem gets released.
* Try to keep your patch(es) based from the latest commit on mojombo/jekyll.
The easier it is to apply your work, the less work the maintainers have to do,
which is always a good thing.
* Please don't tag your GitHub issue with \[fix\], \[feature\], etc. The maintainers
actively read the issues and will label it once they come across it.
<div class="note">
<h5>Let us know what could be better!</h5>
<p>
Both using and hacking on Jekyll should be fun, simple, and easy, so if for
some reason you find it’s a pain, please <a
href="https://github.com/mojombo/jekyll/issues/new">create an issue</a> on
GitHub describing your experience so we can make it better.
</p>
</div>

109
site/docs/deployment-methods.md Normal file
View File

@@ -0,0 +1,109 @@
---
layout: docs
title: Deployment methods
prev_section: github-pages
next_section: contributing
permalink: /docs/deployment-methods/
---
Sites built using Jekyll can be deployed in a large number of ways due to the static nature of the generated output. A few of the most common deployment techniques are described below.
## Web hosting providers (FTP)
Just about any traditional web hosting provider will let you upload files to their servers over FTP. To upload a Jekyll site to a web host using FTP, simply run the `jekyll` command and copy the generated `_site` folder to the root folder of your hosting account. This is most likely to be the `httpdocs` or `public_html` folder on most hosting providers.
### FTP using Glynn
There is a project called [Glynn](https://github.com/dmathieu/glynn), which lets you easily generate your Jekyll powered website’s static files and
send them to your host through FTP.
## Self-managed web server
If you have direct access yourself to the deployment web server yourself, the process is essentially the same, except you might have other methods available to you (such as `scp`, or even direct filesystem access) for transferring the files. Just remember to make sure the contents of the generated `_site` folder get placed in the appropriate web root directory for your web server.
## Automated methods
There are also a number of ways to easily automate the deployment of a Jekyll site. If you’ve got another method that isn’t listed below, we’d love it if you [contributed](../contributing) so that everyone else can benefit too.
### Git post-update hook
If you store your jekyll site in [Git](http://git-scm.com/) (you are using version control, right?), it’s pretty easy to automate the
deployment process by setting up a post-update hook in your Git
repository, [like
this](http://web.archive.org/web/20091223025644/http://www.taknado.com/en/2009/03/26/deploying-a-jekyll-generated-site/).
### Git post-receive hook
To have a remote server handle the deploy for you every time you push changes using Git, you can create a user account which has all the public keys that are authorized to deploy in its `authorized_keys` file. With that in place, setting up the post-receive hook is done as follows:
{% highlight bash %}
laptop$ ssh deployer@myserver.com
server$ mkdir myrepo.git
server$ cd myrepo.git
server$ git --bare init
server$ cp hooks/post-receive.sample hooks/post-receive
server$ mkdir /var/www/myrepo
{% endhighlight %}
Next, add the following lines to hooks/post-receive and be sure Jekyll is
installed on the server:
{% highlight bash %}
GIT_REPO=$HOME/myrepo.git
TMP_GIT_CLONE=$HOME/tmp/myrepo
PUBLIC_WWW=/var/www/myrepo
git clone $GIT_REPO $TMP_GIT_CLONE
jekyll build $TMP_GIT_CLONE $PUBLIC_WWW
rm -Rf $TMP_GIT_CLONE
exit
{% endhighlight %}
Finally, run the following command on any users laptop that needs to be able to
deploy using this hook:
{% highlight bash %}
laptops$ git remote add deploy deployer@myserver.com:~/myrepo.git
{% endhighlight %}
Deploying is now as easy as telling nginx or Apache to look at
`/var/www/myrepo` and running the following:
{% highlight bash %}
laptops$ git push deploy master
{% endhighlight %}
### Rake
Another way to deploy your Jekyll site is to use [Rake](https://github.com/jimweirich/rake), [HighLine](https://github.com/JEG2/highline), and
[Net::SSH](http://net-ssh.rubyforge.org/). A more complex example of deploying Jekyll with Rake that deals with multiple branches can be found in [Git Ready](https://github.com/gitready/gitready/blob/en/Rakefile).
### rsync
Once you’ve generated the `_site` directory, you can easily rsync it using a `tasks/deploy` shell script similar to [this deploy script here](http://github.com/henrik/henrik.nyh.se/blob/master/tasks/deploy). You’d obviously need to change the values to reflect your site’s details. There is even [a matching TextMate command](http://gist.github.com/214959) that will help you run
this script from within Textmate.
## Rack-Jekyll
[Rack-Jekyll](http://github.com/bry4n/rack-jekyll/) is an easy way to deploy your site on any Rack server such as Amazon EC2, Slicehost, Heroku, and so forth. It also can run with [shotgun](http://github.com/rtomakyo/shotgun/), [rackup](http://github.com/rack/rack), [mongrel](http://github.com/mongrel/mongrel), [unicorn](http://github.com/defunkt/unicorn/), and [others](https://github.com/adaoraul/rack-jekyll#readme).
Read [this post](http://blog.crowdint.com/2010/08/02/instant-blog-using-jekyll-and-heroku.html) on how to deploy to Heroku using Rack-Jekyll.
## Jekyll-Admin for Rails
If you want to maintain Jekyll inside your existing Rails app, [Jekyll-Admin](http://github.com/zkarpinski/Jekyll-Admin) contains drop in code to make this possible. See Jekyll-Admin’s [README](http://github.com/zkarpinski/Jekyll-Admin/blob/master/README) for more details.
## Amazon S3
If you want to host your site in Amazon S3, you can do so with
[jekyll-s3](https://github.com/laurilehmijoki/jekyll-s3) application. It will
push your site to Amazon S3 where it can be served like any web server,
dynamically scaling to almost unlimited traffic. This approach has the
benefit of being about the cheapest hosting option available for
low-volume blogs as you only pay for what you use.
<div class="note">
<h5>ProTip™: Use GitHub Pages for zero-hassle Jekyll hosting</h5>
<p>GitHub Pages are powered by Jekyll behind the scenes, so if you’re looking for a zero-hassle, zero-cost solution, GitHub Pages are a great way to <a href="../github-pages">host your Jekyll-powered website for free</a>.</p>
</div>

115
site/docs/extras.md Normal file
View File

@@ -0,0 +1,115 @@
---
layout: docs
title: Extras
prev_section: plugins
next_section: github-pages
permalink: /docs/extras/
---
There are a number of (optional) extra features that Jekyll supports that you
may want to install, depending on how you plan to use Jekyll.
## Pygments
If you want syntax highlighting via the `{% raw %}{% highlight %}{% endraw %}`
tag in your posts, you’ll need to install [Pygments](http://pygments.org/).
### Installing Pygments on OSX
Mac OS X (Leopard onwards) comes preinstalled with Python, so on just about any
OS X machine you can install Pygments simply by running:
{% highlight bash %}
$ sudo easy_install Pygments
{% endhighlight %}
#### Installing Pygments using Homebrew
Alternatively, you can install Pygments with
[Homebrew](http://mxcl.github.com/homebrew/), an excellent package manager for
OS X:
{% highlight bash %}
$ brew install python
# export PATH="/usr/local/share/python:${PATH}"
$ pip install pygments
{% endhighlight %}
<div class="note">
<h5>Homebrew's executable paths</h5>
<p>
Homebrew doesn’t symlink the executables for you. For the Homebrew default
Cellar location and Python 2.7, be sure to add `/usr/local/share/python` to
your `PATH`. For more information, check out
<a href="https://github.com/mxcl/homebrew/wiki/Homebrew-and-Python">the
Homebrew wiki</a>.
</p>
</div>
#### Installing Pygments using MacPorts
If you use MacPorts, you can install Pygments by running:
{% highlight bash %}
$ sudo port install python25 py25-pygments
{% endhighlight %}
Seriously though, you should check out
[Homebrew](http://mxcl.github.com/homebrew/)—it’s awesome.
### Installing Pygments on Arch Linux
You can install Pygments using the pacman package manager as follows:
{% highlight bash %}
$ sudo pacman -S python-pygments
{% endhighlight %}
Or to use python2 for Pygments:
{% highlight bash %}
$ sudo pacman -S python2-pygments
{% endhighlight %}
### Installing Pygments on Ubuntu and Debian
{% highlight bash %}
$ sudo apt-get install python-pygments
{% endhighlight %}
### Installing Pygments on RedHat, Fedora, and CentOS
{% highlight bash %}
$ sudo yum install python-pygments
{% endhighlight %}
### Installing Pygments on Gentoo
{% highlight bash %}
$ sudo emerge -av dev-python/pygments
{% endhighlight %}
## LaTeX Support
Maruku comes with optional support for LaTeX to PNG rendering via blahtex
(Version 0.6) which must be in your `$PATH` along with `dvips`. If you need
Maruku to not assume a fixed location for `dvips`, check out [Remi’s Maruku
fork](http://github.com/remi/maruku).
## RDiscount
If you prefer to use [RDiscount](http://github.com/rtomayko/rdiscount) instead
of [Maruku](http://maruku.rubyforge.org/) for markdown, just make sure you have
it installed:
{% highlight bash %}
$ sudo gem install rdiscount
{% endhighlight %}
And then specify RDiscount as the Markdown engine in your `_config.yml` file to
have Jekyll run with that option.
{% highlight bash %}
# In _config.yml
markdown: rdiscount
{% endhighlight %}

170
site/docs/frontmatter.md Normal file
View File

@@ -0,0 +1,170 @@
---
layout: docs
title: Front-matter
prev_section: configuration
next_section: posts
permalink: /docs/frontmatter/
---
The front-matter is where Jekyll starts to get really cool. Any file that
contains a [YAML](http://yaml.org/) front matter block will be processed by
Jekyll as a special file. The front matter must be the first thing in the file
and must take the form of valid YAML set between triple-dashed lines. Here is a
basic example:
{% highlight yaml %}
---
layout: post
title: Blogging Like a Hacker
---
{% endhighlight %}
Between these triple-dashed lines, you can set predefined variables (see below
for a reference) or even create custom ones of your own. These variables will
then be available to you to access using Liquid tags both further down in the
file and also in any layouts or includes that the page or post in question
relies on.
<div class="note warning">
<h5>UTF-8 Character Encoding Warning</h5>
<p>
If you use UTF-8 encoding, make sure that no <code>BOM</code> header
characters exist in your files or very, very bad things will happen to
Jekyll. This is especially relevant if you’re running Jekyll on Windows.
</p>
</div>
## Predefined Global Variables
There are a number of predefined global variables that you can set in the
front-matter of a page or post.
<div class="mobile-side-scroller">
<table>
<thead>
<tr>
<th>Variable</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p><code>layout</code></p>
</td>
<td>
<p>
If set, this specifies the layout file to use. Use the layout file
name without the file extension. Layout files must be placed in the
<code>_layouts</code> directory.
</p>
</td>
</tr>
<tr>
<td>
<p><code>permalink</code></p>
</td>
<td>
<p>
If you need your processed blog post URLs to be something other than
the default <code>/year/month/day/title.html</code> then you can set
this variable and it will be used as the final URL.
</p>
</td>
</tr>
<tr>
<td>
<p><code>published</code></p>
</td>
<td>
<p>
Set to false if you don’t want a specific post to show up when the
site is generated.
</p>
</td>
</tr>
<tr>
<td>
<p style="margin-bottom: 5px;"><code>category</code></p>
<p><code>categories</code></p>
</td>
<td>
<p>
Instead of placing posts inside of folders, you can specify one or
more categories that the post belongs to. When the site is generated
the post will act as though it had been set with these categories
normally. Categories (plural key) can be specified as a <a
href="http://en.wikipedia.org/wiki/YAML#Lists">YAML list</a> or a
space-separated string.
</p>
</td>
</tr>
<tr>
<td>
<p><code>tags</code></p>
</td>
<td>
<p>
Similar to categories, one or multiple tags can be added to a post.
Also like categories, tags can be specified as a YAML list or a space-
separated string.
</p>
</td>
</tr>
</tbody>
</table>
</div>
## Custom Variables
Any variables in the front matter that are not predefined are mixed into the
data that is sent to the Liquid templating engine during the conversion. For
instance, if you set a title, you can use that in your layout to set the page
title:
{% highlight html %}
<!DOCTYPE HTML>
<html>
<head>
<title>{% raw %}{{ page.title }}{% endraw %}</title>
</head>
<body>
...
{% endhighlight %}
## Predefined Variables for Posts
These are available out-of-the-box to be used in the front-matter for a post.
<div class="mobile-side-scroller">
<table>
<thead>
<tr>
<th>Variable</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p><code>date</code></p>
</td>
<td>
<p>
A date here overrides the date from the name of the post. This can be
used to ensure correct sorting of posts.
</p>
</td>
</tr>
</tbody>
</table>
</div>

66
site/docs/github-pages.md Normal file
View File

@@ -0,0 +1,66 @@
---
layout: docs
title: GitHub Pages
prev_section: extras
next_section: deployment-methods
permalink: /docs/github-pages/
---
[GitHub Pages](http://pages.github.com) are public web pages for users,
organizations, and repositories, that are freely hosted on GitHub's
[github.io]() domain or on a custom domain name of your choice. GitHub Pages are
powered by Jekyll behind the scenes, so in addition to supporting regular HTML
content, they’re also a great way to host your Jekyll-powered website for free.
## Deploying Jekyll to GitHub Pages
GitHub Pages work by looking at certain branches of repositories on GitHub.
There are two basic types available: user/organization pages and project pages.
The way to deploy these two types of sites are nearly identical, except for a
few minor details.
### User and Organization Pages
User and organization pages live in a special GitHub repository dedicated to
only the GitHub Pages files. This repository must be named after the account
name. For example, [@mojombo’s user page
repository](https://github.com/mojombo/mojombo.github.io) has the name
`mojombo.github.io`.
Content from the `master` branch of your repository will be used to build and
publish the GitHub Pages site, so make sure your Jekyll site is stored there.
<div class="note info">
<h5>Custom domains do not affect repository names</h5>
<p>
GitHub Pages are initially configured to live under the
<code>username.github.io</code> subdomain, which is why repositories must
be named this way <strong>even if a custom domain is being used</strong>.
</p>
</div>
### Project Pages
Unlike user and organization Pages, Project Pages are kept in the same
repository as the project they are for, except that the website content is
stored in a specially named `gh-pages` branch. The content of this branch will
be rendered using Jekyll, and the output will become available under a subpath
of your user pages subdomain, such as `username.github.io/project` (unless a
custom domain is specified—see below).
The Jekyll project repository itself is a perfect example of this branch
structure—the [master branch](https://github.com/mojombo/jekyll) contains the
actual software project for Jekyll, however the Jekyll website (that you’re
looking at right now) is contained in the [gh-pages
branch](https://github.com/mojombo/jekyll/tree/gh-pages) of the same repository.
<div class="note">
<h5>GitHub Pages Documentation, Help, and Support</h5>
<p>
For more information about what you can do with GitHub Pages, as well as for
troubleshooting guides, you should check out <a
href="https://help.github.com/categories/20/articles">GitHub’s Pages Help
section</a>. If all else fails, you should contact <a
href="https://github.com/contact">GitHub Support</a>.
</p>
</div>

9
site/docs/heroku.md Normal file
View File

@@ -0,0 +1,9 @@
---
layout: docs
title: Heroku
prev_section: github-pages
next_section: manual-deployment
permalink: /docs/heroku/
---
Move along, people. Nothing to see here.

11
site/docs/index.html
View File

@@ -1,11 +0,0 @@
<!DOCTYPE HTML>
<html lang="en-US">
<head>
<meta charset="UTF-8">
<meta http-equiv="refresh" content="0;url=home">
<title>Jekyll</title>
</head>
<body style="background: #333;">
</body>
</html>

67
site/docs/index.md Normal file
View File

@@ -0,0 +1,67 @@
---
layout: docs
title: Welcome
next_section: installation
---
This site aims to be a comprehensive guide to Jekyll. We’ll cover topics such
as getting your site up and running, creating and managing your content,
customizing the way your site works and looks, deploying to various
environments, and give you some advice on participating in the future
development of Jekyll itself.
## So what is Jekyll, exactly?
Jekyll is a simple, blog-aware, static site generator. It takes a template
directory containing raw text files in various formats, runs it through
[Markdown](http://daringfireball.net/projects/markdown/) (or
[Textile](http://textile.sitemonks.com/)) and
[Liquid](http://wiki.shopify.com/Liquid)
converters, and spits out a complete, ready-to-publish static website suitable
for serving with your favorite web server. Jekyll also happens to be the engine
behind [GitHub Pages](http://pages.github.com), which means you can use Jekyll
to host your project’s page, blog, or website from GitHub’s servers **for
free**.
## Quick-start guide
For the impatient, here's how to get a boilerplate Jekyll site up and running.
{% highlight bash %}
~ $ gem install jekyll
~ $ jekyll new myblog
~ $ cd myblog
~/myblog $ jekyll serve
# => Now browse to http://localhost:4000
{% endhighlight %}
That's nothing, though. The real magic happens when you start creating blog
posts, using the front-matter to control templates and layouts, and taking
advantage of all the awesome configuration options Jekyll makes available.
## ProTips™, Notes, and Warnings
Throughout this guide there are a number of small-but-handy pieces of
information that can make using Jekyll easier, more interesting, and less
hazardous. Here’s what to look out for.
<div class="note">
<h5>ProTips™ help you get more from Jekyll</h5>
<p>These are tips and tricks that will help you be a Jekyll wizard!</p>
</div>
<div class="note info">
<h5>Notes are handy pieces of information</h5>
<p>These are for the extra tidbits sometimes necessary to understand
Jekyll.</p>
</div>
<div class="note warning">
<h5>Warnings help you not blow things up</h5>
<p>Be aware of these messages if you wish to avoid certain death.</p>
</div>
If you come across anything along the way that we haven’t covered, or if you
know of a tip you think others would find handy, please [file an
issue](https://github.com/mojombo/jekyll/issues/new) and we’ll see about
including it in this guide.

67
site/docs/installation.md Normal file
View File

@@ -0,0 +1,67 @@
---
layout: docs
title: Installation
prev_section: home
next_section: usage
permalink: /docs/installation/
---
Getting Jekyll installed and ready-to-go should only take a few minutes. If it
ever becomes a pain in the ass, please [file an
issue](https://github.com/mojombo/jekyll/issues/new) (or submit a pull request)
describing the issue you encountered and how we might make the process easier.
### Requirements
Installing Jekyll is easy and straight-forward, but there are a few requirements
you’ll need to make sure your system has before you start.
- [Ruby](http://www.ruby-lang.org/en/downloads/)
- [RubyGems](http://rubygems.org/pages/download)
- Linux, Unix, or Mac OS X
<div class="note info">
<h5>Running Jekyll on Windows</h5>
<p>
It is possible to get
<a href="http://www.madhur.co.in/blog/2011/09/01/runningjekyllwindows.html">
Jekyll running on Windows</a>, but the official documentation does not
support installation on Windows platforms.
</p>
</div>
## Install with RubyGems
The best way to install Jekyll is via
[RubyGems](http://docs.rubygems.org/read/chapter/3). At the terminal prompt,
simply run the following command to install Jekyll:
{% highlight bash %}
$ gem install jekyll
{% endhighlight %}
All of Jekyll’s gem dependencies are automatically installed by the above
command, so you won’t have to worry about them at all. If you have problems
installing Jekyll, check out the [troubleshooting](../troubleshooting) page or
[report an issue](https://github.com/mojombo/jekyll/issues/new) so the Jekyll
community can improve the experience for everyone.
## Optional Extras
There are a number of (optional) extra features that Jekyll supports that you
may want to install, depending on how you plan to use Jekyll. These extras
include syntax highlighting of code snippets using
[Pygments](http://pygments.org/), LaTeX support, and the use of alternative
content rendering engines. Check out [the extras page](../extras) for more
information.
<div class="note">
<h5>ProTip™: Enable Syntax Highlighting</h5>
<p>
If you’re the kind of person who is using Jekyll, then chances are you’ll
want to enable syntax highlighting using Pygments. You should really
<a href="../extras">check out how to do that</a> before you go any further.
</p>
</div>
Now that you’ve got everything installed, let’s get to work!

246
site/docs/migrations.md Normal file
View File

@@ -0,0 +1,246 @@
---
layout: docs
title: Blog migrations
prev_section: variables
next_section: templates
permalink: /docs/migrations/
---
If you’re switching to Jekyll from another blogging system, Jekyll’s importers
can help you with the move. Most methods listed on this page require read access
to the database from your old system to generate posts for Jekyll. Each method
generates `.markdown` posts in the `_posts` directory based on the entries in
the foreign system.
## Preparing for migrations
Because the importers have many of their own dependencies, they are made
available via a separate gem called `jekyll-import`. To use them, all you need
to do is install the gem, and they will become available as part of Jekyll's
standard command line interface.
{% highlight bash %}
$ gem install jekyll-import
{% endhighlight %}
You should now be all set to run the importers below. If you ever get stuck, you
can see help for each importer:
{% highlight bash %}
$ jekyll help import # => See list of importers
$ jekyll help import IMPORTER # => See importer specific help
{% endhighlight %}
Where IMPORTER is the name of the specific importer.
<div class="note info">
<h5>Note: Always double-check migrated content</h5>
<p>
Importers may not distinguish between published or private posts, so
you should always check that the content Jekyll generates for you appears as
you intended.
</p>
</div>
<!-- TODO all these need to be fixed -->
## WordPress
### Wordpress export files
If hpricot is not already installed, you will need to run `gem install hpricot`.
Next, export your blog using the Wordpress export utility. Assuming that the
exported file is saved as `wordpress.xml`, here is the command you need to run:
{% highlight bash %}
$ ruby -rubygems -e 'require "jekyll/migrators/wordpressdotcom";
Jekyll::WordpressDotCom.process("wordpress.xml")'
{% endhighlight %}
<div class="note">
<h5>ProTip™: Wordpress.com Export Tool</h5>
<p>If you are migrating from a Wordpress.com account, you can access the export tool at the following URL: `https://YOUR-USER-NAME.wordpress.com/wp-admin/export.php`.</p>
</div>
### Using Wordpress MySQL server connection
If you want to import using a direct connection to the Wordpress MySQL server, here's how:
{% highlight bash %}
$ ruby -rubygems -e 'require "jekyll/migrators/wordpress";
Jekyll::WordPress.process("database", "user", "pass")'
{% endhighlight %}
If you are using Webfaction and have to set up an [SSH
tunnel](http://docs.webfaction.com/user-guide/databases.html?highlight=mysql#starting-an-ssh-tunnel-with-ssh),
be sure to make the hostname (`127.0.0.1`) explicit, otherwise MySQL may block
your access based on `localhost` and `127.0.0.1` not being equivalent in its
authentication system:
{% highlight bash %}
$ ruby -rubygems -e 'require "jekyll/migrators/wordpress";
Jekyll::WordPress.process("database", "user", "pass", "127.0.0.1")'
{% endhighlight %}
### Further Wordpress migration alternatives
While the above methods work, they do not import much of the metadata that is
usually stored in Wordpress posts and pages. If you need to export things like
pages, tags, custom fields, image attachments and so on, the following resources
might be useful to you:
- [Exitwp](https://github.com/thomasf/exitwp) is a configurable tool written in
Python for migrating one or more Wordpress blogs into Jekyll (Markdown) format
while keeping as much metadata as possible. Exitwp also downloads attachments
and pages.
- [A great
article](http://vitobotta.com/how-to-migrate-from-wordpress-to-jekyll/) with a
step-by-step guide for migrating a Wordpress blog to Jekyll while keeping most
of the structure and metadata.
- [wpXml2Jekyll](https://github.com/theaob/wpXml2Jekyll) is an executable
windows application for creating Markdown posts from your Wordpress XML file.
## Drupal
If you’re migrating from [Drupal](http://drupal.org), there is [a
migrator](https://github.com/mojombo/jekyll/blob/master/lib/jekyll/migrators/drupal.rb)
for you too:
{% highlight bash %}
$ ruby -rubygems -e 'require "jekyll/migrators/drupal";
Jekyll::Drupal.process("database", "user", "pass")'
{% endhighlight %}
<div class="note warning">
<h5>Warning: Drupal Version Compatibility</h5>
<p>This migrator was written for Drupal 6.1 and may not work as expected with
newer versions of Drupal. Please update it and send us a pull request if
necessary.</p>
</div>
## Movable Type
To import posts from Movable Type:
{% highlight bash %}
$ ruby -rubygems -e 'require "jekyll/migrators/mt";
Jekyll::MT.process("database", "user", "pass")'
{% endhighlight %}
## Typo
To import posts from Typo:
{% highlight bash %}
$ ruby -rubygems -e 'require "jekyll/migrators/typo";
Jekyll::Typo.process("database", "user", "pass")'
{% endhighlight %}
This code has only been tested with Typo version 4+.
## TextPattern
To import posts from TextPattern:
{% highlight bash %}
$ ruby -rubygems -e 'require "jekyll/migrators/textpattern";
Jekyll::TextPattern.process("database_name", "username", "password", "hostname")'
{% endhighlight %}
You will need to run the above from the parent directory of your `_import`
folder. For example, if `_import` is located in `/path/source/_import`, you will
need to run this code from `/path/source`. The hostname defaults to `localhost`,
all other variables are required. You may need to adjust the code used to filter
entries. Left alone, it will attempt to pull all entries that are live or
sticky.
## Mephisto
To import posts from Mephisto:
{% highlight bash %}
$ ruby -rubygems -e 'require "jekyll/migrators/mephisto";
Jekyll::Mephisto.process("database", "user", "password")'
{% endhighlight %}
If your data is in Postgres, you should do this instead:
{% highlight bash %}
$ ruby -rubygems -e 'require "jekyll/migrators/mephisto";
Jekyll::Mephisto.postgres({:database => "database", :username=>"username", :password =>"password"})'
{% endhighlight %}
## Blogger (Blogspot)
To import posts from Blogger, see [this post about migrating from Blogger to
Jekyll](http://coolaj86.info/articles/migrate-from-blogger-to-jekyll.html). If
that doesn’t work for you, you might want to try some of the following
alternatives:
- [@kennym](https://github.com/kennym) created a [little migration
script](https://gist.github.com/1115810), because the solutions in the
previous article didn't work out for him.
- [@ngauthier](https://github.com/ngauthier) created [another
importer](https://gist.github.com/1506614) that imports comments, and does so
via blogger’s archive instead of the RSS feed.
- [@juniorz](https://github.com/juniorz) created [yet another
importer](https://gist.github.com/1564581) that works for
[Octopress](http://octopress.org). It is like [@ngauthier’s
version](https://gist.github.com/1506614) but separates drafts from posts, as
well as importing tags and permalinks.
## Posterous
To import posts from your primary Posterous blog:
{% highlight bash %}
$ ruby -rubygems -e 'require "jekyll/migrators/posterous";
Jekyll::Posterous.process("my_email", "my_pass")'
{% endhighlight %}
For any other Posterous blog on your account, you will need to specify the
`blog_id` for the blog:
{% highlight bash %}
$ ruby -rubygems -e 'require "jekyll/migrators/posterous";
Jekyll::Posterous.process("my_email", "my_pass", "blog_id")'
{% endhighlight %}
There is also an [alternative Posterous
migrator](https://github.com/pepijndevos/jekyll/blob/patch-1/lib/jekyll/migrators/posterous.rb)
that maintains permalinks and attempts to import images too.
## Tumblr
To import posts from Tumblr:
{% highlight bash %}
$ ruby -rubygems -e 'require "jekyll/migrators/tumblr";
Jekyll::Tumblr.process("http://www.your_blog_url.com", true)'
{% endhighlight %}
There is also [a modified Tumblr
migrator](https://github.com/stephenmcd/jekyll/blob/master/lib/jekyll/migrators/tumblr.rb)
that exports posts as Markdown and preserves post tags.
The migrator above requires the `json` gem and Python's `html2text` to be
installed as follows:
{% highlight bash %}
$ gem install json
$ pip install html2text
{% endhighlight %}
Once installed, simply use the format argument:
{% highlight bash %}
$ ruby -rubygems -e 'require "jekyll/migrators/tumblr";
Jekyll::Tumblr.process("http://www.your_blog_url.com", format="md")'
{% endhighlight %}
## Other Systems
If you have a system for which there is currently no migrator, consider writing
one and sending us a pull request.

86
site/docs/pages.md Normal file
View File

@@ -0,0 +1,86 @@
---
layout: docs
title: Creating pages
prev_section: posts
next_section: variables
permalink: /docs/pages/
---
In addition to [writing posts](../posts), another thing you may want to do with
your Jekyll site is create static pages. By taking advantage of the way Jekyll
copies files and directories, this is easy to do.
## Homepage
Just about every web server configuration you come across will look for an HTML
file called `index.html` (by convention) in the site's root folder and display
that as the homepage. Unless the web server you’re using is configured to look
for some different filename as the default, this file will turn into the
homepage of your Jekyll-generated site.
<div class="note">
<h5>ProTip™: Use layouts on your homepage</h5>
<p>
Any HTML file on your site can use layouts and/or includes, even the
homepage. Common content, like headers and footers, make excellent
candidates for extraction into a layout.
</p>
</div>
## Where additional pages live
Where you put HTML files for pages depends on how you want the pages to work.
There are two main ways of creating pages:
- Place named HTML files for each page in your site's root folder.
- Create a folder in the site's root for each page, and place an index.html file
in each page folder.
Both methods work fine (and can be used in conjunction with each other),
with the only real difference being the resulting URLs.
### Named HTML files
The simplest way of adding a page is just to add an HTML file in the root
directory with a suitable name for the page you want to create. For a site with
a homepage, an about page, and a contact page, here’s what the root directory
and associated URLs might look like:
{% highlight bash %}
.
|-- _config.yml
|-- _includes/
|-- _layouts/
|-- _posts/
|-- _site/
|-- about.html # => http://yoursite.com/about.html
|-- index.html # => http://yoursite.com/
└── contact.html # => http://yoursite.com/contact.html
{% endhighlight %}
### Named folders containing index HTML files
There is nothing wrong with the above method, however some people like to keep
their URLs free from things like filename extensions. To achieve clean URLs for
pages using Jekyll, you simply need to create a folder for each top-level page
you want, and then place an `index.html` file in each page’s folder. This way
the page URL ends up being the folder name, and the web server will serve up the
respective `index.html` file. Here's an example of what this structure might
look like:
{% highlight bash %}
.
├── _config.yml
├── _includes/
├── _layouts/
├── _posts/
├── _site/
├── about/
| └── index.html # => http://yoursite.com/about/
├── contact/
| └── index.html # => http://yoursite.com/contact/
└── index.html # => http://yoursite.com/
{% endhighlight %}
This approach may not suit everyone, but for people who like clean URLs it’s
simple and it works. In the end the decision is yours!

220
site/docs/pagination.md Normal file
View File

@@ -0,0 +1,220 @@
---
layout: docs
title: Pagination
prev_section: permalinks
next_section: plugins
permalink: /docs/pagination/
---
With many websites—especially blogs—it’s very common to break the main listing
of posts up into smaller lists and display them over multiple pages. Jekyll has
pagination built-in, so you can automatically generate the appropriate files and
folders you need for paginated listings.
<div class="note info">
<h5>Pagination only works within HTML files</h5>
<p>
Pagination does not work with Markdown or Textile files in your Jekyll site.
It will only work when used within HTML files. Since you’ll likely be using
this for the list of Posts, this shouldn't be an issue.
</p>
</div>
## Enable pagination
To enable pagination for your blog, add a line to the `_config.yml` file that
specifies how many items should be displayed per page:
{% highlight yaml %}
paginate: 5
{% endhighlight %}
The number should be the maximum number of Posts you’d like to be displayed per-
page in the generated site.
## Liquid Attributes Available
The pagination plugin exposes the `paginator` liquid object with the following
attributes:
<div class="mobile-side-scroller">
<table>
<thead>
<tr>
<th>Attribute</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><p><code>page</code></p></td>
<td><p>current page number</p></td>
</tr>
<tr>
<td><p><code>per_page</code></p></td>
<td><p>number of posts per page</p></td>
</tr>
<tr>
<td><p><code>posts</code></p></td>
<td><p>a list of posts for the current page</p></td>
</tr>
<tr>
<td><p><code>total_posts</code></p></td>
<td><p>total number of posts in the site</p></td>
</tr>
<tr>
<td><p><code>total_pages</code></p></td>
<td><p>number of pagination pages</p></td>
</tr>
<tr>
<td><p><code>previous_page</code></p></td>
<td>
<p>
page number of the previous pagination page,
or <code>nil</code> if no previous page exists
</p>
</td>
</tr>
<tr>
<td><p><code>previous_page_path</code></p></td>
<td>
<p>
path of previous pagination page,
or <code>nil</code> if no previous page exists
</p>
</td>
</tr>
<tr>
<td><p><code>next_page</code></p></td>
<td>
<p>
page number of the next pagination page,
or <code>nil</code> if no subsequent page exists
</p>
</td>
</tr>
<tr>
<td><p><code>next_page_path</code></p></td>
<td>
<p>
path of next pagination page,
or <code>nil</code> if no subsequent page exists
</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="note info">
<h5>Pagination does not support tags or categories</h5>
<p>Pagination pages through every post in the <code>posts</code>
variable regardless of variables defined in the YAML Front Matter of
each. It does not currently allow paging over groups of posts linked
by a common tag or category.</p>
</div>
## Render the paginated Posts
The next thing you need to do is to actually display your posts in a list using
the `paginator` variable that will now be available to you. You’ll probably want
to do this in one of the main pages of your site. Here’s one example of a simple
way of rendering paginated Posts in a HTML file:
{% highlight html %}
{% raw %}
---
layout: default
title: My Blog
---
<!-- This loops through the paginated posts -->
{% for post in paginator.posts %}
<h1><a href="{{ post.url }}">{{ post.title }}</a></h1>
<p class="author">
<span class="date">{{ post.date }}</span>
</p>
<div class="content">
{{ post.content }}
</div>
{% endfor %}
<!-- Pagination links -->
<div class="pagination">
{% if paginator.previous_page %}
<a href="/page{{ paginator.previous_page }}" class="previous">Previous</a>
{% else %}
<span class="previous">Previous</span>
{% endif %}
<span class="page_number ">Page: {{ paginator.page }} of {{ paginator.total_pages }}</span>
{% if paginator.next_page %}
<a href="/page{{ paginator.next_page }}" class="next">Next</a>
{% else %}
<span class="next ">Next</span>
{% endif %}
</div>
{% endraw %}
{% endhighlight %}
<div class="note warning">
<h5>Beware the page one edge-case</h5>
<p>
Jekyll does not generate a ‘page1’ folder, so the above code will not work
when a <code>/page1</code> link is produced. See below for a way to handle
this if it’s a problem for you.
</p>
</div>
The following HTML snippet should handle page one, and render a list of each
page with links to all but the current page.
{% highlight html %}
{% raw %}
<div id="post-pagination" class="pagination">
{% if paginator.previous_page %}
<p class="previous">
{% if paginator.previous_page == 1 %}
<a href="/">Previous</a>
{% else %}
<a href="{{ paginator.previous_page_path }}">Previous</a>
{% endif %}
</p>
{% else %}
<p class="previous disabled">
<span>Previous</span>
</p>
{% endif %}
<ul class="pages">
<li class="page">
{% if paginator.page == 1 %}
<span class="current-page">1</span>
{% else %}
<a href="/">1</a>
{% endif %}
</li>
{% for count in (2..paginator.total_pages) %}
<li class="page">
{% if count == paginator.page %}
<span class="current-page">{{ count }}</span>
{% else %}
<a href="/page{{ count }}">{{ count }}</a>
{% endif %}
</li>
{% endfor %}
</ul>
{% if paginator.next_page %}
<p class="next">
<a href="{{ paginator.next_page_path }}">Next</a>
</p>
{% else %}
<p class="next disabled">
<span>Next</span>
</p>
{% endif %}
</div>
{% endraw %}
{% endhighlight %}

180
site/docs/permalinks.md Normal file
View File

@@ -0,0 +1,180 @@
---
layout: docs
title: Permalinks
prev_section: templates
next_section: pagination
permalink: /docs/permalinks/
---
Jekyll supports a flexible way to build your site’s URLs. You can specify the
permalinks for your site through the [Configuration](../configuration) or in the
[YAML Front Matter](../frontmatter) for each post. You’re free to choose one of
the built-in styles to create your links or craft your own. The default style is
`date`.
Permalinks are constructed by creating a template URL where dynamic elements are
represented by colon-prefixed keywords. For example, the default `date`
permalink is defined as `/:categories/:year/:month/:day/:title.html`.
## Template variables
<div class="mobile-side-scroller">
<table>
<thead>
<tr>
<th>Variable</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p><code>year</code></p>
</td>
<td>
<p>Year from the Post’s filename</p>
</td>
</tr>
<tr>
<td>
<p><code>month</code></p>
</td>
<td>
<p>Month from the Post’s filename</p>
</td>
</tr>
<tr>
<td>
<p><code>i_month</code></p>
</td>
<td>
<p>Month from the Post’s filename without leading zeros.</p>
</td>
</tr>
<tr>
<td>
<p><code>day</code></p>
</td>
<td>
<p>Day from the Post’s filename</p>
</td>
</tr>
<tr>
<td>
<p><code>i_day</code></p>
</td>
<td>
<p>Day from the Post’s filename without leading zeros.</p>
</td>
</tr>
<tr>
<td>
<p><code>title</code></p>
</td>
<td>
<p>Title from the Post’s filename</p>
</td>
</tr>
<tr>
<td>
<p><code>categories</code></p>
</td>
<td>
<p>
The specified categories for this Post. Jekyll automatically parses
out double slashes in the URLs, so if no categories are present, it
will ignore this.
</p>
</td>
</tr>
</tbody>
</table>
</div>
## Built-in permalink styles
<div class="mobile-side-scroller">
<table>
<thead>
<tr>
<th>Permalink Style</th>
<th>URL Template</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p><code>date</code></p>
</td>
<td>
<p><code>/:categories/:year/:month/:day/:title.html</code></p>
</td>
</tr>
<tr>
<td>
<p><code>pretty</code></p>
</td>
<td>
<p><code>/:categories/:year/:month/:day/:title/</code></p>
</td>
</tr>
<tr>
<td>
<p><code>none</code></p>
</td>
<td>
<p><code>/:categories/:title.html</code></p>
</td>
</tr>
</tbody>
</table>
</div>
## Permalink style examples
Given a post named: `/2009-04-29-slap-chop.textile`
<div class="mobile-side-scroller">
<table>
<thead>
<tr>
<th>Permalink Setting</th>
<th>Resulting Permalink URL</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>None specified, or <code>permalink: date</code></p>
</td>
<td>
<p><code>/2009/04/29/slap-chop.html</code></p>
</td>
</tr>
<tr>
<td>
<p><code>permalink: pretty</code></p>
</td>
<td>
<p><code>/2009/04/29/slap-chop/index.html</code></p>
</td>
</tr>
<tr>
<td>
<p><code>permalink: /:month-:day-:year/:title.html</code></p>
</td>
<td>
<p><code>/04-29-2009/slap-chop.html</code></p>
</td>
</tr>
<tr>
<td>
<p><code>permalink: /blog/:year/:month/:day/:title</code></p>
</td>
<td>
<p><code>/blog/2009/04/29/slap-chop/index.html</code></p>
</td>
</tr>
</tbody>
</table>
</div>

437
site/docs/plugins.md Normal file
View File

@@ -0,0 +1,437 @@
---
layout: docs
title: Plugins
prev_section: assets
next_section: extras
permalink: /docs/plugins/
---
Jekyll has a plugin system with hooks that allow you to create custom generated
content specific to your site. You can run custom code for your site without
having to modify the Jekyll source itself.
<div class="note info">
<h5>Plugins on GitHub Pages</h5>
<p>
<a href="http://pages.github.com">GitHub Pages</a> is powered by Jekyll,
however all Pages sites are generated using the <code>--safe</code> option
to disable custom plugins for security reasons. Unfortunately, this means
your plugins won’t work if you’re deploying to GitHub Pages.<br><br>
You can still use GitHub Pages to publish your site, but you'll need to
convert the site locally and push the generated static files to your GitHub
repository instead of the Jekyll source files.
</p>
</div>
## Installing a plugin
In your site source root, make a `_plugins` directory. Place your plugins here.
Any file ending in `*.rb` inside this directory will be loaded before Jekyll
generates your site.
In general, plugins you make will fall into one of three categories:
1. Generators
2. Converters
3. Tags
## Generators
You can create a generator when you need Jekyll to create additional content
based on your own rules. For example, a generator might look like this:
{% highlight ruby %}
module Jekyll
class CategoryPage < Page
def initialize(site, base, dir, category)
@site = site
@base = base
@dir = dir
@name = 'index.html'
self.process(@name)
self.read_yaml(File.join(base, '_layouts'), 'category_index.html')
self.data['category'] = category
category_title_prefix = site.config['category_title_prefix'] || 'Category: '
self.data['title'] = "#{category_title_prefix}#{category}"
end
end
class CategoryPageGenerator < Generator
safe true
def generate(site)
if site.layouts.key? 'category_index'
dir = site.config['category_dir'] || 'categories'
site.categories.keys.each do |category|
site.pages << CategoryPage.new(site, site.source, File.join(dir, category), category)
end
end
end
end
end
{% endhighlight %}
In this example, our generator will create a series of files under the
`categories` directory for each category, listing the posts in each category
using the `category_index.html` layout.
Generators are only required to implement one method:
<div class="mobile-side-scroller">
<table>
<thead>
<tr>
<th>Method</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p><code>generate</code></p>
</td>
<td>
<p>String output of the content being generated.</p>
</td>
</tr>
</tbody>
</table>
</div>
## Converters
If you have a new markup language you’d like to use with your site, you can
include it by implementing your own converter. Both the Markdown and Textile
markup languages are implemented using this method.
<div class="note info">
<h5>Remember your YAML front-matter</h5>
<p>
Jekyll will only convert files that have a YAML header at the top, even for
converters you add using a plugin.
</p>
</div>
Below is a converter that will take all posts ending in `.upcase` and process
them using the `UpcaseConverter`:
{% highlight ruby %}
module Jekyll
class UpcaseConverter < Converter
safe true
priority :low
def matches(ext)
ext =~ /^\.upcase$/i
end
def output_ext(ext)
".html"
end
def convert(content)
content.upcase
end
end
end
{% endhighlight %}
Converters should implement at a minimum 3 methods:
<div class="mobile-side-scroller">
<table>
<thead>
<tr>
<th>Method</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p><code>matches</code></p>
</td>
<td><p>
Does the given extension match this converter's list of acceptable
extensions? Takes one argument: the file's extension (including the
dot). Must return <code>true</code> if it matches, <code>false</code>
otherwise.
</p></td>
</tr>
<tr>
<td>
<p><code>output_ext</code></p>
</td>
<td><p>
The extension to be given to the output file (including the dot).
Usually this will be <code>".html"</code>.
</p></td>
</tr>
<tr>
<td>
<p><code>convert</code></p>
</td>
<td><p>
Logic to do the content conversion. Takes one argument: the raw content
of the file (without YAML front matter). Must return a String.
</p></td>
</tr>
</tbody>
</table>
</div>
In our example, `UpcaseConverter#matches` checks if our filename extension is
`.upcase`, and will render using the converter if it is. It will call
`UpcaseConverter#convert` to process the content. In our simple converter we’re
simply uppercasing the entire content string. Finally, when it saves the page,
it will do so with a `.html` extension.
## Tags
If you’d like to include custom liquid tags in your site, you can do so by
hooking into the tagging system. Built-in examples added by Jekyll include the
`highlight` and `include` tags. Below is an example of a custom liquid tag that
will output the time the page was rendered:
{% highlight ruby %}
module Jekyll
class RenderTimeTag < Liquid::Tag
def initialize(tag_name, text, tokens)
super
@text = text
end
def render(context)
"#{@text} #{Time.now}"
end
end
end
Liquid::Template.register_tag('render_time', Jekyll::RenderTimeTag)
{% endhighlight %}
At a minimum, liquid tags must implement:
<div class="mobile-side-scroller">
<table>
<thead>
<tr>
<th>Method</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p><code>render</code></p>
</td>
<td>
<p>Outputs the content of the tag.</p>
</td>
</tr>
</tbody>
</table>
</div>
You must also register the custom tag with the Liquid template engine as
follows:
{% highlight ruby %}
Liquid::Template.register_tag('render_time', Jekyll::RenderTimeTag)
{% endhighlight %}
In the example above, we can place the following tag anywhere in one of our
pages:
{% highlight ruby %}
{% raw %}
<p>{% render_time page rendered at: %}</p>
{% endraw %}
{% endhighlight %}
And we would get something like this on the page:
{% highlight html %}
<p>page rendered at: Tue June 22 23:38:47 –0500 2010</p>
{% endhighlight %}
### Liquid filters
You can add your own filters to the Liquid template system much like you can add
tags above. Filters are simply modules that export their methods to liquid. All
methods will have to take at least one parameter which represents the input of
the filter. The return value will be the output of the filter.
{% highlight ruby %}
module Jekyll
module AssetFilter
def asset_url(input)
"http://www.example.com/#{input}?#{Time.now.to_i}"
end
end
end
Liquid::Template.register_filter(Jekyll::AssetFilter)
{% endhighlight %}
<div class="note">
<h5>ProTip™: Access the site object using Liquid</h5>
<p>
Jekyll lets you access the <code>site</code> object through the
<code>context.registers</code> feature of Liquid. For example, you can
access the global configuration file <code>_config.yml</code> using
<code>context.registers.config</code>.
</p>
</div>
### Flags
There are two flags to be aware of when writing a plugin:
<div class="mobile-side-scroller">
<table>
<thead>
<tr>
<th>Flag</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p><code>safe</code></p>
</td>
<td>
<p>
A boolean flag that informs Jekyll whether this plugin may be safely
executed in an environment where arbitrary code execution is not
allowed. This is used by GitHub Pages to determine which core plugins
may be used, and which are unsafe to run. If your plugin does not
allow for arbitrary code, execution, set this to <code>true</code>.
GitHub Pages still won't load your plugin, but if you submit it for
inclusion in core, it's best for this to be correct!
</p>
</td>
</tr>
<tr>
<td>
<p><code>priority</code></p>
</td>
<td>
<p>
This flag determines what order the plugin is loaded in. Valid values
are: <code>:lowest</code>, <code>:low</code>, <code>:normal</code>,
<code>:high</code>, and <code>:highest</code>. Highest priority
matches are applied first, lowest priority are applied last.
</p>
</td>
</tr>
</tbody>
</table>
</div>
To use one of the example plugins above as an illustration, here is how you’d
specify these two flags:
{% highlight ruby %}
module Jekyll
class UpcaseConverter < Converter
safe true
priority :low
...
end
end
{% endhighlight %}
## Available Plugins
There are a few useful, prebuilt plugins at the following locations:
- [Truncate HTML while preserving markup structure](https://github.com/MattHall/truncatehtml) by [Matt Hall](http://codebeef.com)
- [Generic Blog Plugins by Jose Diaz-Gonzalez](https://github.com/josegonzalez/josediazgonzalez.com/tree/master/_plugins): Contains plugins for tags, categories, archives, as well as a few Liquid extensions
- [Domain Name Filter by Lawrence Woodman](https://github.com/LawrenceWoodman/domain_name-liquid_filter): Filters the input text so that just the domain name is left
- [Jekyll Plugins by Recursive Design](http://recursive-design.com/projects/jekyll-plugins/): Plugin to generate Project pages from GitHub readmes, a Category page plugin, and a Sitemap generator
- [Tag Cloud Plugin from a Jekyll walk-through](http://vitobotta.com/how-to-migrate-from-wordpress-to-jekyll/): Plugin to generate a tag cloud
- [Pygments Cache Path by Raimonds Simanovskis](https://github.com/rsim/blog.rayapps.com/blob/master/_plugins/pygments_cache_patch.rb): Plugin to cache syntax-highlighted code from Pygments
- [Delicious Plugin by Christian Hellsten](https://github.com/christianhellsten/jekyll-plugins): Fetches and renders bookmarks from delicious.com.
- [Ultraviolet plugin by Steve Alex](https://gist.github.com/480380): Jekyll Plugin for Ultraviolet
- [HAML plugin by Sam Z](https://gist.github.com/517556): HAML plugin for jekyll
- [ArchiveGenerator by Ilkka Laukkanen](https://gist.github.com/707909): Uses [this archive page](https://gist.github.com/707020) to generate archives
- [Tag Cloud Plugin by Ilkka Laukkanen](https://gist.github.com/710577): Jekyll tag cloud / tag pages plugin
- [HAML/SASS Converter by Adam Pearson](https://gist.github.com/481456): Simple haml-sass conversion for jekyll. [Fork](https://gist.github.com/528642) by Sam X
- [SASS scss Converter by Mark Wolfe](https://gist.github.com/960150): Jekyll Converter which uses the new css compatible syntax, based on the one written by Sam X.
- [GIT Tag by Alexandre Girard](https://gist.github.com/730347): Jekyll plugin to add Git activity inside a list
- [Draft/Publish Plugin by Michael Ivey](https://gist.github.com/49630)
- [Less.js generator by Andy Fowler](https://gist.github.com/642739): Jekyll plugin to render less.js files during generation.
- [Less Converter by Jason Graham](https://gist.github.com/639920): A Jekyll plugin to convert a .less file to .css
- [Less Converter by Josh Brown](https://gist.github.com/760265)
- [MathJax Liquid Tags by Jessy Cowan-Sharp](https://gist.github.com/834610): A simple liquid tag for Jekyll that converts and into inline math, and and into block equations, by replacing with the appropriate MathJax script tags.
- [Non-JS Gist Tag by Brandon Tilley](https://gist.github.com/1027674) A Liquid tag for Jekyll sites that allows embedding Gists and showing code for non-JavaScript enabled browsers and readers.
- [Growl Notification Generator by Tate Johnson](https://gist.github.com/490101)
- [Growl Notification Hook by Tate Johnson](https://gist.github.com/525267): Better alternative to the above, but requires his “hook” fork.
- [Version Reporter by Blake Smith](https://gist.github.com/449491)
- [Upcase Converter by Blake Smith](https://gist.github.com/449463)
- [Render Time Tag by Blake Smith](https://gist.github.com/449509)
- [Summarize Filter by Mathieu Arnold](https://gist.github.com/731597)
- [Status.net/OStatus Tag by phaer](https://gist.github.com/912466)
- [CoffeeScript converter by phaer](https://gist.github.com/959938): Put this file in `plugins` and write a YAML header to your .coffee files. See [http://coffeescript.org](http://coffeescript.org) for more info
- [Raw Tag by phaer.](https://gist.github.com/1020852): Keeps liquid from parsing text betweeen `{{ "{% raw " }}%}` and `{{ "{% endraw " }}%}`
- [URL encoding by James An](https://gist.github.com/919275)
- [Sitemap.xml Generator by Michael Levin](http://www.kinnetica.com/projects/jekyll-sitemap-generator/)
- [Markdown references by Olov Lassus](https://github.com/olov/jekyll-references): Keep all your markdown reference-style link definitions in one file (_references.md)
- [Full-text search by Pascal Widdershoven](https://github.com/PascalW/jekyll_indextank): Add full-text search to your Jekyll site with this plugin and a bit of JavaScript.
- [Stylus Converter](https://gist.github.com/988201) Convert .styl to .css.
- [Embed.ly client by Robert Böhnke](https://github.com/robb/jekyll-embedly-client) Autogenerate embeds from URLs using oEmbed.
- [Logarithmic Tag Cloud](https://gist.github.com/2290195): Flexible. Logarithmic distribution. Documentation inline.
- [Related Posts by Lawrence Woodman](https://github.com/LawrenceWoodman/related_posts-jekyll_plugin): Overrides `site.related_posts` to use categories to assess relationship
- [AliasGenerator by Thomas Mango](https://github.com/tsmango/jekyll_alias_generator): Generates redirect pages for posts when an alias configuration is specified in the YAML Front Matter.
- [FlickrSetTag by Thomas Mango](https://github.com/tsmango/jekyll_flickr_set_tag): Generates image galleries from Flickr sets.
- [Projectlist by Frederic Hemberger](https://github.com/fhemberger/jekyll-projectlist): Loads all files from a directory and renders the entries into a single page, instead of creating separate posts.
- [Tiered Archives by Eli Naeher](https://gist.github.com/88cda643aa7e3b0ca1e5): creates a tiered template variable that allows you to create archives grouped by year and month.
- [Jammit generator by Vladimir Andrijevik](https://gist.github.com/1224971): enables use of [Jammit](http://documentcloud.github.com/jammit/) for JavaScript and CSS packaging.
- [oEmbed Tag by Tammo van Lessen](https://gist.github.com/1455726): enables easy content embedding (e.g. from YouTube, Flickr, Slideshare) via oEmbed.
- [Company website and blog plugins](https://github.com/flatterline/jekyll-plugins) by Flatterline, a [Ruby on Rails development company](http://flatterline.com/): portfolio/project page generator, team/individual page generator, author bio liquid template tag for use on posts and a few other smaller plugins.
- [Transform Layouts](https://gist.github.com/1472645) Monkey patching allowing HAML layouts (you need a HAML Converter plugin for this to work)
- [ReStructuredText converter](https://github.com/xdissent/jekyll-rst): Converts ReST documents to HTML with Pygments syntax highlighting.
- [Tweet Tag by Scott W. Bradley](https://github.com/scottwb/jekyll-tweet-tag): Liquid tag for [Embedded Tweets](https://dev.twitter.com/docs/embedded-tweets) using Twitter’s shortcodes
- [jekyll-localization](https://github.com/blackwinter/jekyll-localization): Jekyll plugin that adds localization features to the rendering engine.
- [jekyll-rendering](https://github.com/blackwinter/jekyll-rendering): Jekyll plugin to provide alternative rendering engines.
- [jekyll-pagination](https://github.com/blackwinter/jekyll-pagination): Jekyll plugin to extend the pagination generator.
- [jekyll-tagging](https://github.com/pattex/jekyll-tagging): Jekyll plugin to automatically generate a tag cloud and tag pages.
- [Generate YouTube Embed (tag)](https://gist.github.com/1805814) by [joelverhagen](https://github.com/joelverhagen): Jekyll plugin which allows you to embed a YouTube video in your page with the YouTube ID. Optionally specify width and height dimensions. Like “oEmbed Tag” but just for YouTube.
- [JSON Filter](https://gist.github.com/1850654) by [joelverhagen](https://github.com/joelverhagen): filter that takes input text and outputs it as JSON. Great for rendering JavaScript.
- [jekyll-beastiepress](https://github.com/okeeblow/jekyll-beastiepress): FreeBSD utility tags for Jekyll sites.
- [jsonball](https://gist.github.com/1895282): reads json files and produces maps for use in jekylled files
- [redcarpet2](https://github.com/nono/Jekyll-plugins): use Redcarpet2 for rendering markdown
- [bibjekyll](https://github.com/pablooliveira/bibjekyll): render BibTeX-formatted bibliographies/citations included in posts/pages using bibtex2html
- [jekyll-citation](https://github.com/archome/jekyll-citation): render BibTeX-formatted bibliographies/citations included in posts/pages (pure Ruby)
- [jekyll-scholar](https://github.com/inukshuk/jekyll-scholar): Jekyll extensions for the blogging scholar
- [jekyll-asset_bundler](https://github.com/moshen/jekyll-asset_bundler): bundles and minifies JavaScript and CSS
- [Jekyll Dribbble Set Tag](https://github.com/ericdfields/Jekyll-Dribbble-Set-Tag): builds Dribbble image galleries from any user
- [debbugs](https://gist.github.com/2218470): allows posting links to Debian BTS easily
- [refheap_tag](https://github.com/aburdette/refheap_tag): Liquid tag that allows embedding pastes from [refheap](https://refheap.com)
- [i18n_filter](https://github.com/gacha/gacha.id.lv/blob/master/_plugins/i18n_filter.rb): Liquid filter to use I18n localization.
- [singlepage-jekyll](https://github.com/JCB-K/singlepage-jekyll) by [JCB-K](https://github.com/JCB-K): turns Jekyll into a dynamic one-page website.
- [flickr](http://jonasforsberg.se/2012/04/15/flickr-plugin-for-jekyll/): Embed photos from flickr right into your posts.
- [jekyll-devonly_tag](https://gist.github.com/2403522): A block tag for including markup only during development.
- [Jekyll plugins by Aucor](https://github.com/aucor/jekyll-plugins): Plugins for eg. trimming unwanted newlines/whitespace and sorting pages by weight attribute.
- [Only first paragraph](https://github.com/sebcioz/jekyll-only_first_p): Show only first paragrpaph of page/post.
- [jekyll-pandoc-plugin](https://github.com/dsanson/jekyll-pandoc-plugin): use pandoc for rendering markdown.
- [File compressor](https://gist.github.com/2758691) by [mytharcher](https://github.com/mytharcher): Compress HTML (\*.html) and JavaScript(\*.js) files when output.
- [smilify](https://github.com/SaswatPadhi/jekyll_smilify) by [SaswatPadhi](https://github.com/SaswatPadhi): Convert text emoticons in your content to themeable smiley pics. [Demo](http://saswatpadhi.github.com/)
- [excerpts](http://blog.darkrefraction.com/2012/jekyll-excerpt-plugin.html) by [drawoc](https://github.com/drawoc): provides a nice way to implement page excerpts.
<div class="note info">
<h5>Jekyll Plugins Wanted</h5>
<p>
If you have a Jekyll plugin that you would like to see added to this list,
you should <a href="../contributing">read the contributing page</a> to find
out how to make that happen.
</p>
</div>

158
site/docs/posts.md Normal file
View File

@@ -0,0 +1,158 @@
---
layout: docs
title: Writing posts
prev_section: frontmatter
next_section: pages
permalink: /docs/posts/
---
One of Jekyll’s best aspects is that it is “blog aware”. What does this mean,
exactly? Well, simply put, it means that blogging is baked into Jekyll’s
functionality. If you write articles and publish them online, this means that
you can publish and maintain a blog simply by managing a folder of text-files on
your computer. Compared to the hassle of configuring and maintaining databases
and web-based CMS systems, this will be a welcome change!
## The Posts Folder
As explained on the [directory structure](../structure) page, the `_posts`
folder is where your blog posts will live. These files can be either
[Markdown](http://daringfireball.net/projects/markdown/) or
[Textile](http://textile.sitemonks.com/) formatted text files, and as long as
they have [YAML front-matter](../frontmatter), they will be converted from their
source format into an HTML page that is part of your static site.
### Creating Post Files
To create a new post, all you need to do is create a new file in the `_posts`
directory. How you name files in this folder is important. Jekyll requires blog
post files to be named according to the following format:
{% highlight bash %}
YEAR-MONTH-DAY-title.MARKUP
{% endhighlight %}
Where `YEAR` is a four-digit number, `MONTH` and `DAY` are both two-digit
numbers, and `MARKUP` is the file extension representing the format used in the
file. For example, the following are examples of valid post filenames:
{% highlight bash %}
2011-12-31-new-years-eve-is-awesome.md
2012-09-12-how-to-write-a-blog.textile
{% endhighlight %}
### Content Formats
All blog post files must begin with [YAML front- matter](../frontmatter). After
that, it's simply a matter of deciding which format you prefer. Jekyll supports
two popular content markup formats:
[Markdown](http://daringfireball.net/projects/markdown/) and
[Textile](http://textile.sitemonks.com/). These formats each have their own way
of marking up different types of content within a post, so you should
familiarize yourself with these formats and decide which one best suits your
needs.
## Including images and resources
Chances are, at some point, you'll want to include images, downloads, or other
digital assets along with your text content. While the syntax for linking to
these resources differs between Markdown and Textile, the problem of working out
where to store these files in your site is something everyone will face.
Because of Jekyll’s flexibility, there are many solutions to how to do this. One
common solution is to create a folder in the root of the project directory
called something like `assets` or `downloads`, into which any images, downloads
or other resources are placed. Then, from within any post, they can be linked to
using the site’s root as the path for the asset to include. Again, this will
depend on the way your site’s (sub)domain and path are configured, but here some
examples (in Markdown) of how you could do this using the `site.url` variable in
a post.
Including an image asset in a post:
{% highlight text %}
… which is shown in the screenshot below:
![My helpful screenshot]({% raw %}{{ site.url }}{% endraw %}/assets/screenshot.jpg)
{% endhighlight %}
Linking to a PDF for readers to download:
{% highlight text %}
… you can [get the PDF]({% raw %}{{ site.url }}{% endraw %}/assets/mydoc.pdf) directly.
{% endhighlight %}
<div class="note">
<h5>ProTip™: Link using just the site root URL</h5>
<p>
You can skip the <code>{% raw %}{{ site.url }}{% endraw %}</code> variable
if you <strong>know</strong> your site will only ever be displayed at the
root URL of your domain. In this case you can reference assets directly with
just <code>/path/file.jpg</code>.
</p>
</div>
## Displaying an index of posts
It’s all well and good to have posts in a folder, but a blog is no use unless
you have a list of posts somewhere. Creating an index of posts on another page
(or in a [template](../templates)) is easy, thanks to the [Liquid template
language](http://wiki.shopify.com/Liquid) and its tags. Here’s a basic example of how
to create a list of links to your blog posts:
{% highlight html %}
<ul>
{% raw %}{% for post in site.posts %}{% endraw %}
<li>
<a href="{% raw %}{{ post.url }}{% endraw %}">{% raw %}{{ post.title }}{% endraw %}</a>
</li>
{% raw %}{% endfor %}{% endraw %}
</ul>
{% endhighlight %}
Of course, you have full control over how (and where) you display your posts,
and how you structure your site. You should read more about [how templates
work](../templates) with Jekyll if you want to know more.
## Highlighting code snippets
Jekyll also has built-in support for syntax highlighting of code snippets using
[Pygments](../extras), and including a code snippet in any post is easy. Just
use the dedicated Liquid tag as follows:
{% highlight text %}
{% raw %}{% highlight ruby %}{% endraw %}
def show
@widget = Widget(params[:id])
respond_to do |format|
format.html # show.html.erb
format.json { render json: @widget }
end
end
{% raw %}{% endhighlight %}{% endraw %}
{% endhighlight %}
And the output will look like this:
{% highlight ruby %}
def show
@widget = Widget(params[:id])
respond_to do |format|
format.html # show.html.erb
format.json { render json: @widget }
end
end
{% endhighlight %}
<div class="note">
<h5>ProTip™: Show line numbers</h5>
<p>
You can make code snippets include line-numbers by adding the word
<code>linenos</code> to the end of the opening highlight tag like this:
<code>{% raw %}{% highlight ruby linenos %}{% endraw %}</code>.
</p>
</div>
These basics should be enough to get you started writing your first posts. When
you’re ready to dig into what else is possible, you might be interested in doing
things like [customizing post permalinks](../permalinks) or using [custom
variables](../variables) in your posts and elsewhere on your site.

47
site/docs/resources.md Normal file
View File

@@ -0,0 +1,47 @@
---
layout: docs
title: Resources
prev_section: sites
next_section: upgrading
permalink: /docs/resources/
---
Jekyll’s growing use is producing a wide variety of tutorials, frameworks, extensions, examples, and other resources that can be very helpful. Below is a collection of links to some of the most popular Jekyll resources.
### Jekyll tips & tricks, and examples
- [Tips for working with GitHub Pages Integration](https://gist.github.com/2890453)
Code example reuse, and keeping documentation up to date.
- [Use Simple Form to integrate a simple contact
form](http://getsimpleform.com/)
- [JekyllBootstrap.com](http://jekyllbootstrap.com)
Provides detailed explanations, examples, and helper-code to make
getting started with Jekyll easier.
### Tutorials
#### Integrating Jekyll with Git
- [Blogging with Git, Emacs and Jekyll](http://metajack.im/2009/01/23/blogging-with-git-emacs-and-jekyll/)
- [Using Git to maintain your blog](http://matedriven.com.ar/2009/04/28/using-git-to-maintain-your-blog.html) (step by step guide)
#### Other hacks
- [Integrating Twitter with Jekyll](http://www.justkez.com/integrating-twitter-with-jekyll/)
> “Having migrated Justkez.com to be based on Jekyll, I was pondering how I might include my recent twitterings on the front page of the site. In the Wordpress world, this would have been done via a plugin which may or may not have hung the loading of the page, might have employed caching, but would certainly have had some overheads. … Not in Jekyll.”
- [‘My Jekyll Fork’, by Mike West](http://mikewest.org/2009/11/my-jekyll-fork)
> “Jekyll is a well-architected throwback to a time before Wordpress, when men were men, and HTML was static. I like the ideas it espouses, and have made a few improvements to it’s core. Here, I’ll point out some highlights of my fork in the hopes that they see usage beyond this site.”
- [‘About this Website’, by Carter Allen](http://cartera.me/2010/08/12/about-this-website/)
> “Jekyll is everything that I ever wanted in a blogging engine. Really. It isn’t perfect, but what’s excellent about it is that if there’s something wrong, I know exactly how it works and how to fix it. It runs on the your machine only, and is essentially an added”build" step between you and the browser. I coded this entire site in TextMate using standard HTML5 and CSS3, and then at the end I added just a few little variables to the markup. Presto-chango, my site is built and I am at peace with the world.”
- [Generating a Tag Cloud in Jekyll](http://www.justkez.com/generating-a-tag-cloud-in-jekyll/)
A guide to implementing a tag cloud and per-tag content pages using Jekyll.
- [Jekyll Extensions -= Pain](http://rfelix.com/2010/01/19/jekyll-extensions-minus-equal-pain/)
A way to [extend Jekyll](http://github.com/rfelix/jekyll_ext) without forking and modifying the Jekyll gem codebase and some [portable Jekyll extensions](http://wiki.github.com/rfelix/jekyll_ext/extensions) that can be reused and shared.
- [Using your Rails layouts in Jekyll](http://numbers.brighterplanet.com/2010/08/09/sharing-rails-views-with-jekyll)

29
site/docs/sites.md Normal file
View File

@@ -0,0 +1,29 @@
---
layout: docs
title: Sites using Jekyll
prev_section: troubleshooting
next_section: resources
permalink: /docs/sites/
---
It’s interesting to see what designs and features others have come up
with. Below are some Jekyll-powered blogs which were hand-picked for
learning purposes.
- [Tom Preston-Werner](http://tom.preston-werner.com/)
([source](http://github.com/mojombo/mojombo.github.com))
- [Nick Quaranto](http://quaran.to/)
([source](https://github.com/qrush/qrush.github.com))
- [Roger Chapman](http://rogchap.com/)
([source](https://github.com/rogchap/rogchap.github.com))
- [GitHub Official Teaching Materials](http://teach.github.com)
([source](https://github.com/github/teach.github.com))
- [Rasmus Andersson](http://rsms.me/)
([source](https://github.com/rsms/rsms.github.com))
- [Scott Chacon](http://schacon.github.com)
([source](https://github.com/schacon/schacon.github.com))
If you would like to explore more examples, you can find a list of sites
and their sources on the ["Sites" page in the Jekyll wiki][jekyll-sites].
[jekyll-sites]: https://github.com/mojombo/jekyll/wiki/Sites

158
site/docs/structure.md Normal file
View File

@@ -0,0 +1,158 @@
---
layout: docs
title: Directory structure
prev_section: usage
next_section: configuration
permalink: /docs/structure/
---
Jekyll is, at its core, a text transformation engine. The concept behind the
system is this: you give it text written in your favorite markup language, be
that Markdown, Textile, or just plain HTML, and it churns that through a layout
or series of layout files. Throughout that process you can tweak how you want
the site URLs to look, what data gets displayed in the layout, and more. This is
all done through editing text files, and the static web site is the final
product.
A basic Jekyll site usually looks something like this:
{% highlight bash %}
.
├── _config.yml
├── _includes
| ├── footer.html
| └── header.html
├── _layouts
| ├── default.html
| └── post.html
├── _posts
| ├── 2007-10-29-why-every-programmer-should-play-nethack.textile
| └── 2009-04-26-barcamp-boston-4-roundup.textile
├── _site
└── index.html
{% endhighlight %}
An overview of what each of these does:
<div class="mobile-side-scroller">
<table>
<thead>
<tr>
<th>File / Directory</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p><code>_config.yml</code></p>
</td>
<td>
<p>
Stores <a href="../configuration">configuration</a> data. Many of
these options can be specified from the command line executable but
it’s easier to specify them here so you don’t have to remember them.
</p>
</td>
</tr>
<tr>
<td>
<p><code>_includes</code></p>
</td>
<td>
<p>
These are the partials that can be mixed and matched by your layouts
and posts to facilitate reuse. The liquid tag
<code>{% raw %}{% include file.ext %}{% endraw %}</code>
can be used to include the partial in
<code>_includes/file.ext</code>.
</p>
</td>
</tr>
<tr>
<td>
<p><code>_layouts</code></p>
</td>
<td>
<p>
These are the templates that wrap posts. Layouts are chosen on a post-
by-post basis in the <a href="../frontmatter">YAML front matter</a>,
which is described in the next section. The liquid tag
<code>{% raw %}{{ content }}{% endraw %}</code>
is used to inject content into the web page.
</p>
</td>
</tr>
<tr>
<td>
<p><code>_posts</code></p>
</td>
<td>
<p>
Your dynamic content, so to speak. The format of these files is
important, and must follow the format:
<code>YEAR-MONTH-DAY-title.MARKUP</code>.
The <a href="../permalinks">permalinks</a> can be customized for each
post, but the date and markup language are determined solely by the
file name.
</p>
</td>
</tr>
<tr>
<td>
<p><code>_site</code></p>
</td>
<td>
<p>
This is where the generated site will be placed (by default) once
Jekyll is done transforming it. It's probably a good idea to add this
to your <code>.gitignore</code> file.
</p>
</td>
</tr>
<tr>
<td>
<p><code>index.html</code> and other HTML, Markdown, Textile files</p>
</td>
<td>
<p>
Provided that the file has a <a href="../frontmatter">YAML Front
Matter</a> section, it will be transformed by Jekyll. The same will
happen for any <code>.html</code>, <code>.markdown</code>,
<code>.md</code>, or <code>.textile</code> file in your site's root
directory or directories not listed above.
</p>
</td>
</tr>
<tr>
<td>
<p>Other Files/Folders</p>
</td>
<td>
<p>
Every other directory and file except for those listed above—such as
<code>css</code> and <code>images</code> folders,
<code>favicon.ico</code> files, and so forth—will be copied verbatim
to the generated site. There are plenty of <a href="../sites">sites
already using Jekyll</a> if you're curious to see how they're laid
out.
</p>
</td>
</tr>
</tbody>
</table>
</div>

236
site/docs/templates.md Normal file
View File

@@ -0,0 +1,236 @@
---
layout: docs
title: Templates
prev_section: migrations
next_section: permalinks
permalink: /docs/templates/
---
Jekyll uses the [Liquid](http://wiki.shopify.com/Liquid) templating language to
process templates. All of the [standard Liquid tags and
filters](http://wiki.github.com/shopify/liquid/liquid-for-designers) are
supported, Jekyll even adds a few handy filters and tags of its own to make
common tasks easier.
## Filters
<div class="mobile-side-scroller">
<table>
<thead>
<tr>
<th>Description</th>
<th><span class="filter">Filter</span> and <span class="output">Output</span></th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p class='name'><strong>Date to XML Schema</strong></p>
<p>Convert a Date into XML Schema format.</p>
</td>
<td class='align-center'>
<p>
<code class='filter'>{% raw %}{{ site.time | date_to_xmlschema }}{% endraw %}</code>
</p>
<p>
<code class='output'>2008-11-17T13:07:54-08:00</code>
</p>
</td>
</tr>
<tr>
<td>
<p class='name'><strong>Date to String</strong></p>
<p>Convert a date to short format.</p>
</td>
<td class='align-center'>
<p>
<code class='filter'>{% raw %}{{ site.time | date_to_string }}{% endraw %}</code>
</p>
<p>
<code class='output'>17 Nov 2008</code>
</p>
</td>
</tr>
<tr>
<td>
<p class='name'><strong>Date to Long String</strong></p>
<p>Format a date to long format.</p>
</td>
<td class='align-center'>
<p>
<code class='filter'>{% raw %}{{ site.time | date_to_long_string }}{% endraw %}</code>
</p>
<p>
<code class='output'>17 November 2008</code>
</p>
</td>
</tr>
<tr>
<td>
<p class='name'><strong>XML Escape</strong></p>
<p>Escape some text for use in XML.</p>
</td>
<td class='align-center'>
<p>
<code class='filter'>{% raw %}{{ page.content | xml_escape }}{% endraw %}</code>
</p>
</td>
</tr>
<tr>
<td>
<p class='name'><strong>CGI Escape</strong></p>
<p>
CGI escape a string for use in a URL. Replaces any special characters
with appropriate %XX replacements.
</p>
</td>
<td class='align-center'>
<p>
<code class='filter'>{% raw %}{{ “foo,bar;baz?” | cgi_escape }}{% endraw %}</code>
</p>
<p>
<code class='output'>foo%2Cbar%3Bbaz%3F</code>
</p>
</td>
</tr>
<tr>
<td>
<p class='name'><strong>Number of Words</strong></p>
<p>Count the number of words in some text.</p>
</td>
<td class='align-center'>
<p>
<code class='filter'>{% raw %}{{ page.content | number_of_words }}{% endraw %}</code>
</p>
<p>
<code class='output'>1337</code>
</p>
</td>
</tr>
<tr>
<td>
<p class='name'><strong>Array to Sentence</strong></p>
<p>Convert an array into a sentence. Useful for listing tags.</p>
</td>
<td class='align-center'>
<p>
<code class='filter'>{% raw %}{{ page.tags | array_to_sentence_string }}{% endraw %}</code>
</p>
<p>
<code class='output'>foo, bar, and baz</code>
</p>
</td>
</tr>
<tr>
<td>
<p class='name'><strong>Textilize</strong></p>
<p>Convert a Textile-formatted string into HTML, formatted via RedCloth</p>
</td>
<td class='align-center'>
<p>
<code class='filter'>{% raw %}{{ page.excerpt | textilize }}{% endraw %}</code>
</p>
</td>
</tr>
<tr>
<td>
<p class='name'><strong>Markdownify</strong></p>
<p>Convert a Markdown-formatted string into HTML.</p>
</td>
<td class='align-center'>
<p>
<code class='filter'>{% raw %}{{ page.excerpt | markdownify }}{% endraw %}</code>
</p>
</td>
</tr>
</tbody>
</table>
</div>
## Tags
### Includes
If you have small page fragments that you wish to include in multiple places on
your site, you can use the `include` tag.
{% highlight ruby %}
{% raw %}{% include sig.md %}{% endraw %}
{% endhighlight %}
Jekyll expects all include files to be placed in an `_includes` directory at the
root of your source directory. This will embed the contents of
`<source>/_includes/sig.md` into the calling file.
### Code snippet highlighting
Jekyll has built in support for syntax highlighting of [over 100
languages](http://pygments.org/languages/) thanks to
[Pygments](http://pygments.org/). In order to take advantage of this you’ll need
to have Pygments installed, and the `pygmentize` binary must be in your `$PATH`.
When you run Jekyll, make sure you run it with [Pygments enabled](../extras).
To render a code block with syntax highlighting, surround your code as follows:
{% highlight text %}
{% raw %}
{% highlight ruby %}
def foo
puts 'foo'
end
{% endhighlight %}
{% endraw %}
{% endhighlight %}
The argument to the `highlight` tag (`ruby` in the example above) is the
language identifier. To find the appropriate identifier to use for the language
you want to highlight, look for the “short name” on the [Lexers
page](http://pygments.org/docs/lexers/).
#### Line numbers
There is a second argument to `highlight` called `linenos` that is optional.
Including the `linenos` argument will force the highlighted code to include line
numbers. For instance, the following code block would include line numbers next
to each line:
{% highlight text %}
{% raw %}
{% highlight ruby linenos %}
def foo
puts 'foo'
end
{% endhighlight %}
{% endraw %}
{% endhighlight %}
#### Stylesheets for syntax highlighting
In order for the highlighting to show up, you’ll need to include a highlighting
stylesheet. For an example stylesheet you can look at
[syntax.css](http://github.com/mojombo/tpw/tree/master/css/syntax.css). These
are the same styles as used by GitHub and you are free to use them for your own
site. If you use `linenos`, you might want to include an additional CSS class
definition for the `.lineno` class in `syntax.css` to distinguish the line
numbers from the highlighted code.
### Post URL
If you would like to include a link to a post on your site, the `post_url` tag
will generate the correct permalink URL for the post you specify.
{% highlight text %}
{% raw %}
{% post_url 2010-07-21-name-of-post %}
{% endraw %}
{% endhighlight %}
There is no need to include the file extension when using the `post_url` tag.
You can also use this tag to create a link to a post in Markdown as follows:
{% highlight text %}
{% raw %}
[Name of Link]({% post_url 2010-07-21-name-of-post %})
{% endraw %}
{% endhighlight %}

127
site/docs/troubleshooting.md Normal file
View File

@@ -0,0 +1,127 @@
---
layout: docs
title: Troubleshooting
prev_section: contributing
next_section: sites
permalink: /docs/troubleshooting/
---
If you ever run into problems installing or using Jekyll, here’s a few tips that might be of help. If the problem you’re experiencing isn’t covered below, please [report an issue](https://github.com/mojombo/jekyll/issues/new) so the Jekyll community can make everyone’s experience better.
## Installation Problems
If you encounter errors during gem installation, you may need to install
the header files for compiling extension modules for ruby 1.9.1. This
can be done on Ubuntu or Debian by running:
{% highlight bash %}
sudo apt-get install ruby1.9.1-dev
{% endhighlight %}
On Red Hat, CentOS, and Fedora systems you can do this by running:
{% highlight bash %}
sudo yum install ruby-devel
{% endhighlight %}
On [NearlyFreeSpeech](http://nearlyfreespeech.net/) you need to run the command with the following environment variable:
{% highlight bash %}
RB_USER_INSTALL=true gem install jekyll
{% endhighlight %}
On OSX, you may need to update RubyGems:
{% highlight bash %}
sudo gem update --system
{% endhighlight %}
To install RubyGems on Gentoo:
{% highlight bash %}
sudo emerge -av dev-ruby/rubygems
{% endhighlight %}
On Windows, you may need to install [RubyInstaller
DevKit](http://wiki.github.com/oneclick/rubyinstaller/development-kit).
## Problems running Jekyll
On Debian or Ubuntu, you may need to add /var/lib/gems/1.8/bin/ to your path in order to have the `jekyll` executable be available in your Terminal.
## Base-URL Problems
If you are using base-url option like:
{% highlight bash %}
jekyll serve --baseurl '/blog'
{% endhighlight %}
… then make sure that you access the site at:
{% highlight bash %}
http://localhost:4000/blog/index.html
{% endhighlight %}
It won’t work to just access:
{% highlight bash %}
http://localhost:4000/blog
{% endhighlight %}
## Configuration problems
The order of precedence for conflicting [configuration settings](../configuration) is as follows:
1. Command-line flags
2. Configuration file settings
3. Defaults
That is: defaults are overridden by options specified in `_config.yml`, and flags specified at the command-line will override all other settings specified elsewhere.
## Markup Problems
The various markup engines that Jekyll uses may have some issues. This
page will document them to help others who may run into the same
problems.
### Maruku
If your link has characters that need to be escaped, you need to use
this syntax:
{% highlight text %}
![Alt text](http://yuml.me/diagram/class/[Project]->[Task])
{% endhighlight %}
If you have an empty tag, i.e. `<script src="js.js"></script>`, Maruku
transforms this into `<script src="js.js" />`. This causes problems in
Firefox and possibly other browsers and is [discouraged in
XHTML.](http://www.w3.org/TR/xhtml1/#C_3) An easy fix is to put a space
between the opening and closing tags.
### RedCloth
Versions 4.1.1 and higher do not obey the notextile tag. [This is a known
bug](http://aaronqian.com/articles/2009/04/07/redcloth-ate-my-notextile.html)
and will hopefully be fixed for 4.2. You can still use 4.1.9, but the
test suite requires that 4.1.0 be installed. If you use a version of
RedCloth that does not have the notextile tag, you may notice that
syntax highlighted blocks from Pygments are not formatted correctly,
among other things. If you’re seeing this just install 4.1.0.
### Liquid
The latest version, version 2.0, seems to break the use of `{{ "{{" }}` in
templates. Unlike previous versions, using `{{ "{{" }}` in 2.0 triggers the
following error:
{% highlight bash %}
'{{ "{{" }}' was not properly terminated with regexp: /\}\}/ (Liquid::SyntaxError)
{% endhighlight %}
<div class="note">
<h5>Please report issues you encounter!</h5>
<p>If you come across a bug, please <a href="https://github.com/mojombo/jekyll/issues/new">create an issue</a> on GitHub describing the problem and any work-arounds you find so we can document it here for others.</p>
</div>

58
site/docs/usage.md Normal file
View File

@@ -0,0 +1,58 @@
---
layout: docs
title: Basic Usage
prev_section: installation
next_section: structure
permalink: /docs/usage/
---
The Jekyll gem makes a `jekyll` executable available to you in your Terminal
window. You can use this command in a number of ways:
{% highlight bash %}
$ jekyll build
# => The current folder will be generated into ./_site
$ jekyll build --destination <destination>
# => The current folder will be generated into <destination>
$ jekyll build --source <source> --destination <destination>
# => The <source> folder will be generated into <destination>
$ jekyll build --watch
# => The current folder will be generated into ./_site,
# watched for changes, and regenerated automatically.
{% endhighlight %}
Jekyll also comes with a built-in development server that will allow you to
preview what the generated site will look like in your browser locally.
{% highlight bash %}
$ jekyll serve
# => A development server will run at http://localhost:4000/
$ jekyll serve --watch
# => As above, but watch for changes and regenerate automatically.
{% endhighlight %}
This is just a few of the available [configuration options](../configuration).
Many configuration options can either be specified as flags on the command line,
or alternatively (and more commonly) they can be specified in a `_config.yml`
file at the root of the source directory. Jekyll will automatically use the
options from this file when run. For example, if you place the following lines
in your `_config.yml` file:
{% highlight yaml %}
source: _source
destination: _deploy
{% endhighlight %}
Then the following two commands will be equivalent:
{% highlight bash %}
$ jekyll build
$ jekyll build --source _source --destination _deploy
{% endhighlight %}
For more about the possible configuration options, see the
[configuration](../configuration) page.

312
site/docs/variables.md Normal file
View File

@@ -0,0 +1,312 @@
---
layout: docs
title: Variables
prev_section: pages
next_section: migrations
permalink: /docs/variables/
---
Jekyll traverses your site looking for files to process. Any files with [YAML
Front Matter](../frontmatter) are subject to processing. For each of these
files, Jekyll makes a variety of data available via the [Liquid templating
system](http://wiki.github.com/shopify/liquid/liquid-for-designers). The
following is a reference of the available data.
## Global Variables
<div class="mobile-side-scroller">
<table>
<thead>
<tr>
<th>Variable</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><p><code>site</code></p></td>
<td><p>
Sitewide information + configuration settings from
<code>_config.yml</code>. See below for details.
</p></td>
</tr>
<tr>
<td><p><code>page</code></p></td>
<td><p>
Page specific information + the <a href="../frontmatter">YAML Front
Matter</a>. Custom variables set via the YAML front matter will be
available here. See below for details.
</p></td>
</tr>
<tr>
<td><p><code>content</code></p></td>
<td><p>
In layout files, the rendered content of the Post or Page being wrapped.
Not defined in Post or Page files.
</p></td>
</tr>
<tr>
<td><p><code>paginator</code></p></td>
<td><p>
When the <code>paginate</code> configuration option is set, this
variable becomes available for use. See <a
href="../pagination">Pagination</a> for details.
</p></td>
</tr>
</tbody>
</table>
</div>
## Site Variables
<div class="mobile-side-scroller">
<table>
<thead>
<tr>
<th>Variable</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><p><code>site.time</code></p></td>
<td><p>
The current time (when you run the <code>jekyll</code> command).
</p></td>
</tr>
<tr>
<td><p><code>site.posts</code></p></td>
<td><p>
A reverse chronological list of all Posts.
</p></td>
</tr>
<tr>
<td><p><code>site.related_posts</code></p></td>
<td><p>
If the page being processed is a Post, this contains a list of up to ten
related Posts. By default, these are low quality but fast to compute.
For high quality but slow to compute results, run the
<code>jekyll</code> command with the <code>--lsi</code> (latent semantic
indexing) option.
</p></td>
</tr>
<tr>
<td><p><code>site.categories.CATEGORY</code></p></td>
<td><p>
The list of all Posts in category <code>CATEGORY</code>.
</p></td>
</tr>
<tr>
<td><p><code>site.tags.TAG</code></p></td>
<td><p>
The list of all Posts with tag <code>TAG</code>.
</p></td>
</tr>
<tr>
<td><p><code>site.[CONFIGURATION_DATA]</code></p></td>
<td><p>
All the variables set via the command line and your
<code>_config.yml</code> are available through the <code>site</code>
variable. For example, if you have <code>url: http://mysite.com</code>
in your configuration file, then in your Posts and Pages it will be
stored in <code>site.url</code>. Jekyll does not parse changes to
<code>_config.yml</code> in <code>watch</code> mode, you must restart
Jekyll to see changes to variables.
</p></td>
</tr>
</tbody>
</table>
</div>
## Page Variables
<div class="mobile-side-scroller">
<table>
<thead>
<tr>
<th>Variable</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><p><code>page.content</code></p></td>
<td><p>
The un-rendered content of the Page.
</p></td>
</tr>
<tr>
<td><p><code>page.title</code></p></td>
<td><p>
The title of the Post.
</p></td>
</tr>
<tr>
<td><p><code>page.excerpt</code></p></td>
<td><p>
The un-rendered excerpt of the Page.
</p></td>
</tr>
<tr>
<td><p><code>page.url</code></p></td>
<td><p>
The URL of the Post without the domain, but
with a leading slash, e.g.
<code>/2008/12/14/my-post.html</code>
</p></td>
</tr>
<tr>
<td><p><code>page.date</code></p></td>
<td><p>
The Date assigned to the Post. This can be overridden in a Post’s front
matter by specifying a new date/time in the format
<code>YYYY-MM-DD HH:MM:SS</code>
</p></td>
</tr>
<tr>
<td><p><code>page.id</code></p></td>
<td><p>
An identifier unique to the Post (useful in RSS feeds). e.g.
<code>/2008/12/14/my-post</code>
</p></td>
</tr>
<tr>
<td><p><code>page.categories</code></p></td>
<td><p>
The list of categories to which this post belongs. Categories are
derived from the directory structure above the <code>_posts</code>
directory. For example, a post at
<code>/work/code/_posts/2008-12-24-closures.md</code> would have this
field set to <code>['work', 'code']</code>. These can also be specified
in the <a href="../frontmatter">YAML Front Matter</a>.
</p></td>
</tr>
<tr>
<td><p><code>page.tags</code></p></td>
<td><p>
The list of tags to which this post belongs. These can be specified in
the <a href="../frontmatter">YAML Front Matter</a>.
</p></td>
</tr>
<tr>
<td><p><code>page.path</code></p></td>
<td><p>
The path to the raw post or page. Example usage: Linking back to the
page or post's source on GitHub. This can be overridden in the
<a href="../frontmatter">YAML Front Matter</a>.
</p></td>
</tr>
</tbody>
</table>
</div>
<div class="note">
<h5>ProTip™: Use custom front-matter</h5>
<p>
Any custom front matter that you specify will be available under
<code>page</code>. For example, if you specify <code>custom_css: true</code>
in a page’s front matter, that value will be available as
<code>page.custom_css</code>.
</p>
</div>
## Paginator
<div class="mobile-side-scroller">
<table>
<thead>
<tr>
<th>Variable</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><p><code>paginator.per_page</code></p></td>
<td><p>Number of Posts per page.</p></td>
</tr>
<tr>
<td><p><code>paginator.posts</code></p></td>
<td><p>Posts available for that page.</p></td>
</tr>
<tr>
<td><p><code>paginator.total_posts</code></p></td>
<td><p>Total number of Posts.</p></td>
</tr>
<tr>
<td><p><code>paginator.total_pages</code></p></td>
<td><p>Total number of Pages.</p></td>
</tr>
<tr>
<td><p><code>paginator.page</code></p></td>
<td><p>The number of the current page.</p></td>
</tr>
<tr>
<td><p><code>paginator.previous_page</code></p></td>
<td><p>The number of the previous page.</p></td>
</tr>
<tr>
<td><p><code>paginator.previous_page_path</code></p></td>
<td><p>The path to the previous page.</p></td>
</tr>
<tr>
<td><p><code>paginator.next_page</code></p></td>
<td><p>The number of the next page.</p></td>
</tr>
<tr>
<td><p><code>paginator.next_page_path</code></p></td>
<td><p>The path to the next page.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="note info">
<h5>Paginator variable availability</h5>
<p>
These are only available in index files, however they can be located in a
subdirectory, such as <code>/blog/index.html</code>.
</p>
</div>