Merge pull request #918 from mojombo/awesome-docs
Clean up site docs to prepare for 1.0 release.
This commit is contained in:
Parker Moore
commit
3e968ad14f
|
|
@ -15,9 +15,10 @@ following in mind:
|
||||||
would be appreciated, and once merged it will be transferred over to the main
|
would be appreciated, and once merged it will be transferred over to the main
|
||||||
wiki.
|
wiki.
|
||||||
* If your contribution changes any Jekyll behavior, make sure to update the
|
* If your contribution changes any Jekyll behavior, make sure to update the
|
||||||
documentation. It lives in site/_posts. If the docs are missing information,
|
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 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.
|
* Please follow the [GitHub Ruby Styleguide](https://github.com/styleguide/ruby)
|
||||||
|
when modifying Ruby code.
|
||||||
|
|
||||||
Test Dependencies
|
Test Dependencies
|
||||||
-----------------
|
-----------------
|
||||||
|
|
|
||||||
|
|
@ -5,68 +5,80 @@ prev_section: structure
|
||||||
next_section: frontmatter
|
next_section: frontmatter
|
||||||
---
|
---
|
||||||
|
|
||||||
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.
|
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
|
## Configuration Settings
|
||||||
|
|
||||||
### Global Configuration
|
### Global Configuration
|
||||||
|
|
||||||
The table below lists the available settings for Jekyll, and the various <code class="option">options</code> (specifed in the configuration file) and <code class="flag">flags</code> (specified on the command-line) that control them.
|
The table below lists the available settings for Jekyll, and the various <code
|
||||||
|
class="option">options</code> (specifed in the configuration file) and <code
|
||||||
|
class="flag">flags</code> (specified on the command-line) that control them.
|
||||||
|
|
||||||
<table>
|
<table>
|
||||||
<thead>
|
<thead>
|
||||||
<tr>
|
<tr>
|
||||||
<th>Setting</th>
|
<th>Setting</th>
|
||||||
<th><span class="option">Options</span> and <span class="flag">Flags</span></th>
|
<th>
|
||||||
|
<span class="option">Options</span> and <span class="flag">Flags</span>
|
||||||
|
</th>
|
||||||
</tr>
|
</tr>
|
||||||
</thead>
|
</thead>
|
||||||
<tbody>
|
<tbody>
|
||||||
<tr class='setting'>
|
<tr class='setting'>
|
||||||
<td>
|
<td>
|
||||||
<p class='name'><strong>Site Source</strong></p>
|
<p class='name'><strong>Site Source</strong></p>
|
||||||
<p class='description'>Changes the directory where Jekyll will look to transform files</p>
|
<p class='description'>Change the directory where Jekyll will read files</p>
|
||||||
</td>
|
</td>
|
||||||
<td class="align-center">
|
<td class="align-center">
|
||||||
<p><code class="option">source: [string]</code></p>
|
<p><code class="option">source: DIR</code></p>
|
||||||
<p><code class="flag">--source [source]</code></p>
|
<p><code class="flag">-s, --source DIR</code></p>
|
||||||
</td>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr class='setting'>
|
<tr class='setting'>
|
||||||
<td>
|
<td>
|
||||||
<p class='name'><strong>Site Destination</strong></p>
|
<p class='name'><strong>Site Destination</strong></p>
|
||||||
<p class='description'>Changes the directory where Jekyll will write files to</p>
|
<p class='description'>Change the directory where Jekyll will write files</p>
|
||||||
</td>
|
</td>
|
||||||
<td class="align-center">
|
<td class="align-center">
|
||||||
<p><code class="option">destination: [string]</code></p>
|
<p><code class="option">destination: DIR</code></p>
|
||||||
<p><code class="flag">--destination</code></p>
|
<p><code class="flag">-d, --destination DIR</code></p>
|
||||||
</td>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr class='setting'>
|
<tr class='setting'>
|
||||||
<td>
|
<td>
|
||||||
<p class='name'><strong>Safe</strong></p>
|
<p class='name'><strong>Safe</strong></p>
|
||||||
<p class='description'>Disables <a href="../plugins">custom plugins</a>.</p>
|
<p class='description'>Disable <a href="../plugins">custom plugins</a>.</p>
|
||||||
</td>
|
</td>
|
||||||
<td class="align-center">
|
<td class="align-center">
|
||||||
<p><code class="option">safe: [boolean]</code></p>
|
<p><code class="option">safe: BOOL</code></p>
|
||||||
<p><code class="flag">--safe</code></p>
|
<p><code class="flag">--safe</code></p>
|
||||||
</td>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr class='setting'>
|
<tr class='setting'>
|
||||||
<td>
|
<td>
|
||||||
<p class='name'><strong>Exclude</strong></p>
|
<p class='name'><strong>Exclude</strong></p>
|
||||||
<p class="description">A list of directories and files to exclude from the conversion</p>
|
<p class="description">Exclude directories and/or files from the conversion</p>
|
||||||
</td>
|
</td>
|
||||||
<td class='align-center'>
|
<td class='align-center'>
|
||||||
<p><code class="option">exclude: [dir1, file1, dir2]</code></p>
|
<p><code class="option">exclude: [DIR, FILE, ...]</code></p>
|
||||||
</td>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr class='setting'>
|
<tr class='setting'>
|
||||||
<td>
|
<td>
|
||||||
<p class='name'><strong>Include</strong></p>
|
<p class='name'><strong>Include</strong></p>
|
||||||
<p class="description">A list of directories and files to specifically include in the conversion. <code>.htaccess</code> is a good example since dotfiles are excluded by default.</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>
|
||||||
<td class='align-center'>
|
<td class='align-center'>
|
||||||
<p><code class="option">include: [dir1, file1, dir2]</code></p>
|
<p><code class="option">include: [DIR, FILE, ...]</code></p>
|
||||||
</td>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
|
|
@ -85,90 +97,58 @@ The table below lists the available settings for Jekyll, and the various <code c
|
||||||
<tr class='setting'>
|
<tr class='setting'>
|
||||||
<td>
|
<td>
|
||||||
<p class='name'><strong>Regeneration</strong></p>
|
<p class='name'><strong>Regeneration</strong></p>
|
||||||
<p class='description'>Enables auto-regeneration of the site when files are modified. Off by default.</p>
|
<p class='description'>Enable auto-regeneration of the site when files are modified.</p>
|
||||||
</td>
|
</td>
|
||||||
<td class="align-center">
|
<td class="align-center">
|
||||||
<p><code class="flag">--watch</code></p>
|
<p><code class="flag">-w, --watch</code></p>
|
||||||
</td>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr class='setting'>
|
<tr class='setting'>
|
||||||
<td>
|
<td>
|
||||||
<p class='name'><strong>URL</strong></p>
|
<p class='name'><strong>Configuration</strong></p>
|
||||||
<p class='description'>Sets <code>site.url</code>, useful for environment switching</p>
|
<p class="description">Specify a config file. Overrides settings in <code>_config.yml</code></p>
|
||||||
</td>
|
|
||||||
<td class="align-center">
|
|
||||||
<p><code class="option">url: [URL]</code></p>
|
|
||||||
<p><code class="flag">--url [URL]</code></p>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr class='setting'>
|
|
||||||
<td>
|
|
||||||
<p class='name'><strong>Markdown</strong></p>
|
|
||||||
<p class="description">Uses RDiscount or <code>[engine]</code> instead of Maruku.</p>
|
|
||||||
</td>
|
</td>
|
||||||
<td class='align-center'>
|
<td class='align-center'>
|
||||||
<p><code class="option">markdown: [engine]</code></p>
|
<p><code class="flag">--config FILE</code></p>
|
||||||
<p><code class="flag">--markdown [rdiscount|kramdown|redcarpet]</code></p>
|
|
||||||
</td>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr class='setting'>
|
<tr class='setting'>
|
||||||
<td>
|
<td>
|
||||||
<p class='name'><strong>Pygments</strong></p>
|
<p class='name'><strong>Drafts</strong></p>
|
||||||
<p class="description">Enables highlight tag with Pygments.</p>
|
<p class="description">Process and render draft posts.</p>
|
||||||
</td>
|
</td>
|
||||||
<td class='align-center'>
|
<td class='align-center'>
|
||||||
<p><code class="option">pygments: [boolean]</code></p>
|
<p><code class="flag">--drafts</code></p>
|
||||||
<p><code class="flag">--pygments</code></p>
|
|
||||||
</td>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr class='setting'>
|
<tr class='setting'>
|
||||||
<td>
|
<td>
|
||||||
<p class='name'><strong>Future</strong></p>
|
<p class='name'><strong>Future</strong></p>
|
||||||
<p class="description">Publishes posts with a future date</p>
|
<p class="description">Publish posts with a future date.</p>
|
||||||
</td>
|
</td>
|
||||||
<td class='align-center'>
|
<td class='align-center'>
|
||||||
<p><code class="option">future: [boolean]</code></p>
|
<p><code class="option">future: BOOL</code></p>
|
||||||
<p><code class="flag">--future</code></p>
|
<p><code class="flag">--future</code></p>
|
||||||
</td>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr class='setting'>
|
<tr class='setting'>
|
||||||
<td>
|
<td>
|
||||||
<p class='name'><strong>LSI</strong></p>
|
<p class='name'><strong>LSI</strong></p>
|
||||||
<p class="description">Produces an index for related posts.</p>
|
<p class="description">Produce an index for related posts.</p>
|
||||||
</td>
|
</td>
|
||||||
<td class='align-center'>
|
<td class='align-center'>
|
||||||
<p><code class="option">lsi: [boolean]</code></p>
|
<p><code class="option">lsi: BOOL</code></p>
|
||||||
<p><code class="flag">--lsi</code></p>
|
<p><code class="flag">--lsi</code></p>
|
||||||
</td>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr class='setting'>
|
|
||||||
<td>
|
|
||||||
<p class='name'><strong>Permalink</strong></p>
|
|
||||||
<p class="description">Controls the URLs that posts are generated with. Please refer to the <a href="../permalinks">Permalinks</a> page for more info.</p>
|
|
||||||
</td>
|
|
||||||
<td class='align-center'>
|
|
||||||
<p><code class="option">permalink: [style]</code></p>
|
|
||||||
<p><code class="flag">--permalink [style]</code></p>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr class='setting'>
|
|
||||||
<td>
|
|
||||||
<p class='name'><strong>Pagination</strong></p>
|
|
||||||
<p class="description">Splits your posts up over multiple subdirectories called "page2", "page3", ... "pageN"</p>
|
|
||||||
</td>
|
|
||||||
<td class='align-center'>
|
|
||||||
<p><code class="option">paginate: [per_page]</code></p>
|
|
||||||
<p><code class="flag">--paginate [per_page]</code></p>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr class='setting'>
|
<tr class='setting'>
|
||||||
<td>
|
<td>
|
||||||
<p class='name'><strong>Limit Posts</strong></p>
|
<p class='name'><strong>Limit Posts</strong></p>
|
||||||
<p class="description">Limits the number of posts to parse and publish</p>
|
<p class="description">Limit the number of posts to parse and publish.</p>
|
||||||
</td>
|
</td>
|
||||||
<td class='align-center'>
|
<td class='align-center'>
|
||||||
<p><code class="option">limit_posts: [max_posts]</code></p>
|
<p><code class="option">limit_posts: NUM</code></p>
|
||||||
<p><code class="flag">--limit_posts [max_posts]</code></p>
|
<p><code class="flag">--limit_posts NUM</code></p>
|
||||||
</td>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
|
|
@ -191,31 +171,31 @@ before your site is served.
|
||||||
<tr class='setting'>
|
<tr class='setting'>
|
||||||
<td>
|
<td>
|
||||||
<p class='name'><strong>Local Server Port</strong></p>
|
<p class='name'><strong>Local Server Port</strong></p>
|
||||||
<p class='description'>Changes the port that the Jekyll server will run on</p>
|
<p class='description'>Listen on the given port.</p>
|
||||||
</td>
|
</td>
|
||||||
<td class="align-center">
|
<td class="align-center">
|
||||||
<p><code class="option">port: [integer]</code></p>
|
<p><code class="option">port: PORT</code></p>
|
||||||
<p><code class="flag">--port [port]</code></p>
|
<p><code class="flag">--port PORT</code></p>
|
||||||
</td>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr class='setting'>
|
<tr class='setting'>
|
||||||
<td>
|
<td>
|
||||||
<p class='name'><strong>Local Server Hostname</strong></p>
|
<p class='name'><strong>Local Server Hostname</strong></p>
|
||||||
<p class='description'>Changes the hostname that the Jekyll server will run on</p>
|
<p class='description'>Listen at the given hostname.</p>
|
||||||
</td>
|
</td>
|
||||||
<td class="align-center">
|
<td class="align-center">
|
||||||
<p><code class="option">host: [string]</code></p>
|
<p><code class="option">host: HOSTNAME</code></p>
|
||||||
<p><code class="flag">--host [hostname]</code></p>
|
<p><code class="flag">--host HOSTNAME</code></p>
|
||||||
</td>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr class='setting'>
|
<tr class='setting'>
|
||||||
<td>
|
<td>
|
||||||
<p class='name'><strong>Base URL</strong></p>
|
<p class='name'><strong>Base URL</strong></p>
|
||||||
<p class='description'>Serve website from a given base URL</p>
|
<p class='description'>Serve website with the given base URL</p>
|
||||||
</td>
|
</td>
|
||||||
<td class="align-center">
|
<td class="align-center">
|
||||||
<p><code class="option">baseurl: [BASE_URL]</code></p>
|
<p><code class="option">baseurl: URL</code></p>
|
||||||
<p><code class="flag">--baseurl [url]</code></p>
|
<p><code class="flag">--baseurl URL</code></p>
|
||||||
</td>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
|
|
@ -223,14 +203,38 @@ before your site is served.
|
||||||
|
|
||||||
<div class="note warning">
|
<div class="note warning">
|
||||||
<h5>Do not use tabs in configuration files</h5>
|
<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>
|
<p>
|
||||||
|
This will either lead to parsing errors, or Jekyll will revert to the
|
||||||
|
default settings. Use spaces instead.
|
||||||
|
</p>
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
## Default Configuration
|
## 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.
|
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 %}
|
{% highlight yaml %}
|
||||||
|
source: .
|
||||||
|
destination: ./_site
|
||||||
|
plugins: ./_plugins
|
||||||
|
layouts: ./_layouts
|
||||||
|
keep_files: ['.git','.svn']
|
||||||
|
|
||||||
|
future: true
|
||||||
|
pygments: false
|
||||||
|
|
||||||
|
markdown: maruku
|
||||||
|
permalink: date
|
||||||
|
include: ['.htaccess']
|
||||||
|
paginate_path: 'page:num'
|
||||||
|
|
||||||
|
markdown_ext: markdown,mkd,mkdn,md
|
||||||
|
textile_ext: textile
|
||||||
|
|
||||||
|
excerpt_separator: "\n\n"
|
||||||
|
|
||||||
safe: false
|
safe: false
|
||||||
watch: false
|
watch: false
|
||||||
server: false
|
server: false
|
||||||
|
|
@ -238,16 +242,7 @@ host: 0.0.0.0
|
||||||
port: 4000
|
port: 4000
|
||||||
baseurl: /
|
baseurl: /
|
||||||
url: http://localhost:4000
|
url: http://localhost:4000
|
||||||
|
|
||||||
source: .
|
|
||||||
destination: ./_site
|
|
||||||
plugins: ./_plugins
|
|
||||||
|
|
||||||
future: true
|
|
||||||
lsi: false
|
lsi: false
|
||||||
pygments: false
|
|
||||||
markdown: maruku
|
|
||||||
permalink: date
|
|
||||||
|
|
||||||
maruku:
|
maruku:
|
||||||
use_tex: false
|
use_tex: false
|
||||||
|
|
@ -259,11 +254,15 @@ maruku:
|
||||||
rdiscount:
|
rdiscount:
|
||||||
extensions: []
|
extensions: []
|
||||||
|
|
||||||
|
redcarpet:
|
||||||
|
extensions: []
|
||||||
|
|
||||||
kramdown:
|
kramdown:
|
||||||
auto_ids: true,
|
auto_ids: true
|
||||||
footnote_nr: 1
|
footnote_nr: 1
|
||||||
entity_output: as_char
|
entity_output: as_char
|
||||||
toc_levels: 1..6
|
toc_levels: 1..6
|
||||||
|
smart_quotes: lsquo,rsquo,ldquo,rdquo
|
||||||
use_coderay: false
|
use_coderay: false
|
||||||
|
|
||||||
coderay:
|
coderay:
|
||||||
|
|
@ -274,4 +273,6 @@ kramdown:
|
||||||
coderay_bold_every: 10
|
coderay_bold_every: 10
|
||||||
coderay_css: style
|
coderay_css: style
|
||||||
|
|
||||||
|
redcloth:
|
||||||
|
hard_breaks: true
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
|
||||||
|
|
@ -5,62 +5,83 @@ prev_section: deployment-methods
|
||||||
next_section: troubleshooting
|
next_section: troubleshooting
|
||||||
---
|
---
|
||||||
|
|
||||||
Contributions to Jekyll are always welcome, however there’s a few things that you should keep in mind to improve your chances of having your changes merged in.
|
So you've got an awesome idea to throw into Jekyll. Great! Please keep the
|
||||||
|
following in mind:
|
||||||
|
|
||||||
## Workflow
|
* 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
|
||||||
Here’s the most typical way to get your change merged into the project:
|
[Shoulda](http://github.com/thoughtbot/shoulda/tree/master) and
|
||||||
|
[RR](http://github.com/btakita/rr/tree/master).
|
||||||
1. Fork the project [on GitHub](https://github.com/mojombo/jekyll) and clone it down to your local machine.
|
* If it's a brand new feature, make sure to create a new
|
||||||
2. Create a topic branch to contain your change.
|
[Cucumber](https://github.com/cucumber/cucumber/) feature and reuse steps
|
||||||
3. Hack away, add tests. Not necessarily in that order.
|
where appropriate. Also, whipping up some documentation in your fork's wiki
|
||||||
4. Make sure all the existing tests still pass.
|
would be appreciated, and once merged it will be transferred over to the main
|
||||||
5. If necessary, rebase your commits into logical chunks, without errors.
|
wiki.
|
||||||
6. Push the branch up to your fork on GitHub.
|
* If your contribution adds or changes any Jekyll behavior, make sure to update
|
||||||
7. Create an issue on GitHub with a link to your branch.
|
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">
|
<div class="note warning">
|
||||||
<h5>Contributions will not be accepted without tests</h5>
|
<h5>Contributions will not be accepted without tests</h5>
|
||||||
<p>If you’re creating a small fix or patch to an existing feature, just
|
<p>
|
||||||
a simple test will do.</p>
|
If you’re creating a small fix or patch to an existing feature, just
|
||||||
|
a simple test will do.
|
||||||
|
</p>
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
## Tests
|
Test Dependencies
|
||||||
|
-----------------
|
||||||
|
|
||||||
We’re big on tests, so please be sure to include them. Please stay in the confines of the current test suite and use [Shoulda](https://github.com/thoughtbot/shoulda) and [RR](https://github.com/btakita/rr).
|
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
|
||||||
### Tests for brand-new features
|
you're all set!
|
||||||
|
|
||||||
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 `gh-pages` branch would be appreciated, so the main website can be updated as soon as your new feature is merged.
|
|
||||||
|
|
||||||
### 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 %}
|
{% highlight bash %}
|
||||||
$ bundle
|
$ bundle
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
Before you start, run the tests and make sure that they pass (to confirm
|
Before you start, run the tests and make sure that they pass (to confirm your
|
||||||
your environment is configured properly):
|
environment is configured properly):
|
||||||
|
|
||||||
{% highlight bash %}
|
{% highlight bash %}
|
||||||
$ rake test
|
$ rake test
|
||||||
$ rake features
|
$ rake features
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
## Common Gotchas
|
Workflow
|
||||||
|
--------
|
||||||
|
|
||||||
- If you want to bump the gem version, please put that in a separate
|
Here's the most direct way to get your work merged into the project:
|
||||||
commit. This way, the maintainers can control when the gem gets released.
|
|
||||||
- Try to keep your patch(es) based from [the latest commit on
|
* Fork the project.
|
||||||
mojombo/jekyll](https://github.com/mojombo/jekyll/commits/master). The easier it is to apply your work, the less work
|
* Clone down your fork: `git clone git://github.com/<username>/jekyll.git`
|
||||||
the maintainers have to do, which is always a good thing.
|
* Create a topic branch to contain your change: `git checkout -b my_awesome_feature`
|
||||||
- Please don’t tag your GitHub issue with labels like “fix” or “feature”.
|
* Hack away, add tests. Not necessarily in that order.
|
||||||
The maintainers actively read the issues and will label it once they come
|
* Make sure everything still passes by running `rake`.
|
||||||
across it.
|
* If necessary, rebase your commits into logical chunks, without errors.
|
||||||
|
* Push the branch up: `git push origin my_awesome_feature`
|
||||||
|
* 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">
|
<div class="note">
|
||||||
<h5>Let us know what could be better!</h5>
|
<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>
|
<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>
|
</div>
|
||||||
|
|
|
||||||
|
|
@ -5,99 +5,111 @@ prev_section: plugins
|
||||||
next_section: github-pages
|
next_section: github-pages
|
||||||
---
|
---
|
||||||
|
|
||||||
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.
|
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
|
## Pygments
|
||||||
|
|
||||||
If you want syntax highlighting via the `{{ "{% highlight " }}%}` tag in your
|
If you want syntax highlighting via the `{% raw %}{% highlight %}{% endraw %}`
|
||||||
posts, you’ll need to install [Pygments](http://pygments.org/).
|
tag in your posts, you’ll need to install [Pygments](http://pygments.org/).
|
||||||
|
|
||||||
### Installing Pygments on OSX
|
### Installing Pygments on OSX
|
||||||
|
|
||||||
Mac OS X (Leopard onwards) come preinstalled with Python, so on just about any OS X machine you can install Pygments simply by running:
|
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 %}
|
{% highlight bash %}
|
||||||
sudo easy_install Pygments
|
$ sudo easy_install Pygments
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
#### Installing Pygments using Homebrew
|
#### Installing Pygments using Homebrew
|
||||||
|
|
||||||
Alternatively, you can install Pygments with [Homebrew](http://mxcl.github.com/homebrew/), an excellent package manager for OS X:
|
Alternatively, you can install Pygments with
|
||||||
|
[Homebrew](http://mxcl.github.com/homebrew/), an excellent package manager for
|
||||||
|
OS X:
|
||||||
|
|
||||||
{% highlight bash %}
|
{% highlight bash %}
|
||||||
brew install python
|
$ brew install python
|
||||||
# export PATH="/usr/local/share/python:${PATH}"
|
# export PATH="/usr/local/share/python:${PATH}"
|
||||||
easy_install pip
|
$ easy_install pip
|
||||||
pip install --upgrade distribute
|
$ pip install --upgrade distribute
|
||||||
pip install pygments
|
$ pip install pygments
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
**ProTip™**: 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 [the Homebrew wiki](https://github.com/mxcl/homebrew/wiki/Homebrew-and-Python).
|
<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 [the Homebrew
|
||||||
|
wiki](https://github.com/mxcl/homebrew/wiki/Homebrew-and-Python).
|
||||||
|
</p>
|
||||||
|
</div>
|
||||||
|
|
||||||
#### Installing Pygments using MacPorts
|
#### Installing Pygments using MacPorts
|
||||||
|
|
||||||
If you use MacPorts, you can install Pygments by running:
|
If you use MacPorts, you can install Pygments by running:
|
||||||
|
|
||||||
{% highlight bash %}
|
{% highlight bash %}
|
||||||
sudo port install python25 py25-pygments
|
$ sudo port install python25 py25-pygments
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
Seriously though, you should check out [Homebrew](http://mxcl.github.com/homebrew/)—it’s awesome.
|
Seriously though, you should check out
|
||||||
|
[Homebrew](http://mxcl.github.com/homebrew/)—it’s awesome.
|
||||||
|
|
||||||
### Installing Pygments on Arch Linux
|
### Installing Pygments on Arch Linux
|
||||||
|
|
||||||
You can install Pygments using the pacman package manager as follows:
|
You can install Pygments using the pacman package manager as follows:
|
||||||
|
|
||||||
{% highlight bash %}
|
{% highlight bash %}
|
||||||
sudo pacman -S python-pygments
|
$ sudo pacman -S python-pygments
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
Or to use python2 for Pygments:
|
Or to use python2 for Pygments:
|
||||||
|
|
||||||
{% highlight bash %}
|
{% highlight bash %}
|
||||||
sudo pacman -S python2-pygments
|
$ sudo pacman -S python2-pygments
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
### Installing Pygments on Ubuntu and Debian
|
### Installing Pygments on Ubuntu and Debian
|
||||||
|
|
||||||
{% highlight bash %}
|
{% highlight bash %}
|
||||||
sudo apt-get install python-pygments
|
$ sudo apt-get install python-pygments
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
### Installing Pygments on RedHat, Fedora, and CentOS
|
### Installing Pygments on RedHat, Fedora, and CentOS
|
||||||
|
|
||||||
{% highlight bash %}
|
{% highlight bash %}
|
||||||
sudo yum install python-pygments
|
$ sudo yum install python-pygments
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
### Installing Pygments on Gentoo
|
### Installing Pygments on Gentoo
|
||||||
|
|
||||||
{% highlight bash %}
|
{% highlight bash %}
|
||||||
sudo emerge -av dev-python/pygments
|
$ sudo emerge -av dev-python/pygments
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
## LaTeX Support
|
## LaTeX Support
|
||||||
|
|
||||||
Maruku comes with optional support for LaTeX to PNG rendering via
|
Maruku comes with optional support for LaTeX to PNG rendering via blahtex
|
||||||
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).
|
(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
|
## 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:
|
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 %}
|
{% highlight bash %}
|
||||||
sudo gem install rdiscount
|
$ sudo gem install rdiscount
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
And then run Jekyll with the following option:
|
And then specify RDiscount as the Markdown engine in your `_config.yml` file to
|
||||||
|
have Jekyll run with that option.
|
||||||
{% highlight bash %}
|
|
||||||
jekyll build --markdown rdiscount
|
|
||||||
{% endhighlight %}
|
|
||||||
|
|
||||||
Or, specify RDiscount as the markdown engine in your `_config.yml` file to have Jekyll run with that option by default (so you don’t have to specify the flag every time).
|
|
||||||
|
|
||||||
{% highlight bash %}
|
{% highlight bash %}
|
||||||
# In _config.yml
|
# In _config.yml
|
||||||
markdown: rdiscount
|
markdown: rdiscount
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -5,7 +5,11 @@ prev_section: configuration
|
||||||
next_section: posts
|
next_section: posts
|
||||||
---
|
---
|
||||||
|
|
||||||
The front-matter is where Jekyll starts to get really cool. Any files that contain a [YAML](http://yaml.org/) front matter block will be processed by Jekyll as special files. The front matter must be the first thing in the file and must take the form of sets of variables and values set between triple-dashed lines. Here is a basic example:
|
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 %}
|
{% highlight yaml %}
|
||||||
---
|
---
|
||||||
|
|
@ -14,11 +18,19 @@ title: Blogging Like a Hacker
|
||||||
---
|
---
|
||||||
{% endhighlight %}
|
{% 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.
|
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">
|
<div class="note warning">
|
||||||
<h5>UTF-8 Character Encoding Warning</h5>
|
<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>
|
<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>
|
</div>
|
||||||
|
|
||||||
## Predefined Global Variables
|
## Predefined Global Variables
|
||||||
|
|
@ -38,7 +50,13 @@ There are a number of predefined global variables that you can set in the front-
|
||||||
<p><code>layout</code></p>
|
<p><code>layout</code></p>
|
||||||
</td>
|
</td>
|
||||||
<td>
|
<td>
|
||||||
<p>If set, this specifies the layout file to use. Use the layout file name without file extension. Layout files must be placed in the <code>_layouts</code> directory.</p>
|
<p>
|
||||||
|
|
||||||
|
If set, this specifies the layout file to use. Use the layout file
|
||||||
|
name without file extension. Layout files must be placed in the
|
||||||
|
<code>_layouts</code> directory.
|
||||||
|
|
||||||
|
</p>
|
||||||
</td>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
|
|
@ -46,7 +64,13 @@ There are a number of predefined global variables that you can set in the front-
|
||||||
<p><code>permalink</code></p>
|
<p><code>permalink</code></p>
|
||||||
</td>
|
</td>
|
||||||
<td>
|
<td>
|
||||||
<p>If you need your processed 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>
|
<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>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
|
|
@ -54,7 +78,10 @@ There are a number of predefined global variables that you can set in the front-
|
||||||
<p><code>published</code></p>
|
<p><code>published</code></p>
|
||||||
</td>
|
</td>
|
||||||
<td>
|
<td>
|
||||||
<p>Set to false if you don’t want a post to show up when the site is generated.</p>
|
<p>
|
||||||
|
Set to false if you don’t want a specific post to show up when the
|
||||||
|
site is generated.
|
||||||
|
</p>
|
||||||
</td>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
|
|
@ -63,7 +90,16 @@ There are a number of predefined global variables that you can set in the front-
|
||||||
<p><code>categories</code></p>
|
<p><code>categories</code></p>
|
||||||
</td>
|
</td>
|
||||||
<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>
|
<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>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
|
|
@ -71,7 +107,13 @@ There are a number of predefined global variables that you can set in the front-
|
||||||
<p><code>tags</code></p>
|
<p><code>tags</code></p>
|
||||||
</td>
|
</td>
|
||||||
<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>
|
<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>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
|
|
@ -80,16 +122,16 @@ There are a number of predefined global variables that you can set in the front-
|
||||||
|
|
||||||
## Custom Variables
|
## Custom Variables
|
||||||
|
|
||||||
Any variables in the front matter that are not predefined are mixed into
|
Any variables in the front matter that are not predefined are mixed into the
|
||||||
the data that is sent to the Liquid templating engine during the
|
data that is sent to the Liquid templating engine during the conversion. For
|
||||||
conversion. For instance, if you set a title, you can use that in your
|
instance, if you set a title, you can use that in your layout to set the page
|
||||||
layout to set the page title:
|
title:
|
||||||
|
|
||||||
{% highlight html %}
|
{% highlight html %}
|
||||||
<!DOCTYPE HTML>
|
<!DOCTYPE HTML>
|
||||||
<html>
|
<html>
|
||||||
<head>
|
<head>
|
||||||
<title>{{ "{{ page.title " }}}}</title>
|
<title>{% raw %}{{ page.title }}{% endraw %}</title>
|
||||||
</head>
|
</head>
|
||||||
<body>
|
<body>
|
||||||
...
|
...
|
||||||
|
|
@ -97,8 +139,7 @@ layout to set the page title:
|
||||||
|
|
||||||
## Predefined Variables for Posts
|
## Predefined Variables for Posts
|
||||||
|
|
||||||
These are available out-of-the-box to be used in the front-matter for a
|
These are available out-of-the-box to be used in the front-matter for a post.
|
||||||
post.
|
|
||||||
|
|
||||||
<table>
|
<table>
|
||||||
<thead>
|
<thead>
|
||||||
|
|
@ -113,7 +154,10 @@ post.
|
||||||
<p><code>date</code></p>
|
<p><code>date</code></p>
|
||||||
</td>
|
</td>
|
||||||
<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>
|
<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>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
|
|
|
||||||
|
|
@ -5,30 +5,61 @@ prev_section: extras
|
||||||
next_section: deployment-methods
|
next_section: deployment-methods
|
||||||
---
|
---
|
||||||
|
|
||||||
[GitHub Pages](https://pages.github.com) are public web pages for users, organizations, and repositories, that are freely hosted on [GitHub](https://github.com/). 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.
|
[GitHub Pages](https://pages.github.com) are public web pages for users,
|
||||||
|
organizations, and repositories, that are freely hosted on
|
||||||
|
[GitHub](https://github.com/). 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
|
## Deploying Jekyll to GitHub Pages
|
||||||
|
|
||||||
GitHub Pages work by looking at certain branches of repositories on GitHub. There are two basic types of Pages available, user/organization Pages and project Pages. The way to deploy these two types of pages are nearly identical, except for a few minor details.
|
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
|
||||||
|
|
||||||
User and organization Pages live in a special GitHub repository dedicated to only the Pages files. This repository must be named after the account name. For example, [@mojombo’s user page repository](https://github.com/mojombo/mojombo.github.com) has the name `mojombo.github.com`.
|
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.com) has the name
|
||||||
|
`mojombo.github.com`.
|
||||||
|
|
||||||
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.
|
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">
|
<div class="note info">
|
||||||
<h5>Custom domains do not affect repository names</h5>
|
<h5>Custom domains do not affect repository names</h5>
|
||||||
<p>GitHub Pages are initially configured to live under the `username.github.com` subdomain, which is why repositories must be named this way <strong>even if a custom domain is being used</strong>.</p>
|
<p>
|
||||||
|
GitHub Pages are initially configured to live under the
|
||||||
|
<code>username.github.com</code> subdomain, which is why repositories must
|
||||||
|
be named this way <strong>even if a custom domain is being used</strong>.
|
||||||
|
</p>
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
### Project Pages
|
### 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 used to rendered using Jekyll, and the output will become available under a subpath of your user pages subdomain, such as `username.github.com/project` (unless a custom domain is specified—see below).
|
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.com/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.
|
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">
|
<div class="note">
|
||||||
<h5>GitHub Pages Documentation, Help, and Support</h5>
|
<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>
|
<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>
|
</div>
|
||||||
|
|
|
||||||
|
|
@ -4,30 +4,45 @@ title: Welcome
|
||||||
next_section: installation
|
next_section: installation
|
||||||
---
|
---
|
||||||
|
|
||||||
This site aims to be a comprehensive guide to Jekyll. We’ll cover everything from getting your site up and running, creating and managing your content, customizing the way your site works and looks, deploying to various environments, as well as some advice on participating in the future development of Jekyll itself.
|
This site aims to be a comprehensive guide to Jekyll. We’ll cover everything
|
||||||
|
from getting your site up and running, creating and managing your content,
|
||||||
|
customizing the way your site works and looks, deploying to various
|
||||||
|
environments, as well as some advice on participating in the future development
|
||||||
|
of Jekyll itself.
|
||||||
|
|
||||||
## So what is Jekyll, exactly?
|
## 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://liquidmarkup.org/) 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**.
|
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://liquidmarkup.org/)
|
||||||
|
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
|
## Quick-start guide
|
||||||
|
|
||||||
For the impatient, here's how to get Jekyll up and running.
|
For the impatient, here's how to get a boilerplate Jekyll site up and running.
|
||||||
|
|
||||||
{% highlight bash %}
|
{% highlight bash %}
|
||||||
~ $ gem install jekyll
|
~ $ gem install jekyll
|
||||||
~ $ mkdir -p my/new/site
|
~ $ jekyll new myblog
|
||||||
~ $ cd my/new/site
|
~ $ cd myblog
|
||||||
~ $ vim index.html
|
~/myblog $ jekyll serve
|
||||||
~/my/new/site $ jekyll serve
|
|
||||||
# => Now browse to http://localhost:4000
|
# => Now browse to http://localhost:4000
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
That's nothing though. The real magic happens when you start creating posts, using the front-matter to conrol templates and layouts, and taking advantage of all the awesome configuration options Jekyll makes available.
|
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
|
## 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.
|
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">
|
<div class="note">
|
||||||
<h5>ProTips™ help you get more from Jekyll</h5>
|
<h5>ProTips™ help you get more from Jekyll</h5>
|
||||||
|
|
@ -36,7 +51,8 @@ Throughout this guide there are a number of small-but-handy pieces of informatio
|
||||||
|
|
||||||
<div class="note info">
|
<div class="note info">
|
||||||
<h5>Notes are handy pieces of information</h5>
|
<h5>Notes are handy pieces of information</h5>
|
||||||
<p>These are for the extra tidbits sometimes necessary to understand Jekyll.</p>
|
<p>These are for the extra tidbits sometimes necessary to understand
|
||||||
|
Jekyll.</p>
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
<div class="note warning">
|
<div class="note warning">
|
||||||
|
|
@ -44,4 +60,7 @@ Throughout this guide there are a number of small-but-handy pieces of informatio
|
||||||
<p>Be aware of these messages if you wish to avoid certain death.</p>
|
<p>Be aware of these messages if you wish to avoid certain death.</p>
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
If you come across anything along the way that we haven’t covered, or if you know of a tip yourself 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.
|
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.
|
||||||
|
|
|
||||||
|
|
@ -5,11 +5,15 @@ prev_section: home
|
||||||
next_section: usage
|
next_section: usage
|
||||||
---
|
---
|
||||||
|
|
||||||
Getting Jekyll installed and ready-to-go should only take a few minutes. If it ever becomes a pain in the ass, you should [file an issue](https://github.com/mojombo/jekyll/issues/new) (or submit a pull request) about what might be a better way to do things.
|
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
|
### Requirements
|
||||||
|
|
||||||
Installing Jekyll is easy and straight-forward, but there’s a few requirements you’ll need to make sure your system has before you start.
|
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/)
|
- [Ruby](http://www.ruby-lang.org/en/downloads/)
|
||||||
- [RubyGems](http://rubygems.org/pages/download)
|
- [RubyGems](http://rubygems.org/pages/download)
|
||||||
|
|
@ -17,27 +21,46 @@ Installing Jekyll is easy and straight-forward, but there’s a few requirements
|
||||||
|
|
||||||
<div class="note info">
|
<div class="note info">
|
||||||
<h5>Running Jekyll on Windows</h5>
|
<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> however the official documentation does not support installation on Windows platforms.</p>
|
<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>
|
</div>
|
||||||
|
|
||||||
## Install with RubyGems
|
## Install with RubyGems
|
||||||
|
|
||||||
The best way to install Jekyll is via
|
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:
|
[RubyGems](http://docs.rubygems.org/read/chapter/3). At the terminal prompt,
|
||||||
|
simply run the following command to install Jekyll:
|
||||||
|
|
||||||
{% highlight bash %}
|
{% highlight bash %}
|
||||||
gem install jekyll
|
$ gem install jekyll
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
All Jekyll’s gem dependancies 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.
|
All 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
|
## 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.
|
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">
|
<div class="note">
|
||||||
<h5>ProTip™: Enable Syntax Highlighting</h5>
|
<h5>ProTip™: Enable Syntax Highlighting</h5>
|
||||||
<p>If you’re the kind of person who is using Jekyll, then chances are you’ll definitely 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>
|
<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>
|
</div>
|
||||||
|
|
||||||
Now that you’ve got everything installed, let’s get to work!
|
Now that you’ve got everything installed, let’s get to work!
|
||||||
|
|
|
||||||
|
|
@ -5,29 +5,53 @@ prev_section: variables
|
||||||
next_section: templates
|
next_section: templates
|
||||||
---
|
---
|
||||||
|
|
||||||
If you’re switching to Jekyll from another blogging system, Jekyll’s migrators can help you with the move. Most methods listed on this page require read access to the database to generate posts from your old system. Each method generates `.markdown` posts in the `_posts` directory based on the entries in the database.
|
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 to generate posts from your old system. Each method generates
|
||||||
|
`.markdown` posts in the `_posts` directory based on the entries in the foreign
|
||||||
|
system.
|
||||||
|
|
||||||
## Preparing for migrations
|
## Preparing for migrations
|
||||||
|
|
||||||
The migrators are [built-in to the Jekyll gem](https://github.com/mojombo/jekyll/tree/master/lib/jekyll/migrators), and require a few things to be set up in your project directory before they are run. This should all be done from the root folder of your Jekyll project.
|
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 %}
|
{% highlight bash %}
|
||||||
$ mkdir _import
|
$ gem install jekyll-import
|
||||||
$ gem install sequel mysqlplus
|
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
You should now be all set to run the migrators below.
|
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">
|
<div class="note info">
|
||||||
<h5>Note: Always double-check migrated content</h5>
|
<h5>Note: Always double-check migrated content</h5>
|
||||||
<p>Import scripts 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>
|
<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>
|
</div>
|
||||||
|
|
||||||
|
<!-- TODO all these need to be fixed -->
|
||||||
|
|
||||||
## WordPress
|
## WordPress
|
||||||
|
|
||||||
### Wordpress export files
|
### 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 exported file is saved as `wordpress.xml`, here is the command you need to run:
|
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 %}
|
{% highlight bash %}
|
||||||
$ ruby -rubygems -e 'require "jekyll/migrators/wordpressdotcom";
|
$ ruby -rubygems -e 'require "jekyll/migrators/wordpressdotcom";
|
||||||
|
|
@ -48,7 +72,7 @@ $ ruby -rubygems -e 'require "jekyll/migrators/wordpress";
|
||||||
Jekyll::WordPress.process("database", "user", "pass")'
|
Jekyll::WordPress.process("database", "user", "pass")'
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
If you are using Webfaction and have to set an [SSH tunnel](http://docs.webfaction.com/user-guide/databases.html?highlight=mysql#starting-an-ssh-tunnel-with-ssh), make 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:
|
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 %}
|
{% highlight bash %}
|
||||||
$ ruby -rubygems -e 'require "jekyll/migrators/wordpress";
|
$ ruby -rubygems -e 'require "jekyll/migrators/wordpress";
|
||||||
|
|
@ -65,7 +89,7 @@ While the above methods work, they do not import much of the metadata that is us
|
||||||
|
|
||||||
## Drupal
|
## Drupal
|
||||||
|
|
||||||
If you’re migrating from [Drupal](), there is [a migrator](https://github.com/mojombo/jekyll/blob/master/lib/jekyll/migrators/drupal.rb) for you too:
|
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 %}
|
{% highlight bash %}
|
||||||
$ ruby -rubygems -e 'require "jekyll/migrators/drupal";
|
$ ruby -rubygems -e 'require "jekyll/migrators/drupal";
|
||||||
|
|
@ -177,4 +201,4 @@ $ ruby -rubygems -e 'require "jekyll/migrators/tumblr";
|
||||||
|
|
||||||
## Other Systems
|
## Other Systems
|
||||||
|
|
||||||
If you have a system that there isn’t currently a migrator for, you should consider writing one and sending us a pull request.
|
If you have a system that there isn’t currently a migrator for, you should consider writing one and sending us a pull request.
|
||||||
|
|
|
||||||
|
|
@ -5,58 +5,81 @@ prev_section: posts
|
||||||
next_section: variables
|
next_section: variables
|
||||||
---
|
---
|
||||||
|
|
||||||
As well as [writing posts](../posts), the other thing you may want to do with your Jekyll site is create static pages. This is pretty simple to do, simply by taking advantage of the way Jekyll copies files and directories.
|
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
|
## Homepage
|
||||||
|
|
||||||
Just about every web server configuration you’ll come across will look for a HTML file called `index.html` (by convention) in the site 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.
|
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">
|
<div class="note">
|
||||||
<h5>ProTip™: Use layouts on your homepage</h5>
|
<h5>ProTip™: Use layouts on your homepage</h5>
|
||||||
<p>Any HTML file on your site can make use of layouts and includes, even the homepage. It’s usually a good idea to extract everything that is the same across all your pages into an included file in a layout.</p>
|
<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>
|
</div>
|
||||||
|
|
||||||
## Where additional pages live
|
## Where additional pages live
|
||||||
|
|
||||||
Where you put HTML files for pages depends on how you want the pages to work, since there are two main ways of creating pages:
|
Where you put HTML files for pages depends on how you want the pages to work.
|
||||||
|
There are two main ways of creating pages:
|
||||||
|
|
||||||
- By placing named HTML files for each page in the site root folder.
|
- Place named HTML files for each page in your site's root folder.
|
||||||
- Create a folder in the site root for each page, and placing an index.html file in each page 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 conduction with each other), with the only real difference being the resulting URLs each page has.
|
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
|
### Named HTML files
|
||||||
|
|
||||||
The simplest way of adding a page is just to add a 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.
|
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 %}
|
{% highlight bash %}
|
||||||
.
|
.
|
||||||
|-- _config.yml
|
|-- _config.yml
|
||||||
|-- _includes
|
|-- _includes/
|
||||||
|-- _layouts
|
|-- _layouts/
|
||||||
|-- _posts
|
|-- _posts/
|
||||||
|-- _site
|
|-- _site/
|
||||||
|-- about.html #=> http://yoursite.com/about.html
|
|-- about.html # => http://yoursite.com/about.html
|
||||||
|-- index.html #=> http://yoursite.com/
|
|-- index.html # => http://yoursite.com/
|
||||||
└── contact.html #=> http://yoursite.com/contact.html
|
└── contact.html # => http://yoursite.com/contact.html
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
### Named folders containing index HTML files
|
### 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. An example of what this structure would look like is as follows:
|
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 %}
|
{% highlight bash %}
|
||||||
.
|
.
|
||||||
├── _config.yml
|
├── _config.yml
|
||||||
├── _includes
|
├── _includes/
|
||||||
├── _layouts
|
├── _layouts/
|
||||||
├── _posts
|
├── _posts/
|
||||||
├── _site
|
├── _site/
|
||||||
├── about
|
├── about/
|
||||||
| └── index.html #=> http://yoursite.com/about/
|
| └── index.html # => http://yoursite.com/about/
|
||||||
├── contact
|
├── contact/
|
||||||
| └── index.html #=> http://yoursite.com/contact/
|
| └── index.html # => http://yoursite.com/contact/
|
||||||
└── index.html #=> http://yoursite.com/
|
└── index.html # => http://yoursite.com/
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
This approach may not suit everyone, but for people who like clear URLs it’s simple and it works. In the end the decision is yours!
|
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!
|
||||||
|
|
|
||||||
|
|
@ -5,117 +5,138 @@ prev_section: permalinks
|
||||||
next_section: plugins
|
next_section: plugins
|
||||||
---
|
---
|
||||||
|
|
||||||
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 post listings.
|
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">
|
<div class="note info">
|
||||||
<h5>Pagination only works within HTML files</h5>
|
<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 probably won’t be an issue.</p>
|
<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>
|
</div>
|
||||||
|
|
||||||
## Enable pagination
|
## Enable pagination
|
||||||
|
|
||||||
The first thing you need to do to enable pagination for your blog is add a line to the `_config.yml` Jekyll configuration file that specifies how many items should be displayed per page. Here is what the line should look like:
|
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 %}
|
{% highlight yaml %}
|
||||||
paginate: 5
|
paginate: 5
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
The number should be the maximum number of posts you’d like to be displayed per-page in the generated site.
|
The number should be the maximum number of Posts you’d like to be displayed per-
|
||||||
|
page in the generated site.
|
||||||
|
|
||||||
<div class="note info">
|
<div class="note info">
|
||||||
<h5>Pagination does not support tags or categories</h5>
|
<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>
|
<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>
|
</div>
|
||||||
|
|
||||||
## Render the paginated posts
|
## 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:
|
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 %}
|
{% highlight html %}
|
||||||
|
{% raw %}
|
||||||
---
|
---
|
||||||
layout: default
|
layout: default
|
||||||
title: My Blog
|
title: My Blog
|
||||||
---
|
---
|
||||||
|
|
||||||
<!-- This loops through the paginated posts -->
|
<!-- This loops through the paginated posts -->
|
||||||
{{ "{% for post in paginator.posts " }}%}
|
{% for post in paginator.posts %}
|
||||||
<h1><a href="{{ "{{ post.url " }}}}">{{ "{{ post.title " }}}}</a></h1>
|
<h1><a href="{{ post.url }}">{{ post.title }}</a></h1>
|
||||||
<p class="author">
|
<p class="author">
|
||||||
<span class="date">{{ "{{post.date" }}}}</span>
|
<span class="date">{{ post.date }}</span>
|
||||||
</p>
|
</p>
|
||||||
<div class="content">
|
<div class="content">
|
||||||
{{ "{{ post.content " }}}}
|
{{ post.content }}
|
||||||
</div>
|
</div>
|
||||||
{{ "{% endfor " }}%}
|
{% endfor %}
|
||||||
|
|
||||||
<!-- Pagination links -->
|
<!-- Pagination links -->
|
||||||
<div class="pagination">
|
<div class="pagination">
|
||||||
{{ "{% if paginator.previous_page " }}%}
|
{% if paginator.previous_page %}
|
||||||
<a href="/page{{ "{{paginator.previous_page" }}}}" class="previous">Previous</a>
|
<a href="/page{{ paginator.previous_page }}" class="previous">Previous</a>
|
||||||
{{ "{% else " }}%}
|
{% else %}
|
||||||
<span class="previous">Previous</span>
|
<span class="previous">Previous</span>
|
||||||
{{ "{% endif " }}%}
|
{% endif %}
|
||||||
<span class="page_number ">Page: {{ "{{paginator.page" }}}} of {{ "{{paginator.total_pages" }}}}</span>
|
<span class="page_number ">Page: {{ paginator.page }} of {{ paginator.total_pages }}</span>
|
||||||
{{ "{% if paginator.next_page " }}%}
|
{% if paginator.next_page %}
|
||||||
<a href="/page{{ "{{paginator.next_page" }}}}" class="next ">Next</a>
|
<a href="/page{{ paginator.next_page }}" class="next">Next</a>
|
||||||
{{ "{% else " }}%}
|
{% else %}
|
||||||
<span class="next ">Next</span>
|
<span class="next ">Next</span>
|
||||||
{{ "{% endif " }}%}
|
{% endif %}
|
||||||
</div>
|
</div>
|
||||||
|
{% endraw %}
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
<div class="note warning">
|
<div class="note warning">
|
||||||
<h5>Beware the page one edge-case</h5>
|
<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>
|
<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>
|
</div>
|
||||||
|
|
||||||
The following HTML snippet should handle page one, and render a list of each page with links to all but the current page.
|
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 %}
|
{% highlight html %}
|
||||||
|
{% raw %}
|
||||||
<div id="post-pagination" class="pagination">
|
<div id="post-pagination" class="pagination">
|
||||||
{{ "{% if paginator.previous_page " }}%}
|
{% if paginator.previous_page %}
|
||||||
<p class="previous">
|
<p class="previous">
|
||||||
{{ "{% if paginator.previous_page == 1 " }}%}
|
{% if paginator.previous_page == 1 %}
|
||||||
<a href="/">Previous</a>
|
<a href="/">Previous</a>
|
||||||
{{ "{% else " }}%}
|
{% else %}
|
||||||
<a href="/page{{ "{{paginator.previous_page" }}}}">Previous</a>
|
<a href="/page{{ paginator.previous_page }}">Previous</a>
|
||||||
{{ "{% endif " }}%}
|
{% endif %}
|
||||||
</p>
|
</p>
|
||||||
{{ "{% else " }}%}
|
{% else %}
|
||||||
<p class="previous disabled">
|
<p class="previous disabled">
|
||||||
<span>Previous</span>
|
<span>Previous</span>
|
||||||
</p>
|
</p>
|
||||||
{{ "{% endif " }}%}
|
{% endif %}
|
||||||
|
|
||||||
<ul class="pages">
|
<ul class="pages">
|
||||||
<li class="page">
|
<li class="page">
|
||||||
{{ "{% if paginator.page == 1 " }}%}
|
{% if paginator.page == 1 %}
|
||||||
<span class="current-page">1</span>
|
<span class="current-page">1</span>
|
||||||
{{ "{% else " }}%}
|
{% else %}
|
||||||
<a href="/">1</a>
|
<a href="/">1</a>
|
||||||
{{ "{% endif " }}%}
|
{% endif %}
|
||||||
</li>
|
</li>
|
||||||
|
|
||||||
{{ "{% for count in (2..paginator.total_pages) " }}%}
|
{% for count in (2..paginator.total_pages) %}
|
||||||
<li class="page">
|
<li class="page">
|
||||||
{{ "{% if count == paginator.page " }}%}
|
{% if count == paginator.page %}
|
||||||
<span class="current-page">{{ "{{count" }}}}</span>
|
<span class="current-page">{{ count }}</span>
|
||||||
{{ "{% else " }}%}
|
{% else %}
|
||||||
<a href="/page{{ "{{count" }}}}">{{ "{{count" }}}}</a>
|
<a href="/page{{ count }}">{{ count }}</a>
|
||||||
{{ "{% endif " }}%}
|
{% endif %}
|
||||||
</li>
|
</li>
|
||||||
{{ "{% endfor " }}%}
|
{% endfor %}
|
||||||
</ul>
|
</ul>
|
||||||
|
|
||||||
{{ "{% if paginator.next_page " }}%}
|
{% if paginator.next_page %}
|
||||||
<p class="next">
|
<p class="next">
|
||||||
<a href="/page{{ "{{paginator.next_page" }}}}">Next</a>
|
<a href="/page{{ paginator.next_page }}">Next</a>
|
||||||
</p>
|
</p>
|
||||||
{{ "{% else " }}%}
|
{% else %}
|
||||||
<p class="next disabled">
|
<p class="next disabled">
|
||||||
<span>Next</span>
|
<span>Next</span>
|
||||||
</p>
|
</p>
|
||||||
{{ "{% endif " }}%}
|
{% endif %}
|
||||||
|
|
||||||
</div>
|
</div>
|
||||||
|
{% endraw %}
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
|
||||||
|
|
@ -5,8 +5,15 @@ prev_section: templates
|
||||||
next_section: pagination
|
next_section: pagination
|
||||||
---
|
---
|
||||||
|
|
||||||
Jekyll supports a flexible way to build your site’s URLs. You can
|
Jekyll supports a flexible way to build your site’s URLs. You can specify the
|
||||||
specify the permalinks for your site through the [Configuration](../configuration) or on 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 always `date`.
|
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
|
## Template variables
|
||||||
|
|
||||||
|
|
@ -23,7 +30,7 @@ specify the permalinks for your site through the [Configuration](../configuratio
|
||||||
<p><code>year</code></p>
|
<p><code>year</code></p>
|
||||||
</td>
|
</td>
|
||||||
<td>
|
<td>
|
||||||
<p>Year from the post’s filename</p>
|
<p>Year from the Post’s filename</p>
|
||||||
</td>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
|
|
@ -31,31 +38,7 @@ specify the permalinks for your site through the [Configuration](../configuratio
|
||||||
<p><code>month</code></p>
|
<p><code>month</code></p>
|
||||||
</td>
|
</td>
|
||||||
<td>
|
<td>
|
||||||
<p>Month from the post’s filename</p>
|
<p>Month from the Post’s filename</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>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 basically ignores this.</p>
|
|
||||||
</td>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
|
|
@ -63,7 +46,15 @@ specify the permalinks for your site through the [Configuration](../configuratio
|
||||||
<p><code>i_month</code></p>
|
<p><code>i_month</code></p>
|
||||||
</td>
|
</td>
|
||||||
<td>
|
<td>
|
||||||
<p> Month from the post’s filename without leading zeros.</p>
|
<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>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
|
|
@ -71,7 +62,27 @@ specify the permalinks for your site through the [Configuration](../configuratio
|
||||||
<p><code>i_day</code></p>
|
<p><code>i_day</code></p>
|
||||||
</td>
|
</td>
|
||||||
<td>
|
<td>
|
||||||
<p>Day from the post’s filename without leading zeros.</p>
|
<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>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
|
|
@ -160,4 +171,3 @@ Given a post named: `/2009-04-29-slap-chop.textile`
|
||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -6,19 +6,27 @@ next_section: extras
|
||||||
---
|
---
|
||||||
|
|
||||||
Jekyll has a plugin system with hooks that allow you to create custom generated
|
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
|
content specific to your site. You can run custom code for your site without
|
||||||
without having to modify the Jekyll source itself.
|
having to modify the Jekyll source itself.
|
||||||
|
|
||||||
<div class="note info">
|
<div class="note info">
|
||||||
<h5>Plugins on GitHub Pages</h5>
|
<h5>Plugins on GitHub Pages</h5>
|
||||||
<p>GitHub Pages are 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.</p>
|
<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>
|
</div>
|
||||||
|
|
||||||
## Installing a plugin
|
## Installing a plugin
|
||||||
|
|
||||||
In your site source root, make a `_plugins` directory. Place your plugins
|
In your site source root, make a `_plugins` directory. Place your plugins here.
|
||||||
here. Any file ending in `*.rb` inside this directory will be required
|
Any file ending in `*.rb` inside this directory will be loaded before Jekyll
|
||||||
when Jekyll generates your site.
|
generates your site.
|
||||||
|
|
||||||
In general, plugins you make will fall into one of three categories:
|
In general, plugins you make will fall into one of three categories:
|
||||||
|
|
||||||
|
|
@ -28,9 +36,8 @@ In general, plugins you make will fall into one of three categories:
|
||||||
|
|
||||||
## Generators
|
## Generators
|
||||||
|
|
||||||
You can create a generator when you need Jekyll to create additional
|
You can create a generator when you need Jekyll to create additional content
|
||||||
content based on your own rules. For example, a generator might look
|
based on your own rules. For example, a generator might look like this:
|
||||||
like this:
|
|
||||||
|
|
||||||
{% highlight ruby %}
|
{% highlight ruby %}
|
||||||
module Jekyll
|
module Jekyll
|
||||||
|
|
@ -68,8 +75,8 @@ end
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
In this example, our generator will create a series of files under the
|
In this example, our generator will create a series of files under the
|
||||||
`categories` directory for each category, listing the posts in each
|
`categories` directory for each category, listing the posts in each category
|
||||||
category using the `category_index.html` layout.
|
using the `category_index.html` layout.
|
||||||
|
|
||||||
Generators are only required to implement one method:
|
Generators are only required to implement one method:
|
||||||
|
|
||||||
|
|
@ -94,18 +101,20 @@ Generators are only required to implement one method:
|
||||||
|
|
||||||
## Converters
|
## Converters
|
||||||
|
|
||||||
If you have a new markup language you’d like to include in your site,
|
If you have a new markup language you’d like to use with your site, you can
|
||||||
you can include it by implementing your own converter. Both the markdown
|
include it by implementing your own converter. Both the Markdown and Textile
|
||||||
and textile markup languages are implemented using this method.
|
markup languages are implemented using this method.
|
||||||
|
|
||||||
<div class="note info">
|
<div class="note info">
|
||||||
<h5>Remember your YAML front-matter</h5>
|
<h5>Remember your YAML front-matter</h5>
|
||||||
<p>Jekyll will only convert files that have a YAML header at
|
<p>
|
||||||
the top, even for converters you add using a plugin. If there is no YAML header, Jekyll will ignore the file and not send it through the converter.</p>
|
Jekyll will only convert files that have a YAML header at the top, even for
|
||||||
|
converters you add using a plugin.
|
||||||
|
</p>
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
Below is a converter that will take all posts ending in .upcase and
|
Below is a converter that will take all posts ending in `.upcase` and process
|
||||||
process them using the UpcaseConverter:
|
them using the `UpcaseConverter`:
|
||||||
|
|
||||||
{% highlight ruby %}
|
{% highlight ruby %}
|
||||||
module Jekyll
|
module Jekyll
|
||||||
|
|
@ -114,7 +123,7 @@ module Jekyll
|
||||||
priority :low
|
priority :low
|
||||||
|
|
||||||
def matches(ext)
|
def matches(ext)
|
||||||
ext =~ /upcase/i
|
ext =~ /^\.upcase$/i
|
||||||
end
|
end
|
||||||
|
|
||||||
def output_ext(ext)
|
def output_ext(ext)
|
||||||
|
|
@ -142,37 +151,46 @@ Converters should implement at a minimum 3 methods:
|
||||||
<td>
|
<td>
|
||||||
<p><code>matches</code></p>
|
<p><code>matches</code></p>
|
||||||
</td>
|
</td>
|
||||||
<td>
|
<td><p>
|
||||||
<p>Called to determine whether the specific converter will
|
Does the given extension match this converter's list of acceptable
|
||||||
run on the page.</p>
|
extensions? Takes one argument: the file's extension (including the
|
||||||
</td>
|
dot). Must return <code>true</code> if it matches, <code>false</code>
|
||||||
|
otherwise.
|
||||||
|
</p></td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>
|
<td>
|
||||||
<p><code>output_ext</code></p>
|
<p><code>output_ext</code></p>
|
||||||
</td>
|
</td>
|
||||||
<td>
|
<td><p>
|
||||||
<p>The extension of the outputted file, usually this will be <code>.html</code></p>
|
The extension to be given to the output file (including the dot).
|
||||||
</td>
|
Usually this will be <code>".html"</code>.
|
||||||
|
</p></td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>
|
<td>
|
||||||
<p><code>convert</code></p>
|
<p><code>convert</code></p>
|
||||||
</td>
|
</td>
|
||||||
<td>
|
<td><p>
|
||||||
<p>Logic to do the content conversion</p>
|
Logic to do the content conversion. Takes one argument: the raw content
|
||||||
</td>
|
of the file (without YAML front matter). Must return a String.
|
||||||
|
</p></td>
|
||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
|
|
||||||
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 capitalizing the entire content string. Finally, when it saves the page, it will do so with the `.html` extension.
|
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
|
## Tags
|
||||||
|
|
||||||
If you’d like to include custom liquid tags in your site, you can do so
|
If you’d like to include custom liquid tags in your site, you can do so by
|
||||||
by hooking into the tagging system. Built-in examples added by Jekyll
|
hooking into the tagging system. Built-in examples added by Jekyll include the
|
||||||
include the `{{"{% highlight "}}%}` and `{{"{% include "}}%}` tags. Below is an example custom liquid tag that will output the time the page was rendered:
|
`highlight` and `include` tags. Below is an example of a custom liquid tag that
|
||||||
|
will output the time the page was rendered:
|
||||||
|
|
||||||
{% highlight ruby %}
|
{% highlight ruby %}
|
||||||
module Jekyll
|
module Jekyll
|
||||||
|
|
@ -213,16 +231,20 @@ At a minimum, liquid tags must implement:
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
|
|
||||||
You must also register the custom tag with the Liquid template engine as follows:
|
You must also register the custom tag with the Liquid template engine as
|
||||||
|
follows:
|
||||||
|
|
||||||
{% highlight ruby %}
|
{% highlight ruby %}
|
||||||
Liquid::Template.register_tag('render_time', Jekyll::RenderTimeTag)
|
Liquid::Template.register_tag('render_time', Jekyll::RenderTimeTag)
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
In the example above, we can place the following tag anywhere in one of our pages:
|
In the example above, we can place the following tag anywhere in one of our
|
||||||
|
pages:
|
||||||
|
|
||||||
{% highlight ruby %}
|
{% highlight ruby %}
|
||||||
<p>{{"{% render_time page rendered at: "}}%}</p>
|
{% raw %}
|
||||||
|
<p>{% render_time page rendered at: %}</p>
|
||||||
|
{% endraw %}
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
And we would get something like this on the page:
|
And we would get something like this on the page:
|
||||||
|
|
@ -233,7 +255,10 @@ And we would get something like this on the page:
|
||||||
|
|
||||||
### Liquid filters
|
### 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.
|
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 %}
|
{% highlight ruby %}
|
||||||
module Jekyll
|
module Jekyll
|
||||||
|
|
@ -249,7 +274,12 @@ Liquid::Template.register_filter(Jekyll::AssetFilter)
|
||||||
|
|
||||||
<div class="note">
|
<div class="note">
|
||||||
<h5>ProTip™: Access the site object using Liquid</h5>
|
<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>
|
<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>
|
</div>
|
||||||
|
|
||||||
### Flags
|
### Flags
|
||||||
|
|
@ -269,24 +299,35 @@ There are two flags to be aware of when writing a plugin:
|
||||||
<p><code>safe</code></p>
|
<p><code>safe</code></p>
|
||||||
</td>
|
</td>
|
||||||
<td>
|
<td>
|
||||||
<p>A boolean flag that allows a plugin to be safely included in
|
<p>
|
||||||
Jekyll core for exclusion from use with GitHub Pages. In general, set
|
A boolean flag that informs Jekyll whether this plugin may be safely
|
||||||
this to <code>true</code>.</p>
|
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>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>
|
<td>
|
||||||
<p><code>priortiy</code></p>
|
<p><code>priority</code></p>
|
||||||
</td>
|
</td>
|
||||||
<td>
|
<td>
|
||||||
<p>This flag determines what order the plugin is loaded in. Valid
|
<p>
|
||||||
values are: <code>:lowest</code>, <code>:low</code>, <code>:normal</code>, <code>:high</code>, and <code>:highest</code>.</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>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
|
|
||||||
To use one of the example plugins above as an illustration, here is how you’d specify these two flags:
|
To use one of the example plugins above as an illustration, here is how you’d
|
||||||
|
specify these two flags:
|
||||||
|
|
||||||
{% highlight ruby %}
|
{% highlight ruby %}
|
||||||
module Jekyll
|
module Jekyll
|
||||||
|
|
@ -298,16 +339,15 @@ module Jekyll
|
||||||
end
|
end
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
|
|
||||||
## Available Plugins
|
## Available Plugins
|
||||||
|
|
||||||
There are a few useful, prebuilt plugins at the following locations:
|
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)
|
- [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
|
- [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
|
- [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
|
- [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
|
- [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
|
- [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.
|
- [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
|
- [Ultraviolet plugin by Steve Alex](https://gist.github.com/480380): Jekyll Plugin for Ultraviolet
|
||||||
|
|
@ -380,5 +420,9 @@ There are a few useful, prebuilt plugins at the following locations:
|
||||||
|
|
||||||
<div class="note info">
|
<div class="note info">
|
||||||
<h5>Jekyll Plugins Wanted</h5>
|
<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>
|
<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>
|
</div>
|
||||||
|
|
|
||||||
|
|
@ -5,77 +5,121 @@ prev_section: frontmatter
|
||||||
next_section: pages
|
next_section: pages
|
||||||
---
|
---
|
||||||
|
|
||||||
One of Jekyll’s best aspects is that it is “blog aware”. What does that mean, exactly? Well, simply put it means that blogging is baked into Jekyll’s functionality by default. For people who write articles and publish them online, this means that you can publish and maintain a blog simply by managing a folder full 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 for many.
|
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
|
## The Posts Folder
|
||||||
|
|
||||||
As detailed on the [directory structure](../structure) page, the `_posts` folder in any Jekyll site is where the files for all your articles 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) defined, they will be converted from their source format into a HTML page that is part of your static site.
|
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
|
### Creating Post Files
|
||||||
|
|
||||||
To create a new post, all you need to do is create a new file in the `_posts` folder. The filename structure used for files in this folder is important—Jekyll requires the file to be named in the following format:
|
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 %}
|
{% highlight bash %}
|
||||||
YEAR-MONTH-DAY-title.MARKUP
|
YEAR-MONTH-DAY-title.MARKUP
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
Where `YEAR` is a four-digit number, `MONTH` and `DAY` are both two-digit numbers, and `MARKUP` is an appropriate file extension for the format your post is written in. For example, the following are examples of excellent post filenames:
|
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 %}
|
{% highlight bash %}
|
||||||
2011-12-31-new-years-eve-is-awesome.markdown
|
2011-12-31-new-years-eve-is-awesome.md
|
||||||
2012-09-12-how-to-write-a-blog.textile
|
2012-09-12-how-to-write-a-blog.textile
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
### Content Formats
|
### Content Formats
|
||||||
|
|
||||||
The first thing you need to put in any post is a section for [YAML front-matter](../frontmatter), but after that, it's simply a case of deciding which format you prefer to write in. Jekyll supports two popular content markup formats: [Markdown](http://daringfireball.net/projects/markdown/) or [Textile](http://textile.sitemonks.com/). These formats each have their own way of signifying different types of content within a post, so you should read up on how these formats work and decide which one suits your needs best.
|
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
|
## Including images and resources
|
||||||
|
|
||||||
For people who publish articles on a regular basis, it’s quite common to need to include things like images, links, downloads, and other resources along with their text-based content. While the ways to link to these resources differ between Markdown and Textile, the problem of working out where to store these files in your site is something everyone will face.
|
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.
|
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:
|
Including an image asset in a post:
|
||||||
|
|
||||||
{% highlight bash %}
|
{% highlight text %}
|
||||||
… which is shown in the screenshot below:
|
… which is shown in the screenshot below:
|
||||||
![My helpful screenshot]({{ "{{ site.url " }}}}/assets/screenshot.jpg)
|
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
Linking to a PDF for readers to download:
|
Linking to a PDF for readers to download:
|
||||||
|
|
||||||
{% highlight bash %}
|
{% highlight text %}
|
||||||
… you can [get the PDF]({{ "{{ site.url " }}}}/assets/mydoc.pdf) directly.
|
… you can [get the PDF]({% raw %}{{ site.url }}{% endraw %}/assets/mydoc.pdf) directly.
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
<div class="note">
|
<div class="note">
|
||||||
<h5>ProTip™: Link using just the site root URL</h5>
|
<h5>ProTip™: Link using just the site root URL</h5>
|
||||||
<p>You can skip the <code>{{ "{{ site.url " }}}}</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>
|
<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>
|
</div>
|
||||||
|
|
||||||
## Displaying an index of posts
|
## 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 for people. Creating an index of posts on another page (or in a [template](../templates)) is easy, thanks to the [Liquid template language](http://liquidmarkup.org/) and it’s tags. Here’s a basic example of how to create an unordered list of links to posts for a Jekyll site:
|
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://liquidmarkup.org/) and its tags. Here’s a basic example of how
|
||||||
|
to create a list of links to your blog posts:
|
||||||
|
|
||||||
{% highlight html %}
|
{% highlight html %}
|
||||||
<ul>
|
<ul>
|
||||||
{{ "{% for post in site.posts " }}%}
|
{% raw %}{% for post in site.posts %}{% endraw %}
|
||||||
<li>
|
<li>
|
||||||
<a href="{{ "{{ post.url "}}}}">{{ "{{ post.title "}}}}</a>
|
<a href="{% raw %}{{ post.url }}{% endraw %}">{% raw %}{{ post.title }}{% endraw %}</a>
|
||||||
</li>
|
</li>
|
||||||
{{ "{% endfor " }}%}
|
{% raw %}{% endfor %}{% endraw %}
|
||||||
</ul>
|
</ul>
|
||||||
{% endhighlight %}
|
{% 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’re interested in these kinds of things.
|
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
|
## 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:
|
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 ruby %}
|
{% highlight text %}
|
||||||
{{ "{% highlight ruby"}} %}
|
{% raw %}{% highlight ruby %}{% endraw %}
|
||||||
def show
|
def show
|
||||||
@widget = Widget(params[:id])
|
@widget = Widget(params[:id])
|
||||||
respond_to do |format|
|
respond_to do |format|
|
||||||
|
|
@ -83,7 +127,7 @@ def show
|
||||||
format.json { render json: @widget }
|
format.json { render json: @widget }
|
||||||
end
|
end
|
||||||
end
|
end
|
||||||
{{ "{% endhighlight"}} %}
|
{% raw %}{% endhighlight %}{% endraw %}
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
And the output will look like this:
|
And the output will look like this:
|
||||||
|
|
@ -100,7 +144,14 @@ end
|
||||||
|
|
||||||
<div class="note">
|
<div class="note">
|
||||||
<h5>ProTip™: Show line numbers</h5>
|
<h5>ProTip™: Show line numbers</h5>
|
||||||
<p>You can make code snippets include line-numbers easily, simply add the word <code>linenos</code> to the end of the opening highlight tag like this: <code>{{ "{% highlight ruby linenos " }}%}</code>.</p>
|
<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>
|
</div>
|
||||||
|
|
||||||
Those basics should be more than 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.
|
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.
|
||||||
|
|
|
||||||
|
|
@ -5,7 +5,13 @@ prev_section: usage
|
||||||
next_section: configuration
|
next_section: configuration
|
||||||
---
|
---
|
||||||
|
|
||||||
Jekyll at its core is 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 on the layout and more. This is all done through strictly editing files, and the web interface is the final product.
|
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:
|
A basic Jekyll site usually looks something like this:
|
||||||
|
|
||||||
|
|
@ -40,7 +46,13 @@ An overview of what each of these does:
|
||||||
<p><code>_config.yml</code></p>
|
<p><code>_config.yml</code></p>
|
||||||
</td>
|
</td>
|
||||||
<td>
|
<td>
|
||||||
<p>Stores <a href="../configuration">configuration</a> data. A majority of these options can be specified from the command line executable but it’s easier to throw them in here so you don’t have to remember them.</p>
|
<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>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
|
|
@ -48,7 +60,15 @@ An overview of what each of these does:
|
||||||
<p><code>_includes</code></p>
|
<p><code>_includes</code></p>
|
||||||
</td>
|
</td>
|
||||||
<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>{{ "{% include file.ext " }}%}</code> can be used to include the partial in <code>_includes/file.ext</code>.</p>
|
<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>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
|
|
@ -56,7 +76,15 @@ An overview of what each of these does:
|
||||||
<p><code>_layouts</code></p>
|
<p><code>_layouts</code></p>
|
||||||
</td>
|
</td>
|
||||||
<td>
|
<td>
|
||||||
<p>These are the templates which posts are inserted into. 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>{{ "{{ content " }}}}</code> is used to inject data onto the page.</p>
|
<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>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
|
|
@ -64,7 +92,16 @@ An overview of what each of these does:
|
||||||
<p><code>_posts</code></p>
|
<p><code>_posts</code></p>
|
||||||
</td>
|
</td>
|
||||||
<td>
|
<td>
|
||||||
<p>Your dynamic content, so to speak. The format of these files is important, as named as <code>YEAR-MONTH-DAY-title.MARKUP</code>. The <a href="../permalinks">permalinks</a> can be adjusted very flexibly for each post, but the date and markup language are determined solely by the file name.</p>
|
<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>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
|
|
@ -72,7 +109,13 @@ An overview of what each of these does:
|
||||||
<p><code>_site</code></p>
|
<p><code>_site</code></p>
|
||||||
</td>
|
</td>
|
||||||
<td>
|
<td>
|
||||||
<p>This is where the generated site will be placed once Jekyll is done transforming it. It's probably a good idea to add this to your <code>.gitignore</code> file.</p>
|
<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>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
|
|
@ -80,7 +123,15 @@ An overview of what each of these does:
|
||||||
<p><code>index.html</code> and other HTML, Markdown, Textile files</p>
|
<p><code>index.html</code> and other HTML, Markdown, Textile files</p>
|
||||||
</td>
|
</td>
|
||||||
<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>
|
<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>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
|
|
@ -88,7 +139,16 @@ An overview of what each of these does:
|
||||||
<p>Other Files/Folders</p>
|
<p>Other Files/Folders</p>
|
||||||
</td>
|
</td>
|
||||||
<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 transferred over verbatim to the generated site. There's plenty of <a href="../sites">sites already using Jekyll</a> if you're curious as to how they're laid out.</p>
|
<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>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
|
|
|
||||||
|
|
@ -5,7 +5,11 @@ prev_section: migrations
|
||||||
next_section: permalinks
|
next_section: permalinks
|
||||||
---
|
---
|
||||||
|
|
||||||
Jekyll uses the [Liquid](http://www.liquidmarkup.org/) 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.
|
Jekyll uses the [Liquid](http://www.liquidmarkup.org/) 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
|
## Filters
|
||||||
|
|
||||||
|
|
@ -24,7 +28,7 @@ Jekyll uses the [Liquid](http://www.liquidmarkup.org/) templating language to pr
|
||||||
</td>
|
</td>
|
||||||
<td class='align-center'>
|
<td class='align-center'>
|
||||||
<p>
|
<p>
|
||||||
<code class='filter'>{{ "{{ site.time | date_to_xmlschema " }}}}</code>
|
<code class='filter'>{% raw %}{{ site.time | date_to_xmlschema }}{% endraw %}</code>
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
<code class='output'>2008-11-17T13:07:54-08:00</code>
|
<code class='output'>2008-11-17T13:07:54-08:00</code>
|
||||||
|
|
@ -38,7 +42,7 @@ Jekyll uses the [Liquid](http://www.liquidmarkup.org/) templating language to pr
|
||||||
</td>
|
</td>
|
||||||
<td class='align-center'>
|
<td class='align-center'>
|
||||||
<p>
|
<p>
|
||||||
<code class='filter'>{{ "{{ site.time | date_to_string " }}}}</code>
|
<code class='filter'>{% raw %}{{ site.time | date_to_string }}{% endraw %}</code>
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
<code class='output'>17 Nov 2008</code>
|
<code class='output'>17 Nov 2008</code>
|
||||||
|
|
@ -52,7 +56,7 @@ Jekyll uses the [Liquid](http://www.liquidmarkup.org/) templating language to pr
|
||||||
</td>
|
</td>
|
||||||
<td class='align-center'>
|
<td class='align-center'>
|
||||||
<p>
|
<p>
|
||||||
<code class='filter'>{{ "{{ site.time | date_to_long_string " }}}}</code>
|
<code class='filter'>{% raw %}{{ site.time | date_to_long_string }}{% endraw %}</code>
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
<code class='output'>17 November 2008</code>
|
<code class='output'>17 November 2008</code>
|
||||||
|
|
@ -66,18 +70,21 @@ Jekyll uses the [Liquid](http://www.liquidmarkup.org/) templating language to pr
|
||||||
</td>
|
</td>
|
||||||
<td class='align-center'>
|
<td class='align-center'>
|
||||||
<p>
|
<p>
|
||||||
<code class='filter'>{{ "{{ page.content | xml_escape " }}}}</code>
|
<code class='filter'>{% raw %}{{ page.content | xml_escape }}{% endraw %}</code>
|
||||||
</p>
|
</p>
|
||||||
</td>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td>
|
<td>
|
||||||
<p class='name'><strong>CGI Escape</strong></p>
|
<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>
|
<p>
|
||||||
|
CGI escape a string for use in a URL. Replaces any special characters
|
||||||
|
with appropriate %XX replacements.
|
||||||
|
</p>
|
||||||
</td>
|
</td>
|
||||||
<td class='align-center'>
|
<td class='align-center'>
|
||||||
<p>
|
<p>
|
||||||
<code class='filter'>{{ "{{ “foo,bar;baz?” | cgi_escape " }}}}</code>
|
<code class='filter'>{% raw %}{{ “foo,bar;baz?” | cgi_escape }}{% endraw %}</code>
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
<code class='output'>foo%2Cbar%3Bbaz%3F</code>
|
<code class='output'>foo%2Cbar%3Bbaz%3F</code>
|
||||||
|
|
@ -91,7 +98,7 @@ Jekyll uses the [Liquid](http://www.liquidmarkup.org/) templating language to pr
|
||||||
</td>
|
</td>
|
||||||
<td class='align-center'>
|
<td class='align-center'>
|
||||||
<p>
|
<p>
|
||||||
<code class='filter'>{{ "{{ page.content | number_of_words " }}}}</code>
|
<code class='filter'>{% raw %}{{ page.content | number_of_words }}{% endraw %}</code>
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
<code class='output'>1337</code>
|
<code class='output'>1337</code>
|
||||||
|
|
@ -105,7 +112,7 @@ Jekyll uses the [Liquid](http://www.liquidmarkup.org/) templating language to pr
|
||||||
</td>
|
</td>
|
||||||
<td class='align-center'>
|
<td class='align-center'>
|
||||||
<p>
|
<p>
|
||||||
<code class='filter'>{{ "{{ page.tags | array_to_sentence_string " }}}}</code>
|
<code class='filter'>{% raw %}{{ page.tags | array_to_sentence_string }}{% endraw %}</code>
|
||||||
</p>
|
</p>
|
||||||
<p>
|
<p>
|
||||||
<code class='output'>foo, bar, and baz</code>
|
<code class='output'>foo, bar, and baz</code>
|
||||||
|
|
@ -119,7 +126,7 @@ Jekyll uses the [Liquid](http://www.liquidmarkup.org/) templating language to pr
|
||||||
</td>
|
</td>
|
||||||
<td class='align-center'>
|
<td class='align-center'>
|
||||||
<p>
|
<p>
|
||||||
<code class='filter'>{{ "{{ page.excerpt | textilize " }}}}</code>
|
<code class='filter'>{% raw %}{{ page.excerpt | textilize }}{% endraw %}</code>
|
||||||
</p>
|
</p>
|
||||||
</td>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
|
|
@ -130,7 +137,7 @@ Jekyll uses the [Liquid](http://www.liquidmarkup.org/) templating language to pr
|
||||||
</td>
|
</td>
|
||||||
<td class='align-center'>
|
<td class='align-center'>
|
||||||
<p>
|
<p>
|
||||||
<code class='filter'>{{ "{{ page.excerpt | markdownify " }}}}</code>
|
<code class='filter'>{% raw %}{{ page.excerpt | markdownify }}{% endraw %}</code>
|
||||||
</p>
|
</p>
|
||||||
</td>
|
</td>
|
||||||
</tr>
|
</tr>
|
||||||
|
|
@ -139,79 +146,89 @@ Jekyll uses the [Liquid](http://www.liquidmarkup.org/) templating language to pr
|
||||||
|
|
||||||
## Tags
|
## Tags
|
||||||
|
|
||||||
### Includes (Partials)
|
### Includes
|
||||||
|
|
||||||
If you have small page fragments that you wish to include in multiple
|
If you have small page fragments that you wish to include in multiple places on
|
||||||
places on your site, you can use the `include` tag.
|
your site, you can use the `include` tag.
|
||||||
|
|
||||||
{% highlight ruby %}
|
{% highlight ruby %}
|
||||||
{{ "{% include sig.textile " }}%}
|
{% raw %}{% include sig.md %}{% endraw %}
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
Jekyll expects all include files to be placed in an `_includes`
|
Jekyll expects all include files to be placed in an `_includes` directory at the
|
||||||
directory at the root of your source dir. So this will embed the
|
root of your source directory. This will embed the contents of
|
||||||
contents of `/path/to/your/site/_includes/sig.textile` into the calling
|
`<source>/_includes/sig.md` into the calling file.
|
||||||
file.
|
|
||||||
|
|
||||||
### Code snippet highlighting
|
### Code snippet highlighting
|
||||||
|
|
||||||
Jekyll has built in support for syntax highlighting of [over 100
|
Jekyll has built in support for syntax highlighting of [over 100
|
||||||
languages](http://pygments.org/languages/) thanks to
|
languages](http://pygments.org/languages/) thanks to
|
||||||
[Pygments](http://pygments.org/). In order to take advantage of this
|
[Pygments](http://pygments.org/). In order to take advantage of this you’ll need
|
||||||
you’ll need to have Pygments installed, and the `pygmentize` binary must
|
to have Pygments installed, and the `pygmentize` binary must be in your `$PATH`.
|
||||||
be in your `$PATH`. When you run Jekyll, make sure you run it with
|
When you run Jekyll, make sure you run it with [Pygments enabled](../extras).
|
||||||
[Pygments enabled](../extras).
|
|
||||||
|
|
||||||
To render a code block with syntax highlighting, surround your code as follows:
|
To render a code block with syntax highlighting, surround your code as follows:
|
||||||
|
|
||||||
|
{% highlight text %}
|
||||||
|
{% raw %}
|
||||||
{% highlight ruby %}
|
{% highlight ruby %}
|
||||||
{{ "{% highlight ruby " }}%}
|
|
||||||
def foo
|
def foo
|
||||||
puts 'foo'
|
puts 'foo'
|
||||||
end
|
end
|
||||||
{{ "{% endhighlight " }}%}
|
{% endhighlight %}
|
||||||
|
{% endraw %}
|
||||||
{% endhighlight %}
|
{% 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/).
|
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
|
#### Line numbers
|
||||||
|
|
||||||
There is a second argument to `highlight` called `linenos` that is
|
There is a second argument to `highlight` called `linenos` that is optional.
|
||||||
optional. Including the `linenos` argument will force the highlighted
|
Including the `linenos` argument will force the highlighted code to include line
|
||||||
code to include line numbers. For instance, the following code block
|
numbers. For instance, the following code block would include line numbers next
|
||||||
would include line numbers next to each line:
|
to each line:
|
||||||
|
|
||||||
{% highlight ruby %}
|
{% highlight text %}
|
||||||
{{ "{% highlight ruby linenos " }}%}
|
{% raw %}
|
||||||
|
{% highlight ruby linenos %}
|
||||||
def foo
|
def foo
|
||||||
puts 'foo'
|
puts 'foo'
|
||||||
end
|
end
|
||||||
{{ "{% endhighlight " }}%}
|
{% endhighlight %}
|
||||||
|
{% endraw %}
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
#### Stylesheets for syntax highlighting
|
#### Stylesheets for syntax highlighting
|
||||||
|
|
||||||
In order for the highlighting to show up, you’ll need to include a
|
In order for the highlighting to show up, you’ll need to include a highlighting
|
||||||
highlighting stylesheet. For an example stylesheet you can look at
|
stylesheet. For an example stylesheet you can look at
|
||||||
[syntax.css](http://github.com/mojombo/tpw/tree/master/css/syntax.css).
|
[syntax.css](http://github.com/mojombo/tpw/tree/master/css/syntax.css). These
|
||||||
These are the same styles as used by GitHub and you are free to use them
|
are the same styles as used by GitHub and you are free to use them for your own
|
||||||
for your own site. If you use linenos, you might want to include an
|
site. If you use `linenos`, you might want to include an additional CSS class
|
||||||
additional CSS class definition for the `.lineno` class in `syntax.css` to
|
definition for the `.lineno` class in `syntax.css` to distinguish the line
|
||||||
distinguish the line numbers from the highlighted code.
|
numbers from the highlighted code.
|
||||||
|
|
||||||
### Post URL
|
### 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.
|
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 bash %}
|
{% highlight text %}
|
||||||
{{ "{% post_url 2010-07-21-name-of-post " }}%}
|
{% raw %}
|
||||||
|
{% post_url 2010-07-21-name-of-post %}
|
||||||
|
{% endraw %}
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
There is no need to include the file extension when using the `post_url` tag.
|
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:
|
You can also use this tag to create a link to a post in Markdown as follows:
|
||||||
|
|
||||||
{% highlight html %}
|
{% highlight text %}
|
||||||
[Name of Link]({{ "{% post_url 2010-07-21-name-of-post " }}%})
|
{% raw %}
|
||||||
|
[Name of Link]({% post_url 2010-07-21-name-of-post %})
|
||||||
|
{% endraw %}
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -5,34 +5,53 @@ prev_section: installation
|
||||||
next_section: structure
|
next_section: structure
|
||||||
---
|
---
|
||||||
|
|
||||||
The Jekyll gem makes a `jekyll` executable available to you in your Terminal window. You can use this command in a number of ways:
|
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 %}
|
{% highlight bash %}
|
||||||
jekyll build
|
$ jekyll build
|
||||||
#=> The current folder will get generated into ./_site
|
# => The current folder will be generated into ./_site
|
||||||
jekyll build --destination <destination>
|
|
||||||
#=> The current folder will get generated into <destination>
|
$ jekyll build --destination <destination>
|
||||||
jekyll build --source <source> --destination <destination>
|
# => The current folder will be generated into <destination>
|
||||||
#=> The <source> folder will get generated into <destination>
|
|
||||||
jekyll build --watch
|
$ jekyll build --source <source> --destination <destination>
|
||||||
#=> The current folder will get generated into ./_site,
|
# => The <source> folder will be generated into <destination>
|
||||||
# and watch for changes and regenerate automatically.
|
|
||||||
|
$ jekyll build --watch
|
||||||
|
# => The current folder will be generated into ./_site,
|
||||||
|
# and watch for changes and regenerate automatically.
|
||||||
{% endhighlight %}
|
{% 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.
|
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 %}
|
{% highlight bash %}
|
||||||
jekyll serve
|
$ jekyll serve
|
||||||
#=> A development server will run at http://localhost:4000/
|
# => A development server will run at http://localhost:4000/
|
||||||
jekyll serve --watch
|
|
||||||
#=> As above, but watch for changes and regenerate automatically too.
|
$ jekyll serve --watch
|
||||||
|
# => As above, but watch for changes and regenerate automatically.
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
These are just some of the many [configuration options](../configuration) available. All 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 configuration options from this file when run, so placing the following one line in the configuration file will mean that running `jekyll build` or `jekyll serve` would be equivalent to running `jekyll [build|serve] --source _source --destination _deploy`:
|
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 %}
|
{% highlight yaml %}
|
||||||
source: _source
|
source: _source
|
||||||
destination: _deploy
|
destination: _deploy
|
||||||
{% endhighlight %}
|
{% endhighlight %}
|
||||||
|
|
||||||
For more about the possible configuration options, see the [configuration](../configuration) page.
|
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.
|
||||||
|
|
|
||||||
|
|
@ -5,7 +5,11 @@ prev_section: pages
|
||||||
next_section: migrations
|
next_section: migrations
|
||||||
---
|
---
|
||||||
|
|
||||||
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 to the pages via the [Liquid templating system](http://wiki.github.com/shopify/liquid/liquid-for-designers). The following is a reference of the available data.
|
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
|
## Global Variables
|
||||||
|
|
||||||
|
|
@ -19,19 +23,41 @@ Jekyll traverses your site looking for files to process. Any files with [YAML Fr
|
||||||
<tbody>
|
<tbody>
|
||||||
<tr>
|
<tr>
|
||||||
<td><p><code>site</code></p></td>
|
<td><p><code>site</code></p></td>
|
||||||
<td><p>Sitewide information + Configuration settings from <code>_config.yml</code></p></td>
|
<td><p>
|
||||||
|
|
||||||
|
Sitewide information + configuration settings from
|
||||||
|
<code>_config.yml</code>. See below for details.
|
||||||
|
|
||||||
|
</p></td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td><p><code>page</code></p></td>
|
<td><p><code>page</code></p></td>
|
||||||
<td><p>This is just the <a href="../frontmatter">YAML Front Matter</a> with 2 additions: <code>url</code> and <code>content</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>
|
||||||
<tr>
|
<tr>
|
||||||
<td><p><code>content</code></p></td>
|
<td><p><code>content</code></p></td>
|
||||||
<td><p>In layout files, this contains the content of the subview(s). This is the variable used to insert the rendered content into the layout. This is not used in post files or page files.</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>
|
||||||
<tr>
|
<tr>
|
||||||
<td><p><code>paginator</code></p></td>
|
<td><p><code>paginator</code></p></td>
|
||||||
<td><p>When the <code>paginate</code> configuration option is set, this variable becomes available for use.</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>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
|
|
@ -48,27 +74,61 @@ Jekyll traverses your site looking for files to process. Any files with [YAML Fr
|
||||||
<tbody>
|
<tbody>
|
||||||
<tr>
|
<tr>
|
||||||
<td><p><code>site.time</code></p></td>
|
<td><p><code>site.time</code></p></td>
|
||||||
<td><p>The current time (when you run the <code>jekyll</code> command).</p></td>
|
<td><p>
|
||||||
|
|
||||||
|
The current time (when you run the <code>jekyll</code> command).
|
||||||
|
|
||||||
|
</p></td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td><p><code>site.posts</code></p></td>
|
<td><p><code>site.posts</code></p></td>
|
||||||
<td><p>A reverse chronological list of all Posts.</p></td>
|
<td><p>
|
||||||
|
|
||||||
|
A reverse chronological list of all Posts.
|
||||||
|
|
||||||
|
</p></td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td><p><code>site.related_posts</code></p></td>
|
<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>
|
<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>
|
||||||
<tr>
|
<tr>
|
||||||
<td><p><code>site.categories.CATEGORY</code></p></td>
|
<td><p><code>site.categories.CATEGORY</code></p></td>
|
||||||
<td><p>The list of all Posts in category <code>CATEGORY</code>.</p></td>
|
<td><p>
|
||||||
|
|
||||||
|
The list of all Posts in category <code>CATEGORY</code>.
|
||||||
|
|
||||||
|
</p></td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td><p><code>site.tags.TAG</code></p></td>
|
<td><p><code>site.tags.TAG</code></p></td>
|
||||||
<td><p>The list of all Posts with tag <code>TAG</code>.</p></td>
|
<td><p>
|
||||||
|
|
||||||
|
The list of all Posts with tag <code>TAG</code>.
|
||||||
|
|
||||||
|
</p></td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td><p><code>site.[CONFIGURATION_DATA]</code></p></td>
|
<td><p><code>site.[CONFIGURATION_DATA]</code></p></td>
|
||||||
<td><p>All variables set in 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 can be accessed using <code>{{ "{{ site.url " }}}}</code>. Jekyll does not parse changes to <code>_config.yml</code> in <code>watch</code> mode, you have to restart Jekyll to see changes to variables.</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>
|
</tr>
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
|
|
@ -85,38 +145,83 @@ Jekyll traverses your site looking for files to process. Any files with [YAML Fr
|
||||||
<tbody>
|
<tbody>
|
||||||
<tr>
|
<tr>
|
||||||
<td><p><code>page.content</code></p></td>
|
<td><p><code>page.content</code></p></td>
|
||||||
<td><p>The un-rendered content of the Page.</p></td>
|
<td><p>
|
||||||
|
|
||||||
|
The un-rendered content of the Page.
|
||||||
|
|
||||||
|
</p></td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td><p><code>page.title</code></p></td>
|
<td><p><code>page.title</code></p></td>
|
||||||
<td><p>The title of the Post.</p></td>
|
<td><p>
|
||||||
|
|
||||||
|
The title of the Post.
|
||||||
|
|
||||||
|
</p></td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td><p><code>page.url</code></p></td>
|
<td><p><code>page.url</code></p></td>
|
||||||
<td><p>The URL of the Post without the domain. e.g. <code>/2008/12/14/my-post.html</code></p></td>
|
<td><p>
|
||||||
|
|
||||||
|
The URL of the Post without the domain. e.g.
|
||||||
|
<code>/2008/12/14/my-post.html</code>
|
||||||
|
|
||||||
|
</p></td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td><p><code>page.date</code></p></td>
|
<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>
|
<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>
|
||||||
<tr>
|
<tr>
|
||||||
<td><p><code>page.id</code></p></td>
|
<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>
|
<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>
|
||||||
<tr>
|
<tr>
|
||||||
<td><p><code>page.categories</code></p></td>
|
<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.textile</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>
|
<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>
|
||||||
<tr>
|
<tr>
|
||||||
<td><p><code>page.tags</code></p></td>
|
<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>
|
<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>
|
||||||
</tbody>
|
</tbody>
|
||||||
</table>
|
</table>
|
||||||
|
|
||||||
<div class="note">
|
<div class="note">
|
||||||
<h5>ProTip™: Use custom front-matter</h5>
|
<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 in templates as <code>page.custom_css</code>.</p>
|
<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>
|
</div>
|
||||||
|
|
||||||
## Paginator
|
## Paginator
|
||||||
|
|
@ -131,7 +236,7 @@ Jekyll traverses your site looking for files to process. Any files with [YAML Fr
|
||||||
<tbody>
|
<tbody>
|
||||||
<tr>
|
<tr>
|
||||||
<td><p><code>paginator.per_page</code></p></td>
|
<td><p><code>paginator.per_page</code></p></td>
|
||||||
<td><p>Number of posts per page.</p></td>
|
<td><p>Number of Posts per page.</p></td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td><p><code>paginator.posts</code></p></td>
|
<td><p><code>paginator.posts</code></p></td>
|
||||||
|
|
@ -139,11 +244,11 @@ Jekyll traverses your site looking for files to process. Any files with [YAML Fr
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td><p><code>paginator.total_posts</code></p></td>
|
<td><p><code>paginator.total_posts</code></p></td>
|
||||||
<td><p>Total number of posts.</p></td>
|
<td><p>Total number of Posts.</p></td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td><p><code>paginator.total_pages</code></p></td>
|
<td><p><code>paginator.total_pages</code></p></td>
|
||||||
<td><p>Total number of pages.</p></td>
|
<td><p>Total number of Pages.</p></td>
|
||||||
</tr>
|
</tr>
|
||||||
<tr>
|
<tr>
|
||||||
<td><p><code>paginator.page</code></p></td>
|
<td><p><code>paginator.page</code></p></td>
|
||||||
|
|
@ -162,5 +267,10 @@ Jekyll traverses your site looking for files to process. Any files with [YAML Fr
|
||||||
|
|
||||||
<div class="note info">
|
<div class="note info">
|
||||||
<h5>Paginator variable availability</h5>
|
<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>
|
<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>
|
</div>
|
||||||
|
|
|
||||||
|
|
@ -406,7 +406,7 @@ pre, code {
|
||||||
line-height: 1.8em;
|
line-height: 1.8em;
|
||||||
}
|
}
|
||||||
|
|
||||||
.highlight, p > pre, p > code {
|
.highlight, p > pre, p > code, p > nobr > code, li > code {
|
||||||
background: #333;
|
background: #333;
|
||||||
color: #fff;
|
color: #fff;
|
||||||
border-radius: 5px;
|
border-radius: 5px;
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue