dan
/
jekyll
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

merge in changes from latest master 

conflicts:
- site/_posts/2012-07-01-permalinks.md
- site/css/style.css
- site/index.html
This commit is contained in:
Coby Chapple 2013-05-02 21:16:47 +01:00
parent e0640d6687 40b587c46c
commit 6a57d5248b
64 changed files with 2246 additions and 954 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.travis.yml
View File

@ -1,5 +1,8 @@
language: ruby
before_install:
- gem install bundler
rvm:
- 2.0.0
- 1.9.3
- 1.9.2
- 1.8.7

7
CONTRIBUTING.md
View File

@ -15,9 +15,10 @@ following in mind:
would be appreciated, and once merged it will be transferred over to the main
wiki.
* 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 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
-----------------
@ -40,7 +41,7 @@ Workflow
Here's the most direct way to get your work merged into the project:
* Fork the project.
* Clone down your fork ( `git clone git://github.com/<username>/jekyll.git` ).
* Clone down your fork ( `git clone git@github.com:<username>/jekyll.git` ).
* Create a topic branch to contain your change ( `git checkout -b my_awesome_feature` ).
* Hack away, add tests. Not necessarily in that order.
* Make sure everything still passes by running `rake`.

31
History.txt
View File

@ -4,7 +4,24 @@
* Refactored jekyll commands into subcommands: build, serve, and migrate. (#690)
* Removed importers/migrators from main project, migrated to jekyll-import sub-gem (#793)
* Added ability to render drafts in _drafts folder via command line (#833)
* Add ordinal date permalink style (/:categories/:year/:y_day/:title.html) (#928)
* Minor Enhancements
* Tell the user if there is no subcommand specified (#1008)
* Freak out if the destination of `jekyll new` exists and is non-empty (#981)
* Add `timezone` configuration option for compilation (#957)
* Add deprecation messages for pre-1.0 CLI options (#959)
* Refactor and colorize logging (#959)
* Refactor Markdown parsing (#955)
* Added application/vnd.apple.pkpass to mime.types served by WEBrick (#907)
* Move template site to default markdown renderer (#961)
* Expose new attribute to Liquid via `page`: `page.path` (#951)
* Accept multiple config files from command line (#945)
* Add page variable to liquid custom tags and blocks (#413)
* Add paginator.previous_page_path and paginator.next_page_path (#942)
* Backwards compatibility for 'auto' (#821, #934)
* Added date_to_rfc822 used on RSS feeds (#892)
* Upgrade version of pygments.rb to 0.4.2 (#927)
* Added short month (e.g. "Sep") to permalink style options for posts (#890)
* Expose site.baseurl to Liquid templates (#869)
* Adds excerpt attribute to posts which contains first paragraph of content (#837)
* Accept custom configuration file via CLI (#863)
@ -25,11 +42,19 @@
* Truncate post slugs when importing from Tumblr (#496)
* Add glob support to include, exclude option (#743)
* Layout of Page or Post defaults to 'page' or 'post', respectively (#580)
REPEALED by (#977)
* "Keep files" feature (#685)
* Output full path & name for files that don't parse (#745)
* Add source and destination directory protection (#535)
* Better YAML error message (#718)
* Bug Fixes
* Catch all exceptions, not just StandardError descendents (#1007)
* Bullet-proof limit_posts option (#1004)
* Read in YAML as UTF-8 to accept non-ASCII chars (#836)
* Fix the CLI option --plugins to actually accept dirs and files (#993)
* Allow 'excerpt' in YAML Front-Matter to override the extracted excerpt (#946)
* Fix cascade problem with site.baseurl, site.port and site.host. (#935)
* Filter out directories with valid post names (#875)
* Fix symlinked static files not being correctly built in unsafe mode (#909)
* Fix integration with directory_watcher 1.4.x (#916)
* Accepting strings as arguments to jekyll-import command (#910)
@ -48,9 +73,15 @@
* Add SVG support to Jekyll/WEBrick. (#407, #406)
* Prevent custom destination from causing continuous regen on watch (#528, #820, #862)
* Site Enhancements
* Fix spelling, punctuation and phrasal errors (#989)
* Update quickstart instructions with `new` command (#966)
* Add docs for page.excerpt (#956)
* Add docs for page.path (#951)
* Clean up site docs to prepare for 1.0 release (#918)
* Bring site into master branch with better preview/deploy (#709)
* Redesigned site (#583)
* Development fixes
* Exclude Cucumber 1.2.4, which causes tests to fail in 1.9.2 (#938)
* Added "features:html" rake task for debugging purposes, cleaned up
cucumber profiles (#832)
* Explicitly require HTTPS rubygems source in Gemfile (#826)

3
README.textile
View File

@ -31,7 +31,6 @@ h2. Runtime Dependencies
* Kramdown: Markdown-superset converter (Ruby)
* Liquid: Templating system (Ruby)
* Maruku: Default markdown engine (Ruby)
* Pygments: Syntax highlighting (Python)
h2. Developer Dependencies
@ -43,4 +42,4 @@ h2. Developer Dependencies
h2. License
See LICENSE.
See "LICENSE":https://github.com/mojombo/jekyll/blob/master/LICENSE.

18
bin/jekyll
View File

@ -6,6 +6,8 @@ $:.unshift File.join(File.dirname(__FILE__), *%w{ .. lib })
require 'commander/import'
require 'jekyll'
Jekyll::Deprecator.process(ARGV)
program :name, 'jekyll'
program :version, Jekyll::VERSION
program :description, 'Jekyll is a blog-aware, static site generator in Ruby'
@ -15,7 +17,7 @@ default_command :help
global_option '-s', '--source [DIR]', 'Source directory (defaults to ./)'
global_option '-d', '--destination [DIR]', 'Destination directory (defaults to ./_site)'
global_option '--safe', 'Safe mode (defaults to false)'
global_option '--plugins', 'Plugins directory (defaults to ./_plugins)'
global_option '--plugins PLUGINS_DIR1[,PLUGINS_DIR2[,...]]', Array, 'Plugins directory (defaults to ./_plugins)'
global_option '--layouts', 'Layouts directory (defaults to ./_layouts)'
# Option names don't always directly match the configuration value we'd like.
@ -44,15 +46,14 @@ command :build do |c|
c.syntax = 'jekyll build [options]'
c.description = 'Build your site'
c.option '--config [CONFIG_FILE]', 'Custom configuration file'
c.option '--config CONFIG_FILE[,CONFIG_FILE2,...]', Array, 'Custom configuration file'
c.option '--future', 'Publishes posts with a future date'
c.option '--limit_posts MAX_POSTS', 'Limits the number of posts to parse and publish'
c.option '--limit_posts MAX_POSTS', Integer, 'Limits the number of posts to parse and publish'
c.option '-w', '--watch', 'Watch for changes and rebuild'
c.option '--lsi', 'Use LSI for improved related posts'
c.option '--drafts', 'Render posts in the _drafts folder'
c.action do |args, options|
options.defaults :serving => false
options = normalize_options(options.__hash__)
options = Jekyll.configuration(options)
Jekyll::Commands::Build.process(options)
@ -63,9 +64,9 @@ command :serve do |c|
c.syntax = 'jekyll serve [options]'
c.description = 'Serve your site locally'
c.option '--config [CONFIG_FILE]', 'Custom configuration file'
c.option '--config CONFIG_FILE[,CONFIG_FILE2,...]', Array, 'Custom configuration file'
c.option '--future', 'Publishes posts with a future date'
c.option '--limit_posts MAX_POSTS', 'Limits the number of posts to parse and publish'
c.option '--limit_posts MAX_POSTS', Integer, 'Limits the number of posts to parse and publish'
c.option '-w', '--watch', 'Watch for changes and rebuild'
c.option '--lsi', 'Use LSI for improved related posts'
c.option '--drafts', 'Render posts in the _drafts folder'
@ -75,10 +76,7 @@ command :serve do |c|
c.option '-b', '--baseurl [URL]', 'Base URL'
c.action do |args, options|
options.default :port => '4000',
:host => '0.0.0.0',
:baseurl => '/',
:serving => true
options.default :serving => true
options = normalize_options(options.__hash__)
options = Jekyll.configuration(options)

24
features/post_data.feature
View File

@ -153,6 +153,30 @@ Feature: Post data
And I should see "Post categories: scifi and movies" in "_site/scifi/movies/2009/03/27/star-wars.html"
And I should see "Post categories: scifi and movies" in "_site/scifi/movies/2013/03/17/star-trek.html"
Scenario Outline: Use page.path variable
Given I have a <dir>/_posts directory
And I have the following post in "<dir>":
| title | type | date | content |
| my-post | html | 4/12/2013 | Source path: {{ page.path }} |
When I run jekyll
Then the _site directory should exist
And I should see "Source path: <path_prefix>_posts/2013-04-12-my-post.html" in "_site/<dir>/2013/04/12/my-post.html"
Examples:
| dir | path_prefix |
| . | |
| dir | dir/ |
| dir/nested | dir/nested/ |
Scenario: Override page.path variable
Given I have a _posts directory
And I have the following post:
| title | date | path | content |
| override | 4/12/2013 | override-path.html | Custom path: {{ page.path }} |
When I run jekyll
Then the _site directory should exist
And I should see "Custom path: override-path.html" in "_site/2013/04/12/override.html"
Scenario: Disable a post from being published
Given I have a _posts directory
And I have an "index.html" file that contains "Published!"

40
features/site_configuration.feature
View File

@ -116,6 +116,46 @@ Feature: Site configuration
And I should see "Post Layout: <p>content for entry1.</p>" in "_site/2007/12/31/entry1.html"
And I should see "Post Layout: <p>content for entry2.</p>" in "_site/2020/01/31/entry2.html"
Scenario: Generate proper dates with explicitly set timezone (same as posts' time)
Given I have a _layouts directory
And I have a page layout that contains "Page Layout: {{ site.posts.size }}"
And I have a post layout that contains "Post Layout: {{ content }} built at {{ page.date | date_to_xmlschema }}"
And I have an "index.html" page with layout "page" that contains "site index page"
And I have a configuration file with:
| key | value |
| timezone | America/New_York |
And I have a _posts directory
And I have the following posts:
| title | date | layout | content |
| entry1 | 2013-04-09 23:22 -0400 | post | content for entry1. |
| entry2 | 2013-04-10 03:14 -0400 | post | content for entry2. |
When I run jekyll
Then the _site directory should exist
And I should see "Page Layout: 2" in "_site/index.html"
And I should see "Post Layout: <p>content for entry1.</p> built at 2013-04-09T23:22:00-04:00" in "_site/2013/04/09/entry1.html"
And I should see "Post Layout: <p>content for entry2.</p> built at 2013-04-10T03:14:00-04:00" in "_site/2013/04/10/entry2.html"
Scenario: Generate proper dates with explicitly set timezone (different than posts' time)
Given I have a _layouts directory
And I have a page layout that contains "Page Layout: {{ site.posts.size }}"
And I have a post layout that contains "Post Layout: {{ content }} built at {{ page.date | date_to_xmlschema }}"
And I have an "index.html" page with layout "page" that contains "site index page"
And I have a configuration file with:
| key | value |
| timezone | Australia/Melbourne |
And I have a _posts directory
And I have the following posts:
| title | date | layout | content |
| entry1 | 2013-04-09 23:22 -0400 | post | content for entry1. |
| entry2 | 2013-04-10 03:14 -0400 | post | content for entry2. |
When I run jekyll
Then the _site directory should exist
And I should see "Page Layout: 2" in "_site/index.html"
And the "_site/2013/04/10/entry1.html" file should exist
And the "_site/2013/04/10/entry2.html" file should exist
And I should see escaped "Post Layout: <p>content for entry1.</p> built at 2013-04-10T13:22:00+10:00" in "_site/2013/04/10/entry1.html"
And I should see escaped "Post Layout: <p>content for entry2.</p> built at 2013-04-10T17:14:00+10:00" in "_site/2013/04/10/entry2.html"
Scenario: Limit the number of posts generated by most recent date
Given I have a _posts directory
And I have a configuration file with:

19
features/site_data.feature
View File

@ -9,6 +9,25 @@ Feature: Site data
Then the _site directory should exist
And I should see "Contact: email@me.com" in "_site/contact.html"
Scenario Outline: Use page.path variable in a page
Given I have a <dir> directory
And I have a "<path>" page that contains "Source path: {{ page.path }}"
When I run jekyll
Then the _site directory should exist
And I should see "Source path: <path>" in "_site/<path>"
Examples:
| dir | path |
| . | index.html |
| dir | dir/about.html |
| dir/nested | dir/nested/page.html |
Scenario: Override page.path
Given I have an "override.html" page with path "custom-override.html" that contains "Custom path: {{ page.path }}"
When I run jekyll
Then the _site directory should exist
And I should see "Custom path: custom-override.html" in "_site/override.html"
Scenario: Use site.time variable
Given I have an "index.html" page that contains "{{ site.time }}"
When I run jekyll

29
features/step_definitions/jekyll_steps.rb
View File

@ -1,4 +1,5 @@
Before do
FileUtils.rm_rf(TEST_DIR)
FileUtils.mkdir(TEST_DIR)
Dir.chdir(TEST_DIR)
end
@ -21,28 +22,24 @@ Given /^I have an? "(.*)" page(?: with (.*) "(.*)")? that contains "(.*)"$/ do |
---
#{text}
EOF
f.close
end
end
Given /^I have an? "(.*)" file that contains "(.*)"$/ do |file, text|
File.open(file, 'w') do |f|
f.write(text)
f.close
end
end
Given /^I have a (.*) layout that contains "(.*)"$/ do |layout, text|
File.open(File.join('_layouts', layout + '.html'), 'w') do |f|
f.write(text)
f.close
end
end
Given /^I have a (.*) theme that contains "(.*)"$/ do |layout, text|
File.open(File.join('_theme', layout + '.html'), 'w') do |f|
f.write(text)
f.close
end
end
@ -65,14 +62,24 @@ Given /^I have the following (draft|post)s?(?: (.*) "(.*)")?:$/ do |status, dire
if "draft" == status
path = File.join(before || '.', '_drafts', after || '.', "#{title}.#{ext}")
else
date = Date.strptime(post['date'], '%m/%d/%Y').strftime('%Y-%m-%d')
format = if has_time_component?(post['date'])
'%Y-%m-%d %H:%M %z'
else
'%m/%d/%Y' # why even
end
parsed_date = DateTime.strptime(post['date'], format)
post['date'] = parsed_date.to_s
date = parsed_date.strftime('%Y-%m-%d')
path = File.join(before || '.', '_posts', after || '.', "#{date}-#{title}.#{ext}")
end
matter_hash = {}
%w(title layout tag tags category categories published author).each do |key|
%w(title layout tag tags category categories published author path).each do |key|
matter_hash[key] = post[key] if post[key]
end
if "post" == status
matter_hash["date"] = post["date"] if post["date"]
end
matter = matter_hash.map { |k, v| "#{k}: #{v}\n" }.join.chomp
content = post['content']
@ -87,7 +94,6 @@ Given /^I have the following (draft|post)s?(?: (.*) "(.*)")?:$/ do |status, dire
---
#{content}
EOF
f.close
end
end
end
@ -95,7 +101,6 @@ end
Given /^I have a configuration file with "(.*)" set to "(.*)"$/ do |key, value|
File.open('_config.yml', 'w') do |f|
f.write("#{key}: #{value}\n")
f.close
end
end
@ -104,7 +109,6 @@ Given /^I have a configuration file with:$/ do |table|
table.hashes.each do |row|
f.write("#{row["key"]}: #{row["value"]}\n")
end
f.close
end
end
@ -114,7 +118,6 @@ Given /^I have a configuration file with "([^\"]*)" set to:$/ do |key, table|
table.hashes.each do |row|
f.write("- #{row["value"]}\n")
end
f.close
end
end
@ -142,7 +145,11 @@ Then /^the (.*) directory should exist$/ do |dir|
end
Then /^I should see "(.*)" in "(.*)"$/ do |text, file|
assert_match Regexp.new(text), File.open(file).readlines.join
assert Regexp.new(text).match(File.open(file).readlines.join)
end
Then /^I should see escaped "(.*)" in "(.*)"$/ do |text, file|
assert Regexp.new(Regexp.escape(text)).match(File.open(file).readlines.join)
end
Then /^the "(.*)" file should exist$/ do |file|

6
features/support/env.rb
View File

@ -7,7 +7,7 @@ World do
end
TEST_DIR = File.join('/', 'tmp', 'jekyll')
JEKYLL_PATH = File.join(ENV['PWD'], 'bin', 'jekyll')
JEKYLL_PATH = File.join(File.dirname(__FILE__), '..', '..', 'bin', 'jekyll')
def run_jekyll(opts = {})
command = JEKYLL_PATH.clone
@ -17,5 +17,9 @@ def run_jekyll(opts = {})
system command
end
def has_time_component?(date_string)
date_string.split(" ").size > 1
end
# work around "invalid option: --format" cucumber bug (see #296)
Test::Unit.run = true if RUBY_VERSION < '1.9'

20
jekyll.gemspec
View File

@ -4,9 +4,9 @@ Gem::Specification.new do |s|
s.rubygems_version = '1.3.5'
s.name = 'jekyll'
s.version = '1.0.0.beta2'
s.version = '1.0.0.rc1'
s.license = 'MIT'
s.date = '2013-03-19'
s.date = '2013-04-16'
s.rubyforge_project = 'jekyll'
s.summary = "A simple, blog aware, static site generator."
@ -28,16 +28,17 @@ Gem::Specification.new do |s|
s.add_runtime_dependency('directory_watcher', "~> 1.4.1")
s.add_runtime_dependency('maruku', "~> 0.5")
s.add_runtime_dependency('kramdown', "~> 0.14")
s.add_runtime_dependency('pygments.rb', "~> 0.3.2")
s.add_runtime_dependency('pygments.rb', "~> 0.4.2")
s.add_runtime_dependency('commander', "~> 4.1.3")
s.add_runtime_dependency('safe_yaml', "~> 0.7.0")
s.add_runtime_dependency('colorator', "~> 0.1")
s.add_development_dependency('rake', "~> 10.0.3")
s.add_development_dependency('rdoc', "~> 3.11")
s.add_development_dependency('redgreen', "~> 1.2")
s.add_development_dependency('shoulda', "~> 3.3.2")
s.add_development_dependency('rr', "~> 1.0")
s.add_development_dependency('cucumber', "~> 1.2.1")
s.add_development_dependency('cucumber', "~> 1.2.1", '!= 1.2.4')
s.add_development_dependency('RedCloth', "~> 4.2")
s.add_development_dependency('rdiscount', "~> 1.6")
s.add_development_dependency('redcarpet', "~> 2.2.2")
@ -72,18 +73,25 @@ Gem::Specification.new do |s|
lib/jekyll/commands/build.rb
lib/jekyll/commands/new.rb
lib/jekyll/commands/serve.rb
lib/jekyll/configuration.rb
lib/jekyll/converter.rb
lib/jekyll/converters/identity.rb
lib/jekyll/converters/markdown.rb
lib/jekyll/converters/markdown/kramdown_parser.rb
lib/jekyll/converters/markdown/maruku_parser.rb
lib/jekyll/converters/markdown/rdiscount_parser.rb
lib/jekyll/converters/markdown/redcarpet_parser.rb
lib/jekyll/converters/textile.rb
lib/jekyll/convertible.rb
lib/jekyll/core_ext.rb
lib/jekyll/deprecator.rb
lib/jekyll/draft.rb
lib/jekyll/errors.rb
lib/jekyll/filters.rb
lib/jekyll/generator.rb
lib/jekyll/generators/pagination.rb
lib/jekyll/layout.rb
lib/jekyll/logger.rb
lib/jekyll/mime.types
lib/jekyll/page.rb
lib/jekyll/plugin.rb
@ -192,6 +200,8 @@ Gem::Specification.new do |s|
test/source/_posts/2013-01-02-post-excerpt.markdown
test/source/_posts/2013-01-12-nil-layout.textile
test/source/_posts/2013-01-12-no-layout.textile
test/source/_posts/2013-03-19-not-a-post.markdown/.gitkeep
test/source/_posts/2013-04-11-custom-excerpt.markdown
test/source/about.html
test/source/category/_posts/2008-9-23-categories.textile
test/source/contacts.html
@ -202,6 +212,8 @@ Gem::Specification.new do |s|
test/source/foo/_posts/bar/2008-12-12-topical-post.textile
test/source/index.html
test/source/sitemap.xml
test/source/symlink-test/symlinked-dir
test/source/symlink-test/symlinked-file
test/source/win/_posts/2009-05-24-yaml-linebreak.markdown
test/source/z_category/_posts/2008-9-23-categories.textile
test/suite.rb

114
lib/jekyll.rb
View File

@ -25,9 +25,13 @@ require 'English'
require 'liquid'
require 'maruku'
require 'pygments'
require 'colorator'
# internal requires
require 'jekyll/core_ext'
require 'jekyll/logger'
require 'jekyll/deprecator'
require 'jekyll/configuration'
require 'jekyll/site'
require 'jekyll/convertible'
require 'jekyll/layout'
@ -46,113 +50,41 @@ require 'jekyll/command'
require_all 'jekyll/commands'
require_all 'jekyll/converters'
require_all 'jekyll/converters/markdown'
require_all 'jekyll/generators'
require_all 'jekyll/tags'
SafeYAML::OPTIONS[:suppress_warnings] = true
module Jekyll
VERSION = '1.0.0.beta2'
# Default options. Overriden by values in _config.yml.
# Strings rather than symbols are used for compatability with YAML.
DEFAULTS = {
'source' => Dir.pwd,
'destination' => File.join(Dir.pwd, '_site'),
'plugins' => '_plugins',
'layouts' => '_layouts',
'keep_files' => ['.git','.svn'],
'future' => true, # remove and make true just default
'pygments' => true, # remove and make true just default
'markdown' => 'maruku',
'permalink' => 'date',
'baseurl' => '',
'include' => ['.htaccess'],
'paginate_path' => 'page:num',
'markdown_ext' => 'markdown,mkd,mkdn,md',
'textile_ext' => 'textile',
'excerpt_separator' => "\n\n",
'maruku' => {
'use_tex' => false,
'use_divs' => false,
'png_engine' => 'blahtex',
'png_dir' => 'images/latex',
'png_url' => '/images/latex'
},
'rdiscount' => {
'extensions' => []
},
'redcarpet' => {
'extensions' => []
},
'kramdown' => {
'auto_ids' => true,
'footnote_nr' => 1,
'entity_output' => 'as_char',
'toc_levels' => '1..6',
'smart_quotes' => 'lsquo,rsquo,ldquo,rdquo',
'use_coderay' => false,
'coderay' => {
'coderay_wrap' => 'div',
'coderay_line_numbers' => 'inline',
'coderay_line_number_start' => 1,
'coderay_tab_width' => 4,
'coderay_bold_every' => 10,
'coderay_css' => 'style'
}
},
'redcloth' => {
'hard_breaks' => true
}
}
VERSION = '1.0.0.rc1'
# Public: Generate a Jekyll configuration Hash by merging the default
# options with anything in _config.yml, and adding the given options on top.
#
# override - A Hash of config directives that override any options in both
# the defaults and the config file. See Jekyll::DEFAULTS for a
# the defaults and the config file. See Jekyll::Configuration::DEFAULTS for a
# list of option names and their defaults.
#
# Returns the final configuration Hash.
def self.configuration(override)
# Convert any symbol keys to strings and remove the old key/values
override = override.reduce({}) { |hsh,(k,v)| hsh.merge(k.to_s => v) }
# _config.yml may override default source location, but until
# then, we need to know where to look for _config.yml
source = override['source'] || Jekyll::DEFAULTS['source']
# Get configuration from <source>/_config.yml or <source>/<config_file>
config_file = override.delete('config')
config_file = File.join(source, "_config.yml") if config_file.to_s.empty?
begin
config = YAML.safe_load_file(config_file)
raise "Configuration file: (INVALID) #{config_file}" if !config.is_a?(Hash)
$stdout.puts "Configuration file: #{config_file}"
rescue SystemCallError
# Errno:ENOENT = file not found
$stderr.puts "Configuration file: none"
config = {}
rescue => err
$stderr.puts " " +
"WARNING: Error reading configuration. " +
"Using defaults (and options)."
$stderr.puts "#{err}"
config = {}
end
config = Configuration[Configuration::DEFAULTS]
override = Configuration[override].stringify_keys
config = config.read_config_files(config.config_files(override))
# Merge DEFAULTS < _config.yml < override
Jekyll::DEFAULTS.deep_merge(config).deep_merge(override)
config = config.deep_merge(override).stringify_keys
set_timezone(config['timezone']) if config['timezone']
config
end
# Static: Set the TZ environment variable to use the timezone specified
#
# timezone - the IANA Time Zone
#
# Returns nothing
def self.set_timezone(timezone)
ENV['TZ'] = timezone
end
end

15
lib/jekyll/command.rb
View File

@ -8,5 +8,20 @@ module Jekyll
dirs += ['*']
end
end
# Static: Run Site#process and catch errors
#
# site - the Jekyll::Site object
#
# Returns nothing
def self.process_site(site)
site.process
rescue Jekyll::FatalException => e
puts
Jekyll::Logger.error "ERROR:", "YOUR SITE COULD NOT BE BUILT:"
Jekyll::Logger.error "", "------------------------------------"
Jekyll::Logger.error "", e.message
exit(1)
end
end
end

30
lib/jekyll/commands/build.rb
View File

@ -17,18 +17,10 @@ module Jekyll
def self.build(site, options)
source = options['source']
destination = options['destination']
puts " Source: #{source}"
puts " Destination: #{destination}"
print " Generating... "
begin
site.process
rescue Jekyll::FatalException => e
puts
puts "ERROR: YOUR SITE COULD NOT BE BUILT:"
puts "------------------------------------"
puts e.message
exit(1)
end
Jekyll::Logger.info "Source:", source
Jekyll::Logger.info "Destination:", destination
print Jekyll::Logger.formatted_topic "Generating..."
self.process_site(site)
puts "done."
end
@ -44,23 +36,15 @@ module Jekyll
source = options['source']
destination = options['destination']
puts " Auto-regeneration: enabled"
Jekyll::Logger.info "Auto-regeneration:", "enabled"
dw = DirectoryWatcher.new(source, :glob => self.globs(source, destination), :pre_load => true)
dw.interval = 1
dw.add_observer do |*args|
t = Time.now.strftime("%Y-%m-%d %H:%M:%S")
print " Regenerating: #{args.size} files at #{t} "
begin
site.process
rescue Jekyll::FatalException => e
puts
puts "ERROR: YOUR SITE COULD NOT BE BUILT:"
puts "------------------------------------"
puts e.message
exit(1)
end
print Jekyll::Logger.formatted_topic("Regenerating:") + "#{args.size} files at #{t} "
self.process_site(site)
puts "...done."
end

4
lib/jekyll/commands/new.rb
View File

@ -8,6 +8,10 @@ module Jekyll
new_blog_path = File.expand_path(args.join(" "), Dir.pwd)
FileUtils.mkdir_p new_blog_path
unless Dir["#{new_blog_path}/**/*"].empty?
Jekyll::Logger.error "Conflict:", "#{new_blog_path} exists and is not empty."
exit(1)
end
create_sample_files new_blog_path

171
lib/jekyll/configuration.rb Normal file
View File

@ -0,0 +1,171 @@
# encoding: UTF-8
module Jekyll
class Configuration < Hash
# Default options. Overriden by values in _config.yml.
# Strings rather than symbols are used for compatability with YAML.
DEFAULTS = {
'source' => Dir.pwd,
'destination' => File.join(Dir.pwd, '_site'),
'plugins' => '_plugins',
'layouts' => '_layouts',
'keep_files' => ['.git','.svn'],
'timezone' => nil, # use the local timezone
'safe' => false,
'show_drafts' => nil,
'limit_posts' => 0,
'lsi' => false,
'future' => true, # remove and make true just default
'pygments' => true, # remove and make true just default
'markdown' => 'maruku',
'permalink' => 'date',
'baseurl' => '/',
'include' => ['.htaccess'],
'exclude' => [],
'paginate_path' => 'page:num',
'markdown_ext' => 'markdown,mkd,mkdn,md',
'textile_ext' => 'textile',
'port' => '4000',
'host' => '0.0.0.0',
'excerpt_separator' => "\n\n",
'maruku' => {
'use_tex' => false,
'use_divs' => false,
'png_engine' => 'blahtex',
'png_dir' => 'images/latex',
'png_url' => '/images/latex'
},
'rdiscount' => {
'extensions' => []
},
'redcarpet' => {
'extensions' => []
},
'kramdown' => {
'auto_ids' => true,
'footnote_nr' => 1,
'entity_output' => 'as_char',
'toc_levels' => '1..6',
'smart_quotes' => 'lsquo,rsquo,ldquo,rdquo',
'use_coderay' => false,
'coderay' => {
'coderay_wrap' => 'div',
'coderay_line_numbers' => 'inline',
'coderay_line_number_start' => 1,
'coderay_tab_width' => 4,
'coderay_bold_every' => 10,
'coderay_css' => 'style'
}
},
'redcloth' => {
'hard_breaks' => true
}
}
# Public: Turn all keys into string
#
# Return a copy of the hash where all its keys are strings
def stringify_keys
reduce({}) { |hsh,(k,v)| hsh.merge(k.to_s => v) }
end
# Public: Directory of the Jekyll source folder
#
# override - the command-line options hash
#
# Returns the path to the Jekyll source directory
def source(override)
override['source'] || self['source'] || DEFAULTS['source']
end
# Public: Generate list of configuration files from the override
#
# override - the command-line options hash
#
# Returns an Array of config files
def config_files(override)
# Get configuration from <source>/_config.yml or <source>/<config_file>
config_files = override.delete('config')
config_files = File.join(source(override), "_config.yml") if config_files.to_s.empty?
config_files = [config_files] unless config_files.is_a? Array
config_files
end
# Public: Read configuration and return merged Hash
#
# file - the path to the YAML file to be read in
#
# Returns this configuration, overridden by the values in the file
def read_config_file(file)
next_config = YAML.safe_load_file(file)
raise "Configuration file: (INVALID) #{file}".yellow if !next_config.is_a?(Hash)
Jekyll::Logger.info "Configuration file:", file
next_config
end
# Public: Read in a list of configuration files and merge with this hash
#
# files - the list of configuration file paths
#
# Returns the full configuration, with the defaults overridden by the values in the
# configuration files
def read_config_files(files)
configuration = clone
begin
files.each do |config_file|
new_config = read_config_file(config_file)
configuration = configuration.deep_merge(new_config)
end
rescue SystemCallError
# Errno:ENOENT = file not found
Jekyll::Logger.warn "Configuration file:", "none"
rescue => err
Jekyll::Logger.warn "WARNING:", "Error reading configuration. " +
"Using defaults (and options)."
$stderr.puts "#{err}"
end
configuration.backwards_compatibilize
end
# Public: Ensure the proper options are set in the configuration to allow for
# backwards-compatibility with Jekyll pre-1.0
#
# Returns the backwards-compatible configuration
def backwards_compatibilize
config = clone
# Provide backwards-compatibility
if config.has_key?('auto') || config.has_key?('watch')
Jekyll::Logger.warn "Deprecation:", "Auto-regeneration can no longer" +
" be set from your configuration file(s). Use the"+
" --watch/-w command-line option instead."
config.delete('auto')
config.delete('watch')
end
if config.has_key? 'server'
Jekyll::Logger.warn "Deprecation:", "The 'server' configuration option" +
" is no longer accepted. Use the 'jekyll serve'" +
" subcommand to serve your site with WEBrick."
config.delete('server')
end
config
end
end
end

120
lib/jekyll/converters/markdown.rb
View File

@ -8,82 +8,18 @@ module Jekyll
def setup
return if @setup
case @config['markdown']
@parser = case @config['markdown']
when 'redcarpet'
begin
require 'redcarpet'
@renderer ||= Class.new(Redcarpet::Render::HTML) do
def block_code(code, lang)
lang = lang && lang.split.first || "text"
output = add_code_tags(
Pygments.highlight(code, :lexer => lang, :options => { :encoding => 'utf-8' }),
lang
)
end
def add_code_tags(code, lang)
code = code.sub(/<pre>/,'<pre><code class="' + lang + '">')
code = code.sub(/<\/pre>/,"</code></pre>")
end
end
@redcarpet_extensions = {}
@config['redcarpet']['extensions'].each { |e| @redcarpet_extensions[e.to_sym] = true }
rescue LoadError
STDERR.puts 'You are missing a library required for Markdown. Please run:'
STDERR.puts ' $ [sudo] gem install redcarpet'
raise FatalException.new("Missing dependency: redcarpet")
end
RedcarpetParser.new @config
when 'kramdown'
begin
require 'kramdown'
rescue LoadError
STDERR.puts 'You are missing a library required for Markdown. Please run:'
STDERR.puts ' $ [sudo] gem install kramdown'
raise FatalException.new("Missing dependency: kramdown")
end
KramdownParser.new @config
when 'rdiscount'
begin
require 'rdiscount'
@rdiscount_extensions = @config['rdiscount']['extensions'].map { |e| e.to_sym }
rescue LoadError
STDERR.puts 'You are missing a library required for Markdown. Please run:'
STDERR.puts ' $ [sudo] gem install rdiscount'
raise FatalException.new("Missing dependency: rdiscount")
end
RDiscountParser.new @config
when 'maruku'
begin
require 'maruku'
if @config['maruku']['use_divs']
require 'maruku/ext/div'
STDERR.puts 'Maruku: Using extended syntax for div elements.'
end
if @config['maruku']['use_tex']
require 'maruku/ext/math'
STDERR.puts "Maruku: Using LaTeX extension. Images in `#{@config['maruku']['png_dir']}`."
# Switch off MathML output
MaRuKu::Globals[:html_math_output_mathml] = false
MaRuKu::Globals[:html_math_engine] = 'none'
# Turn on math to PNG support with blahtex
# Resulting PNGs stored in `images/latex`
MaRuKu::Globals[:html_math_output_png] = true
MaRuKu::Globals[:html_png_engine] = @config['maruku']['png_engine']
MaRuKu::Globals[:html_png_dir] = @config['maruku']['png_dir']
MaRuKu::Globals[:html_png_url] = @config['maruku']['png_url']
end
rescue LoadError
STDERR.puts 'You are missing a library required for Markdown. Please run:'
STDERR.puts ' $ [sudo] gem install maruku'
raise FatalException.new("Missing dependency: maruku")
end
MarukuParser.new @config
else
STDERR.puts "Invalid Markdown processor: #{@config['markdown']}"
STDERR.puts " Valid options are [ maruku | rdiscount | kramdown ]"
STDERR.puts " Valid options are [ maruku | rdiscount | kramdown | redcarpet ]"
raise FatalException.new("Invalid Markdown process: #{@config['markdown']}")
end
@setup = true
@ -100,49 +36,7 @@ module Jekyll
def convert(content)
setup
case @config['markdown']
when 'redcarpet'
@redcarpet_extensions[:fenced_code_blocks] = !@redcarpet_extensions[:no_fenced_code_blocks]
@renderer.send :include, Redcarpet::Render::SmartyPants if @redcarpet_extensions[:smart]
markdown = Redcarpet::Markdown.new(@renderer.new(@redcarpet_extensions), @redcarpet_extensions)
markdown.render(content)
when 'kramdown'
# Check for use of coderay
if @config['kramdown']['use_coderay']
Kramdown::Document.new(content, {
:auto_ids => @config['kramdown']['auto_ids'],
:footnote_nr => @config['kramdown']['footnote_nr'],
:entity_output => @config['kramdown']['entity_output'],
:toc_levels => @config['kramdown']['toc_levels'],
:smart_quotes => @config['kramdown']['smart_quotes'],
:coderay_wrap => @config['kramdown']['coderay']['coderay_wrap'],
:coderay_line_numbers => @config['kramdown']['coderay']['coderay_line_numbers'],
:coderay_line_number_start => @config['kramdown']['coderay']['coderay_line_number_start'],
:coderay_tab_width => @config['kramdown']['coderay']['coderay_tab_width'],
:coderay_bold_every => @config['kramdown']['coderay']['coderay_bold_every'],
:coderay_css => @config['kramdown']['coderay']['coderay_css']
}).to_html
else
# not using coderay
Kramdown::Document.new(content, {
:auto_ids => @config['kramdown']['auto_ids'],
:footnote_nr => @config['kramdown']['footnote_nr'],
:entity_output => @config['kramdown']['entity_output'],
:toc_levels => @config['kramdown']['toc_levels'],
:smart_quotes => @config['kramdown']['smart_quotes']
}).to_html
end
when 'rdiscount'
rd = RDiscount.new(content, *@rdiscount_extensions)
html = rd.to_html
if rd.generate_toc and html.include?(@config['rdiscount']['toc_token'])
html.gsub!(@config['rdiscount']['toc_token'], rd.toc_content.force_encoding('utf-8'))
end
html
when 'maruku'
Maruku.new(content).to_html
end
@parser.convert(content)
end
end
end

44
lib/jekyll/converters/markdown/kramdown_parser.rb Normal file
View File

@ -0,0 +1,44 @@
module Jekyll
module Converters
class Markdown
class KramdownParser
def initialize(config)
require 'kramdown'
@config = config
rescue LoadError
STDERR.puts 'You are missing a library required for Markdown. Please run:'
STDERR.puts ' $ [sudo] gem install kramdown'
raise FatalException.new("Missing dependency: kramdown")
end
def convert(content)
# Check for use of coderay
kramdown_configs = if @config['kramdown']['use_coderay']
base_kramdown_configs.merge({
:coderay_wrap => @config['kramdown']['coderay']['coderay_wrap'],
:coderay_line_numbers => @config['kramdown']['coderay']['coderay_line_numbers'],
:coderay_line_number_start => @config['kramdown']['coderay']['coderay_line_number_start'],
:coderay_tab_width => @config['kramdown']['coderay']['coderay_tab_width'],
:coderay_bold_every => @config['kramdown']['coderay']['coderay_bold_every'],
:coderay_css => @config['kramdown']['coderay']['coderay_css']
})
else
# not using coderay
base_kramdown_configs
end
Kramdown::Document.new(content, kramdown_configs).to_html
end
def base_kramdown_configs
{
:auto_ids => @config['kramdown']['auto_ids'],
:footnote_nr => @config['kramdown']['footnote_nr'],
:entity_output => @config['kramdown']['entity_output'],
:toc_levels => @config['kramdown']['toc_levels'],
:smart_quotes => @config['kramdown']['smart_quotes']
}
end
end
end
end
end

47
lib/jekyll/converters/markdown/maruku_parser.rb Normal file
View File

@ -0,0 +1,47 @@
module Jekyll
module Converters
class Markdown
class MarukuParser
def initialize(config)
require 'maruku'
@config = config
if @config['maruku']['use_divs']
load_divs_library
end
if @config['maruku']['use_tex']
load_blahtext_library
end
rescue LoadError
STDERR.puts 'You are missing a library required for Markdown. Please run:'
STDERR.puts ' $ [sudo] gem install maruku'
raise FatalException.new("Missing dependency: maruku")
end
def load_divs_library
require 'maruku/ext/div'
STDERR.puts 'Maruku: Using extended syntax for div elements.'
end
def load_blahtext_library
require 'maruku/ext/math'
STDERR.puts "Maruku: Using LaTeX extension. Images in `#{@config['maruku']['png_dir']}`."
# Switch off MathML output
MaRuKu::Globals[:html_math_output_mathml] = false
MaRuKu::Globals[:html_math_engine] = 'none'
# Turn on math to PNG support with blahtex
# Resulting PNGs stored in `images/latex`
MaRuKu::Globals[:html_math_output_png] = true
MaRuKu::Globals[:html_png_engine] = @config['maruku']['png_engine']
MaRuKu::Globals[:html_png_dir] = @config['maruku']['png_dir']
MaRuKu::Globals[:html_png_url] = @config['maruku']['png_url']
end
def convert(content)
Maruku.new(content).to_html
end
end
end
end
end

26
lib/jekyll/converters/markdown/rdiscount_parser.rb Normal file
View File

@ -0,0 +1,26 @@
module Jekyll
module Converters
class Markdown
class RDiscountParser
def initialize(config)
require 'rdiscount'
@config = config
@rdiscount_extensions = @config['rdiscount']['extensions'].map { |e| e.to_sym }
rescue LoadError
STDERR.puts 'You are missing a library required for Markdown. Please run:'
STDERR.puts ' $ [sudo] gem install rdiscount'
raise FatalException.new("Missing dependency: rdiscount")
end
def convert(content)
rd = RDiscount.new(content, *@rdiscount_extensions)
html = rd.to_html
if rd.generate_toc and html.include?(@config['rdiscount']['toc_token'])
html.gsub!(@config['rdiscount']['toc_token'], rd.toc_content.force_encoding('utf-8'))
end
html
end
end
end
end
end

40
lib/jekyll/converters/markdown/redcarpet_parser.rb Normal file
View File

@ -0,0 +1,40 @@
module Jekyll
module Converters
class Markdown
class RedcarpetParser
def initialize(config)
require 'redcarpet'
@config = config
@redcarpet_extensions = {}
@config['redcarpet']['extensions'].each { |e| @redcarpet_extensions[e.to_sym] = true }
@renderer ||= Class.new(Redcarpet::Render::HTML) do
def block_code(code, lang)
lang = lang && lang.split.first || "text"
output = add_code_tags(
Pygments.highlight(code, :lexer => lang, :options => { :encoding => 'utf-8' }),
lang
)
end
def add_code_tags(code, lang)
code = code.sub(/<pre>/,'<pre><code class="' + lang + '">')
code = code.sub(/<\/pre>/,"</code></pre>")
end
end
rescue LoadError
STDERR.puts 'You are missing a library required for Markdown. Please run:'
STDERR.puts ' $ [sudo] gem install redcarpet'
raise FatalException.new("Missing dependency: redcarpet")
end
def convert(content)
@redcarpet_extensions[:fenced_code_blocks] = !@redcarpet_extensions[:no_fenced_code_blocks]
@renderer.send :include, Redcarpet::Render::SmartyPants if @redcarpet_extensions[:smart]
markdown = Redcarpet::Markdown.new(@renderer.new(@redcarpet_extensions), @redcarpet_extensions)
markdown.render(content)
end
end
end
end
end

92
lib/jekyll/convertible.rb
View File

@ -1,3 +1,5 @@
# encoding: UTF-8
require 'set'
# Convertible provides methods for converting a pagelike item
@ -32,10 +34,10 @@ module Jekyll
self.content = $POSTMATCH
self.data = YAML.safe_load($1)
end
rescue => e
puts "Error reading file #{File.join(base, name)}: #{e.message}"
rescue SyntaxError => e
puts "YAML Exception reading #{File.join(base, name)}: #{e.message}"
rescue Exception => e
puts "Error reading file #{File.join(base, name)}: #{e.message}"
end
self.data ||= {}
@ -64,34 +66,31 @@ module Jekyll
@converter ||= self.site.converters.find { |c| c.matches(self.ext) }
end
# Add any necessary layouts to this convertible document.
# Render Liquid in the content
#
# payload - The site payload Hash.
# layouts - A Hash of {"name" => "layout"}.
# content - the raw Liquid content to render
# payload - the payload for Liquid
# info - the info for Liquid
#
# Returns nothing.
def do_layout(payload, layouts)
info = { :filters => [Jekyll::Filters], :registers => { :site => self.site } }
# render and transform content (this becomes the final content of the object)
payload["pygments_prefix"] = converter.pygments_prefix
payload["pygments_suffix"] = converter.pygments_suffix
begin
self.content = Liquid::Template.parse(self.content).render!(payload, info)
rescue => e
puts "Liquid Exception: #{e.message} in #{self.name}"
# Returns the converted content
def render_liquid(content, payload, info)
Liquid::Template.parse(content).render!(payload, info)
rescue Exception => e
Jekyll::Logger.error "Liquid Exception:", "#{e.message} in #{payload[:file]}"
e.backtrace.each do |backtrace|
puts backtrace
end
abort("Build Failed")
end
self.transform
# output keeps track of what will finally be written
self.output = self.content
# Recursively render layouts
#
# layouts - a list of the layouts
# payload - the payload for Liquid
# info - the info for Liquid
#
# Returns nothing
def render_all_layouts(layouts, payload, info)
# recursively render layouts
layout = layouts[self.data["layout"]]
used = Set.new([layout])
@ -99,15 +98,9 @@ module Jekyll
while layout
payload = payload.deep_merge({"content" => self.output, "page" => layout.data})
begin
self.output = Liquid::Template.parse(layout.content).render!(payload, info)
rescue => e
puts "Liquid Exception: #{e.message} in #{self.data["layout"]}"
e.backtrace.each do |backtrace|
puts backtrace
end
abort("Build Failed")
end
self.output = self.render_liquid(layout.content,
payload.merge({:file => self.data["layout"]}),
info)
if layout = layouts[layout.data["layout"]]
if used.include?(layout)
@ -118,5 +111,42 @@ module Jekyll
end
end
end
# Add any necessary layouts to this convertible document.
#
# payload - The site payload Hash.
# layouts - A Hash of {"name" => "layout"}.
#
# Returns nothing.
def do_layout(payload, layouts)
info = { :filters => [Jekyll::Filters], :registers => { :site => self.site, :page => payload['page'] } }
# render and transform content (this becomes the final content of the object)
payload["pygments_prefix"] = converter.pygments_prefix
payload["pygments_suffix"] = converter.pygments_suffix
self.content = self.render_liquid(self.content,
payload.merge({:file => self.name}),
info)
self.transform
# output keeps track of what will finally be written
self.output = self.content
self.render_all_layouts(layouts, payload, info)
end
# Write the generated page file to the destination directory.
#
# dest - The String path to the destination dir.
#
# Returns nothing.
def write(dest)
path = destination(dest)
FileUtils.mkdir_p(File.dirname(path))
File.open(path, 'w') do |f|
f.write(self.output)
end
end
end
end

34
lib/jekyll/deprecator.rb Normal file
View File

@ -0,0 +1,34 @@
module Jekyll
class Deprecator
def self.process(args)
no_subcommand(args)
deprecation_message args, "--server", "The --server command has been replaced by the \
'serve' subcommand."
deprecation_message args, "--no-server", "To build Jekyll without launching a server, \
use the 'build' subcommand."
deprecation_message args, "--auto", "The switch '--auto' has been replaced with '--watch'."
deprecation_message args, "--no-auto", "To disable auto-replication, simply leave off \
the '--watch' switch."
deprecation_message args, "--pygments", "The 'pygments' setting can only be set in \
your config files."
deprecation_message args, "--paginate", "The 'paginate' setting can only be set in your \
config files."
deprecation_message args, "--url", "The 'url' setting can only be set in your config files."
end
def self.no_subcommand(args)
if args.size == 0 || args.first =~ /^--/
Jekyll::Logger.error "Deprecation:", "Jekyll now uses subcommands instead of just \
switches. Run `jekyll help' to find out more."
exit(1)
end
end
def self.deprecation_message(args, deprecated_argument, message)
if args.include?(deprecated_argument)
Jekyll::Logger.error "Deprecation:", message
exit(1)
end
end
end
end

14
lib/jekyll/filters.rb
View File

@ -56,6 +56,20 @@ module Jekyll
date.xmlschema
end
# Format a date according to RFC-822
#
# date - The Time to format.
#
# Examples
#
# date_to_rfc822(Time.now)
# # => "Sun, 24 Apr 2011 12:34:46 +0000"
#
# Returns the formatted String.
def date_to_rfc822(date)
date.rfc822
end
# XML escape a string for use. Replaces any special characters with
# appropriate HTML entity replacements.
#

28
lib/jekyll/generators/pagination.rb
View File

@ -37,7 +37,7 @@ module Jekyll
if num_page > 1
newpage = Page.new(site, site.source, page.dir, page.name)
newpage.pager = pager
newpage.dir = File.join(page.dir, paginate_path(site, num_page))
newpage.dir = File.join(page.dir, Pager.paginate_path(site.config, num_page))
site.pages << newpage
else
page.pager = pager
@ -45,16 +45,12 @@ module Jekyll
end
end
private
def paginate_path(site, num_page)
format = site.config['paginate_path']
format.sub(':num', num_page.to_s)
end
end
end
class Pager
attr_reader :page, :per_page, :posts, :total_posts, :total_pages, :previous_page, :next_page
attr_reader :page, :per_page, :posts, :total_posts, :total_pages,
:previous_page, :previous_page_path, :next_page, :next_page_path
# Calculate the number of pages.
#
@ -76,6 +72,18 @@ module Jekyll
file == 'index.html' && !config['paginate'].nil?
end
# Static: Return the pagination path of the page
#
# site_config - the site config
# num_page - the pagination page number
#
# Returns the pagination path as a string
def self.paginate_path(site_config, num_page)
return nil if num_page.nil? || num_page <= 1
format = site_config['paginate_path']
format.sub(':num', num_page.to_s)
end
# Initialize a new Pager.
#
# config - The Hash configuration of the site.
@ -98,7 +106,9 @@ module Jekyll
@total_posts = all_posts.size
@posts = all_posts[init..offset]
@previous_page = @page != 1 ? @page - 1 : nil
@previous_page_path = Pager.paginate_path(config, @previous_page)
@next_page = @page != @total_pages ? @page + 1 : nil
@next_page_path = Pager.paginate_path(config, @next_page)
end
# Convert this Pager's data to a Hash suitable for use by Liquid.
@ -112,7 +122,9 @@ module Jekyll
'total_posts' => total_posts,
'total_pages' => total_pages,
'previous_page' => previous_page,
'next_page' => next_page
'previous_page_path' => previous_page_path,
'next_page' => next_page,
'next_page_path' => next_page_path
}
end
end

52
lib/jekyll/logger.rb Normal file
View File

@ -0,0 +1,52 @@
module Jekyll
module Logger
# Public: Print a jekyll message to stdout
#
# topic - the topic of the message, e.g. "Configuration file", "Deprecation", etc.
# message - the message detail
#
# Returns nothing
def self.info(topic, message)
$stdout.puts message(topic, message)
end
# Public: Print a jekyll message to stderr
#
# topic - the topic of the message, e.g. "Configuration file", "Deprecation", etc.
# message - the message detail
#
# Returns nothing
def self.warn(topic, message)
$stderr.puts message(topic, message).yellow
end
# Public: Print a jekyll error message to stderr
#
# topic - the topic of the message, e.g. "Configuration file", "Deprecation", etc.
# message - the message detail
#
# Returns nothing
def self.error(topic, message)
$stderr.puts message(topic, message).red
end
# Public: Build a Jekyll topic method
#
# topic - the topic of the message, e.g. "Configuration file", "Deprecation", etc.
# message - the message detail
#
# Returns the formatted message
def self.message(topic, message)
formatted_topic(topic) + message.gsub(/\s+/, ' ')
end
# Public: Format the topic
#
# topic - the topic of the message, e.g. "Configuration file", "Deprecation", etc.
#
# Returns the formatted topic statement
def self.formatted_topic(topic)
"#{topic} ".rjust(20)
end
end
end

1
lib/jekyll/mime.types
View File

@ -35,6 +35,7 @@ application/postscript ps eps ai
application/rdf+xml rdf
application/rtf rtf
text/vcard vcf vcard
application/vnd.apple.pkpass pkpass
application/vnd.ms-excel xls
application/vnd.ms-powerpoint ppt
application/vnd.wap.wmlc wmlc

28
lib/jekyll/page.rb
View File

@ -23,18 +23,6 @@ module Jekyll
self.read_yaml(File.join(base, dir), name)
end
# Read the YAML frontmatter.
#
# base - The String path to the dir containing the file.
# name - The String filename of the file.
#
# Returns nothing.
def read_yaml(base, name)
super(base, name)
self.data['layout'] = 'page' unless self.data.has_key?('layout')
self.data
end
# The generated directory into which the page will be placed
# upon generation. This is derived from the permalink or, if
# permalink is absent, we be '/'
@ -124,7 +112,8 @@ module Jekyll
def to_liquid
self.data.deep_merge({
"url" => self.url,
"content" => self.content })
"content" => self.content,
"path" => self.data['path'] || File.join(@dir, @name).sub(/\A\//, '') })
end
# Obtain destination path.
@ -140,19 +129,6 @@ module Jekyll
path
end
# Write the generated page file to the destination directory.
#
# dest - The String path to the destination dir.
#
# Returns nothing.
def write(dest)
path = destination(dest)
FileUtils.mkdir_p(File.dirname(path))
File.open(path, 'w') do |f|
f.write(self.output)
end
end
# Returns the object as a debug String.
def inspect
"#<Jekyll:Page @name=#{self.name.inspect}>"

130
lib/jekyll/post.rb
View File

@ -10,6 +10,21 @@ module Jekyll
# Valid post name regex.
MATCHER = /^(.+\/)*(\d+-\d+-\d+)-(.*)(\.[^.]+)$/
# Attributes for Liquid templates
ATTRIBUTES_FOR_LIQUID = %w[
title
url
date
id
categories
next
previous
tags
content
excerpt
path
]
# Post name validator. Post filenames must be like:
# 2008-11-05-my-awesome-post.textile
#
@ -19,7 +34,7 @@ module Jekyll
end
attr_accessor :site
attr_accessor :data, :excerpt, :content, :output, :ext
attr_accessor :data, :extracted_excerpt, :content, :output, :ext
attr_accessor :date, :slug, :published, :tags, :categories
attr_reader :name
@ -33,40 +48,43 @@ module Jekyll
# Returns the new Post.
def initialize(site, source, dir, name)
@site = site
@dir = dir
@base = self.containing_dir(source, dir)
@name = name
self.categories = dir.downcase.split('/').reject { |x| x.empty? }
self.process(name)
begin
self.read_yaml(@base, name)
rescue Exception => msg
raise FatalException.new("#{msg} in #{@base}/#{name}")
end
# If we've added a date and time to the YAML, use that instead of the
# filename date. Means we'll sort correctly.
if self.data.has_key?('date')
# ensure Time via to_s and reparse
self.date = Time.parse(self.data["date"].to_s)
end
if self.data.has_key?('published') && self.data['published'] == false
self.published = false
else
self.published = true
self.published = self.published?
self.populate_categories
self.populate_tags
end
self.tags = self.data.pluralized_array("tag", "tags")
def published?
if self.data.has_key?('published') && self.data['published'] == false
false
else
true
end
end
def populate_categories
if self.categories.empty?
self.categories = self.data.pluralized_array('category', 'categories').map {|c| c.downcase}
end
self.tags.flatten!
self.categories.flatten!
end
def populate_tags
self.tags = self.data.pluralized_array("tag", "tags").flatten
end
# Get the full path to the directory containing the post files
def containing_dir(source, dir)
return File.join(source, dir, '_posts')
@ -80,8 +98,36 @@ module Jekyll
# Returns nothing.
def read_yaml(base, name)
super(base, name)
self.excerpt = self.extract_excerpt
self.data['layout'] = 'post' unless self.data.has_key?('layout')
self.extracted_excerpt = self.extract_excerpt
end
# The post excerpt. This is either a custom excerpt
# set in YAML front matter or the result of extract_excerpt.
#
# Returns excerpt string.
def excerpt
if self.data.has_key? 'excerpt'
self.data['excerpt']
else
self.extracted_excerpt
end
end
# Public: the Post title, from the YAML Front-Matter or from the slug
#
# Returns the post title
def title
self.data["title"] || self.slug.split('-').select {|w| w.capitalize! || w }.join(' ')
end
# Public: the path to the post relative to the site source,
# from the YAML Front-Matter or from a combination of
# the directory it's in, "_posts", and the name of the
# post file
#
# Returns the path to the file relative to the site source
def path
self.data['path'] || File.join(@dir, '_posts', @name).sub(/\A\//, '')
end
# Compares Post objects. First compares the Post date. If the dates are
@ -117,7 +163,7 @@ module Jekyll
# Returns nothing.
def transform
super
self.excerpt = converter.convert(self.excerpt)
self.extracted_excerpt = converter.convert(self.extracted_excerpt)
end
# The generated directory into which the post will be placed
@ -146,6 +192,8 @@ module Jekyll
"/:categories/:title.html"
when :date
"/:categories/:year/:month/:day/:title.html"
when :ordinal
"/:categories/:year/:y_day/:title.html"
else
self.site.permalink_style.to_s
end
@ -169,6 +217,8 @@ module Jekyll
"i_day" => date.strftime("%d").to_i.to_s,
"i_month" => date.strftime("%m").to_i.to_s,
"categories" => categories.map { |c| URI.escape(c.to_s) }.join('/'),
"short_month" => date.strftime("%b"),
"y_day" => date.strftime("%j"),
"output_ext" => self.output_ext
}.inject(template) { |result, token|
result.gsub(/:#{Regexp.escape token.first}/, token.last)
@ -196,6 +246,16 @@ module Jekyll
return [] unless posts.size > 1
if self.site.lsi
build_index
related = self.class.lsi.find_related(self.content, 11)
related - [self]
else
(posts - [self])[0..9]
end
end
def build_index
self.class.lsi ||= begin
puts "Starting the classifier..."
lsi = Classifier::LSI.new(:auto_rebuild => false)
@ -206,12 +266,6 @@ module Jekyll
puts ""
lsi
end
related = self.class.lsi.find_related(self.content, 11)
related - [self]
else
(posts - [self])[0..9]
end
end
# Add any necessary layouts to this post.
@ -242,34 +296,14 @@ module Jekyll
path
end
# Write the generated post file to the destination directory.
#
# dest - The String path to the destination dir.
#
# Returns nothing.
def write(dest)
path = destination(dest)
FileUtils.mkdir_p(File.dirname(path))
File.open(path, 'w') do |f|
f.write(self.output)
end
end
# Convert this post into a Hash for use in Liquid templates.
#
# Returns the representative Hash.
def to_liquid
self.data.deep_merge({
"title" => self.data["title"] || self.slug.split('-').select {|w| w.capitalize! || w }.join(' '),
"url" => self.url,
"date" => self.date,
"id" => self.id,
"categories" => self.categories,
"next" => self.next,
"previous" => self.previous,
"tags" => self.tags,
"content" => self.content,
"excerpt" => self.excerpt })
further_data = Hash[ATTRIBUTES_FOR_LIQUID.map { |attribute|
[attribute, send(attribute)]
}]
data.deep_merge(further_data)
end
# Returns the shorthand String identifier of this Post.

19
lib/jekyll/site.rb
View File

@ -23,12 +23,12 @@ module Jekyll
self.pygments = config['pygments']
self.baseurl = config['baseurl']
self.permalink_style = config['permalink'].to_sym
self.exclude = config['exclude'] || []
self.include = config['include'] || []
self.exclude = config['exclude']
self.include = config['include']
self.future = config['future']
self.show_drafts = config['show_drafts'] || nil
self.limit_posts = config['limit_posts'] || nil
self.keep_files = config['keep_files'] || []
self.show_drafts = config['show_drafts']
self.limit_posts = config['limit_posts']
self.keep_files = config['keep_files']
self.reset
self.setup
@ -62,8 +62,8 @@ module Jekyll
self.categories = Hash.new { |hash, key| hash[key] = [] }
self.tags = Hash.new { |hash, key| hash[key] = [] }
if !self.limit_posts.nil? && self.limit_posts < 1
raise ArgumentError, "Limit posts must be nil or >= 1"
if self.limit_posts < 0
raise ArgumentError, "limit_posts must not be a negative number"
end
end
@ -97,7 +97,7 @@ module Jekyll
#
# Returns an Array of plugin search paths
def plugins_path
if (config['plugins'] == Jekyll::DEFAULTS['plugins'])
if (config['plugins'] == Jekyll::Configuration::DEFAULTS['plugins'])
[File.join(self.source, config['plugins'])]
else
Array(config['plugins']).map { |d| File.expand_path(d) }
@ -148,7 +148,7 @@ module Jekyll
self.posts.sort!
# limit the posts if :limit_posts option is set
if limit_posts
if limit_posts > 0
limit = self.posts.length < limit_posts ? self.posts.length : limit_posts
self.posts = self.posts[-limit, limit]
end
@ -405,6 +405,7 @@ module Jekyll
base = File.join(self.source, dir, subfolder)
return [] unless File.exists?(base)
entries = Dir.chdir(base) { filter_entries(Dir['**/*']) }
entries.delete_if { |e| File.directory?(File.join(base, e)) }
end
# Aggregate post information

13
lib/jekyll/tags/post_url.rb
View File

@ -10,6 +10,13 @@ module Jekyll
@slug = slug
@date = Time.parse(date)
end
def ==(other)
slug == other.slug &&
date.year == other.date.year &&
date.month == other.date.month &&
date.day == other.date.day
end
end
class PostUrl < Liquid::Tag
@ -23,11 +30,7 @@ module Jekyll
site = context.registers[:site]
site.posts.each do |p|
if p.slug == @post.slug \
and p.date.year == @post.date.year \
and p.date.month == @post.date.month \
and p.date.day == @post.date.day
if @post == p
return p.url
end
end

1
lib/site_template/_config.yml
View File

@ -1,2 +1 @@
markdown: rdiscount
pygments: true

2
site/_config.yml
View File

@ -1,5 +1,3 @@
auto: false
server: true
permalink: /docs/:categories/:title
pygments: true
gauges_id: 503c5af6613f5d0f19000027

191
site/_posts/2012-07-01-configuration.md
View File

@ -5,69 +5,97 @@ prev_section: structure
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
### 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.
<div class="mobile-side-scroller">
<table>
<thead>
<tr>
<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>
</thead>
<tbody>
<tr class='setting'>
<td>
<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 class="align-center">
<p><code class="option">source: [string]</code></p>
<p><code class="flag">--source [source]</code></p>
<p><code class="option">source: DIR</code></p>
<p><code class="flag">-s, --source DIR</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Site Destination</strong></p>
<p class='description'>Changes the directory where Jekyll will write files to</p>
<p class='description'>Change the directory where Jekyll will write files</p>
</td>
<td class="align-center">
<p><code class="option">destination: [string]</code></p>
<p><code class="flag">--destination</code></p>
<p><code class="option">destination: DIR</code></p>
<p><code class="flag">-d, --destination DIR</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Safe</strong></p>
<p class='description'>Disables <a href="../plugins">custom plugins</a>.</p>
<p class='description'>Disable <a href="../plugins">custom plugins</a>.</p>
</td>
<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>
</td>
</tr>
<tr class='setting'>
<td>
<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 class='align-center'>
<p><code class="option">exclude: [dir1, file1, dir2]</code></p>
<p><code class="option">exclude: [DIR, FILE, ...]</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Include</strong></p>
<p class="description">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 class='align-center'>
<p><code class="option">include: [dir1, file1, dir2]</code></p>
<p><code class="option">include: [DIR, FILE, ...]</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Time Zone</strong></p>
<p class="description">
Set the time zone for site generation. This sets the <code>TZ</code>
environment variable, which Ruby uses to handle time and date
creation and manipulation. Any entry from the
<a href="http://en.wikipedia.org/wiki/Tz_database">IANA Time Zone
Database</a> is valid, e.g. <code>America/New_York</code>. The default
is the local time zone, as set by your operating system.
</p>
</td>
<td class='align-center'>
<p><code class="option">timezone: TIMEZONE</code></p>
</td>
</tr>
</tbody>
@ -88,90 +116,58 @@ The table below lists the available settings for Jekyll, and the various <code c
<tr class='setting'>
<td>
<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 class="align-center">
<p><code class="flag">--watch</code></p>
<p><code class="flag">-w, --watch</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>URL</strong></p>
<p class='description'>Sets <code>site.url</code>, useful for environment switching</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>
<p class='name'><strong>Configuration</strong></p>
<p class="description">Specify a config file. Overrides settings in <code>_config.yml</code></p>
</td>
<td class='align-center'>
<p><code class="option">markdown: [engine]</code></p>
<p><code class="flag">--markdown [rdiscount|kramdown|redcarpet]</code></p>
<p><code class="flag">--config FILE</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Pygments</strong></p>
<p class="description">Enables highlight tag with Pygments.</p>
<p class='name'><strong>Drafts</strong></p>
<p class="description">Process and render draft posts.</p>
</td>
<td class='align-center'>
<p><code class="option">pygments: [boolean]</code></p>
<p><code class="flag">--pygments</code></p>
<p><code class="flag">--drafts</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<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 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>
</td>
</tr>
<tr class='setting'>
<td>
<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 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>
</td>
</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'>
<td>
<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 class='align-center'>
<p><code class="option">limit_posts: [max_posts]</code></p>
<p><code class="flag">--limit_posts [max_posts]</code></p>
<p><code class="option">limit_posts: NUM</code></p>
<p><code class="flag">--limit_posts NUM</code></p>
</td>
</tr>
</tbody>
@ -196,31 +192,31 @@ before your site is served.
<tr class='setting'>
<td>
<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 class="align-center">
<p><code class="option">port: [integer]</code></p>
<p><code class="flag">--port [port]</code></p>
<p><code class="option">port: PORT</code></p>
<p><code class="flag">--port PORT</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Local Server Hostname</strong></p>
<p class='description'>Changes the hostname that the Jekyll server will run on</p>
<p class='description'>Listen at the given hostname.</p>
</td>
<td class="align-center">
<p><code class="option">host: [string]</code></p>
<p><code class="flag">--host [hostname]</code></p>
<p><code class="option">host: HOSTNAME</code></p>
<p><code class="flag">--host HOSTNAME</code></p>
</td>
</tr>
<tr class='setting'>
<td>
<p class='name'><strong>Base URL</strong></p>
<p class='description'>Serve website from a given base URL</p>
<p class='description'>Serve the website from the given base URL</p>
</td>
<td class="align-center">
<p><code class="option">baseurl: [BASE_URL]</code></p>
<p><code class="flag">--baseurl [url]</code></p>
<p><code class="option">baseurl: URL</code></p>
<p><code class="flag">--baseurl URL</code></p>
</td>
</tr>
</tbody>
@ -229,31 +225,50 @@ before your site is served.
<div class="note warning">
<h5>Do not use tabs in configuration files</h5>
<p>This will either lead to parsing errors, or Jekyll will revert to the default settings. Use spaces instead.</p>
<p>
This will either lead to parsing errors, or Jekyll will revert to the
default settings. Use spaces instead.
</p>
</div>
## Default Configuration
Jekyll runs with the following configuration options by default. Unless alternative settings for these options are explicitly specified in the configuration file or on the command-line, Jekyll will run using these options.
Jekyll runs with the following configuration options by default. Unless
alternative settings for these options are explicitly specified in the
configuration file or on the command-line, Jekyll will run using these options.
{% highlight yaml %}
source: .
destination: ./_site
plugins: ./_plugins
layouts: ./_layouts
include: ['.htaccess']
exclude: []
keep_files: ['.git','.svn']
timezone: nil
future: true
show_drafts: nil
limit_posts: 0
pygments: true
permalink: date
paginate_path: 'page:num'
markdown: maruku
markdown_ext: markdown,mkd,mkdn,md
textile_ext: textile
excerpt_separator: "\n\n"
safe: false
watch: false
server: false
watch: false # deprecated
server: false # deprecated
host: 0.0.0.0
port: 4000
baseurl: /
url: http://localhost:4000
source: .
destination: ./_site
plugins: ./_plugins
future: true
lsi: false
pygments: false
markdown: maruku
permalink: date
maruku:
use_tex: false
@ -265,11 +280,15 @@ maruku:
rdiscount:
extensions: []
redcarpet:
extensions: []
kramdown:
auto_ids: true,
auto_ids: true
footnote_nr: 1
entity_output: as_char
toc_levels: 1..6
smart_quotes: lsquo,rsquo,ldquo,rdquo
use_coderay: false
coderay:
@ -280,4 +299,6 @@ kramdown:
coderay_bold_every: 10
coderay_css: style
redcloth:
hard_breaks: true
{% endhighlight %}

93
site/_posts/2012-07-01-contributing.md
View File

@ -5,62 +5,83 @@ prev_section: deployment-methods
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
Here’s the most typical way to get your change merged into the project:
1. Fork the project [on GitHub](https://github.com/mojombo/jekyll) and clone it down to your local machine.
2. Create a topic branch to contain your change.
3. Hack away, add tests. Not necessarily in that order.
4. Make sure all the existing tests still pass.
5. If necessary, rebase your commits into logical chunks, without errors.
6. Push the branch up to your fork on GitHub.
7. Create an issue on GitHub with a link to your branch.
* If you're creating a small fix or patch to an existing feature, just a simple
test will do. Please stay in the confines of the current test suite and use
[Shoulda](http://github.com/thoughtbot/shoulda/tree/master) and
[RR](http://github.com/btakita/rr/tree/master).
* If it's a brand new feature, make sure to create a new
[Cucumber](https://github.com/cucumber/cucumber/) feature and reuse steps
where appropriate. Also, whipping up some documentation in your fork's `site`
directory would be appreciated, and once merged it will also appear in
the next update of the main site.
* If your contribution adds or changes any Jekyll behavior, make sure to update
the documentation. It lives in `site/_posts`. If the docs are missing
information, please feel free to add it in. Great docs make a great project!
* Please follow the [GitHub Ruby Styleguide](https://github.com/styleguide/ruby)
when modifying Ruby code.
<div class="note warning">
<h5>Contributions will not be accepted without tests</h5>
<p>If you’re creating a small fix or patch to an existing feature, just
a simple test will do.</p>
<p>
If you’re creating a small fix or patch to an existing feature, just
a simple test will do.
</p>
</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).
### Tests for brand-new features
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!
To run the test suite and build the gem you'll need to install Jekyll's
dependencies. Jekyll uses Bundler, so a quick run of the `bundle` command and
you're all set!
{% highlight bash %}
$ bundle
{% endhighlight %}
Before you start, run the tests and make sure that they pass (to confirm
your environment is configured properly):
Before you start, run the tests and make sure that they pass (to confirm your
environment is configured properly):
{% highlight bash %}
$ rake test
$ rake features
{% endhighlight %}
## Common Gotchas
Workflow
--------
- 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](https://github.com/mojombo/jekyll/commits/master). 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 labels like “fix” or “feature”.
The maintainers actively read the issues and will label it once they come
across it.
Here's the most direct way to get your work merged into the project:
* Fork the project.
* Clone down your fork: `git clone git://github.com/<username>/jekyll.git`
* Create a topic branch to contain your change: `git checkout -b my_awesome_feature`
* Hack away, add tests. Not necessarily in that order.
* Make sure everything still passes by running `rake`.
* If necessary, rebase your commits into logical chunks, without errors.
* Push the branch up: `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">
<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>

75
site/_posts/2012-07-01-extras.md
View File

@ -5,99 +5,112 @@ prev_section: plugins
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
If you want syntax highlighting via the `{{ "{% highlight " }}%}` tag in your
posts, you’ll need to install [Pygments](http://pygments.org/).
If you want syntax highlighting via the `{% raw %}{% highlight %}{% endraw %}`
tag in your posts, you’ll need to install [Pygments](http://pygments.org/).
### Installing Pygments on OSX
Mac OS X (Leopard onwards) 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 %}
sudo easy_install Pygments
$ sudo easy_install Pygments
{% endhighlight %}
#### Installing Pygments using Homebrew
Alternatively, you can install Pygments with [Homebrew](http://mxcl.github.com/homebrew/), an excellent package manager for OS X:
Alternatively, you can install Pygments with
[Homebrew](http://mxcl.github.com/homebrew/), an excellent package manager for
OS X:
{% highlight bash %}
brew install python
$ brew install python
# export PATH="/usr/local/share/python:${PATH}"
easy_install pip
pip install --upgrade distribute
pip install pygments
$ easy_install pip
$ pip install --upgrade distribute
$ pip install pygments
{% 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
<a href="https://github.com/mxcl/homebrew/wiki/Homebrew-and-Python">the
Homebrew wiki</a>.
</p>
</div>
#### Installing Pygments using MacPorts
If you use MacPorts, you can install Pygments by running:
{% highlight bash %}
sudo port install python25 py25-pygments
$ sudo port install python25 py25-pygments
{% 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
You can install Pygments using the pacman package manager as follows:
{% highlight bash %}
sudo pacman -S python-pygments
$ sudo pacman -S python-pygments
{% endhighlight %}
Or to use python2 for Pygments:
{% highlight bash %}
sudo pacman -S python2-pygments
$ sudo pacman -S python2-pygments
{% endhighlight %}
### Installing Pygments on Ubuntu and Debian
{% highlight bash %}
sudo apt-get install python-pygments
$ sudo apt-get install python-pygments
{% endhighlight %}
### Installing Pygments on RedHat, Fedora, and CentOS
{% highlight bash %}
sudo yum install python-pygments
$ sudo yum install python-pygments
{% endhighlight %}
### Installing Pygments on Gentoo
{% highlight bash %}
sudo emerge -av dev-python/pygments
$ sudo emerge -av dev-python/pygments
{% endhighlight %}
## LaTeX Support
Maruku comes with optional support for LaTeX to PNG rendering via
blahtex (Version 0.6) which must be in your `$PATH` along with `dvips`. If you need Maruku to not assume a fixed location for `dvips`, check out [Remi’s Maruku fork](http://github.com/remi/maruku).
Maruku comes with optional support for LaTeX to PNG rendering via blahtex
(Version 0.6) which must be in your `$PATH` along with `dvips`. If you need
Maruku to not assume a fixed location for `dvips`, check out [Remi’s Maruku
fork](http://github.com/remi/maruku).
## RDiscount
If you prefer to use [RDiscount](http://github.com/rtomayko/rdiscount) instead of [Maruku](http://maruku.rubyforge.org/) for markdown, just make sure you have it installed:
If you prefer to use [RDiscount](http://github.com/rtomayko/rdiscount) instead
of [Maruku](http://maruku.rubyforge.org/) for markdown, just make sure you have
it installed:
{% highlight bash %}
sudo gem install rdiscount
$ sudo gem install rdiscount
{% endhighlight %}
And then run Jekyll with the following 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).
And then specify RDiscount as the Markdown engine in your `_config.yml` file to
have Jekyll run with that option.
{% highlight bash %}
# In _config.yml
markdown: rdiscount
{% endhighlight %}

79
site/_posts/2012-07-01-frontmatter.md
View File

@ -5,7 +5,11 @@ prev_section: configuration
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 %}
---
@ -14,16 +18,25 @@ title: Blogging Like a Hacker
---
{% endhighlight %}
Between these triple-dashed lines, you can set predefined variables (see below for a reference) or even create custom ones of your own. These variables will then be available to you to access using Liquid tags both further down in the file and also in any layouts or includes that the page or post in question relies on.
Between these triple-dashed lines, you can set predefined variables (see below
for a reference) or even create custom ones of your own. These variables will
then be available to you to access using Liquid tags both further down in the
file and also in any layouts or includes that the page or post in question
relies on.
<div class="note warning">
<h5>UTF-8 Character Encoding Warning</h5>
<p>If you use UTF-8 encoding, make sure that no <code>BOM</code> header characters exist in your files or very, very bad things will happen to Jekyll. This is especially relevant if you’re running Jekyll on Windows.</p>
<p>
If you use UTF-8 encoding, make sure that no <code>BOM</code> header
characters exist in your files or very, very bad things will happen to
Jekyll. This is especially relevant if you’re running Jekyll on Windows.
</p>
</div>
## Predefined Global Variables
There are a number of predefined global variables that you can set in the front-matter of a page or post.
There are a number of predefined global variables that you can set in the
front-matter of a page or post.
<div class="mobile-side-scroller">
<table>
@ -39,7 +52,13 @@ There are a number of predefined global variables that you can set in the front-
<p><code>layout</code></p>
</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 the file extension. Layout files must be placed in the
<code>_layouts</code> directory.
</p>
</td>
</tr>
<tr>
@ -47,7 +66,13 @@ There are a number of predefined global variables that you can set in the front-
<p><code>permalink</code></p>
</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>
</tr>
<tr>
@ -55,7 +80,10 @@ There are a number of predefined global variables that you can set in the front-
<p><code>published</code></p>
</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>
</tr>
<tr>
@ -64,7 +92,16 @@ There are a number of predefined global variables that you can set in the front-
<p><code>categories</code></p>
</td>
<td>
<p>Instead of placing posts inside of folders, you can specify one or more categories that the post belongs to. When the site is generated the post will act as though it had been set with these categories normally. Categories (plural key) can be specified as a <a href="http://en.wikipedia.org/wiki/YAML#Lists">YAML list</a> or a space-separated string.</p>
<p>
Instead of placing posts inside of folders, you can specify one or
more categories that the post belongs to. When the site is generated
the post will act as though it had been set with these categories
normally. Categories (plural key) can be specified as a <a
href="http://en.wikipedia.org/wiki/YAML#Lists">YAML list</a> or a
space-separated string.
</p>
</td>
</tr>
<tr>
@ -72,7 +109,13 @@ There are a number of predefined global variables that you can set in the front-
<p><code>tags</code></p>
</td>
<td>
<p>Similar to categories, one or multiple tags can be added to a post. Also like categories, tags can be specified as a YAML list or a space-separated string.</p>
<p>
Similar to categories, one or multiple tags can be added to a post.
Also like categories, tags can be specified as a YAML list or a space-
separated string.
</p>
</td>
</tr>
</tbody>
@ -82,16 +125,16 @@ There are a number of predefined global variables that you can set in the front-
## Custom Variables
Any variables in the front matter that are not predefined are mixed into
the data that is sent to the Liquid templating engine during the
conversion. For instance, if you set a title, you can use that in your
layout to set the page title:
Any variables in the front matter that are not predefined are mixed into the
data that is sent to the Liquid templating engine during the conversion. For
instance, if you set a title, you can use that in your layout to set the page
title:
{% highlight html %}
<!DOCTYPE HTML>
<html>
<head>
<title>{{ "{{ page.title " }}}}</title>
<title>{% raw %}{{ page.title }}{% endraw %}</title>
</head>
<body>
...
@ -99,8 +142,7 @@ layout to set the page title:
## Predefined Variables for Posts
These are available out-of-the-box to be used in the front-matter for a
post.
These are available out-of-the-box to be used in the front-matter for a post.
<div class="mobile-side-scroller">
<table>
@ -116,7 +158,10 @@ post.
<p><code>date</code></p>
</td>
<td>
<p>A date here overrides the date from the name of the post. This can be used to ensure correct sorting of posts.</p>
<p>
A date here overrides the date from the name of the post. This can be
used to ensure correct sorting of posts.
</p>
</td>
</tr>
</tbody>

47
site/_posts/2012-07-01-github-pages.md
View File

@ -5,30 +5,61 @@ prev_section: extras
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's
[github.io]() domain or on a custom domain name of your choice. GitHub Pages are
powered by Jekyll behind the scenes, so in addition to supporting regular HTML
content, they’re also a great way to host your Jekyll-powered website for free.
## Deploying Jekyll to GitHub Pages
GitHub Pages work by looking at certain branches of repositories on GitHub. There are two basic types 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 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.io) has the name
`mojombo.github.io`.
Content from the `master` branch of your repository will be used to build and publish the GitHub Pages site, so make sure your Jekyll site is stored there.
Content from the `master` branch of your repository will be used to build and
publish the GitHub Pages site, so make sure your Jekyll site is stored there.
<div class="note info">
<h5>Custom domains do not affect repository names</h5>
<p>GitHub Pages are initially configured to live under the `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.io</code> subdomain, which is why repositories must
be named this way <strong>even if a custom domain is being used</strong>.
</p>
</div>
### Project Pages
Unlike user and organization Pages, Project Pages are kept in the same repository as the project they are for, except that the website content is stored in a specially named `gh-pages` branch. The content of this branch will be 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.io/project` (unless a
custom domain is specified—see below).
The Jekyll project repository itself is a perfect example of this branch structure—the [master branch](https://github.com/mojombo/jekyll) contains the actual software project for Jekyll, however the Jekyll website (that you’re looking at right now) is contained in the [gh-pages branch](https://github.com/mojombo/jekyll/tree/gh-pages) of the same repository.
The Jekyll project repository itself is a perfect example of this branch
structure—the [master branch](https://github.com/mojombo/jekyll) contains the
actual software project for Jekyll, however the Jekyll website (that you’re
looking at right now) is contained in the [gh-pages
branch](https://github.com/mojombo/jekyll/tree/gh-pages) of the same repository.
<div class="note">
<h5>GitHub Pages Documentation, Help, and Support</h5>
<p>For more information about what you can do with GitHub Pages, as well as for troubleshooting guides, you should check out <a href="https://help.github.com/categories/20/articles">GitHub’s Pages Help section</a>. If all else fails, you should contact <a href="https://github.com/contact">GitHub Support</a>.</p>
<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>

41
site/_posts/2012-07-01-home.md
View File

@ -4,30 +4,45 @@ title: Welcome
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 topics such
as getting your site up and running, creating and managing your content,
customizing the way your site works and looks, deploying to various
environments, and give you some advice on participating in the future
development of Jekyll itself.
## So what is Jekyll, exactly?
Jekyll is a simple, blog-aware, static site generator. It takes a template directory containing raw text files in various formats, runs it through [Markdown](http://daringfireball.net/projects/markdown/) (or [Textile](http://textile.sitemonks.com/)) and [Liquid](http://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
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 %}
~ $ gem install jekyll
~ $ mkdir -p my/new/site
~ $ cd my/new/site
~ $ vim index.html
~/my/new/site $ jekyll serve
~ $ jekyll new myblog
~ $ cd myblog
~/myblog $ jekyll serve
# => Now browse to http://localhost:4000
{% endhighlight %}
That's nothing though. The real magic happens when you start creating 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
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">
<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">
<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 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>
</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.

39
site/_posts/2012-07-01-installation.md
View File

@ -5,11 +5,15 @@ prev_section: home
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
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/)
- [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">
<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>
## Install with RubyGems
The best way to install Jekyll is via
[RubyGems](http://docs.rubygems.org/read/chapter/3). At the terminal prompt, simply run the following command to install Jekyll:
[RubyGems](http://docs.rubygems.org/read/chapter/3). At the terminal prompt,
simply run the following command to install Jekyll:
{% highlight bash %}
gem install jekyll
$ gem install jekyll
{% 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 of Jekyll’s gem dependencies are automatically installed by the above
command, so you won’t have to worry about them at all. If you have problems
installing Jekyll, check out the [troubleshooting](../troubleshooting) page or
[report an issue](https://github.com/mojombo/jekyll/issues/new) so the Jekyll
community can improve the experience for everyone.
## Optional Extras
There are a number of (optional) extra features that Jekyll supports that you may want to install, depending on how you plan to use Jekyll. These extras include syntax highlighting of code snippets using [Pygments](http://pygments.org/), LaTeX support, and the use of alternative content rendering engines. Check out [the extras page](../extras) for more information.
There are a number of (optional) extra features that Jekyll supports that you
may want to install, depending on how you plan to use Jekyll. These extras
include syntax highlighting of code snippets using
[Pygments](http://pygments.org/), LaTeX support, and the use of alternative
content rendering engines. Check out [the extras page](../extras) for more
information.
<div class="note">
<h5>ProTip™: Enable Syntax Highlighting</h5>
<p>If you’re the kind of person who is using Jekyll, then chances are you’ll 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>
Now that you’ve got everything installed, let’s get to work!

115
site/_posts/2012-07-01-migrations.md
View File

@ -5,29 +5,53 @@ prev_section: variables
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 from your old system to generate posts for Jekyll. Each method
generates `.markdown` posts in the `_posts` directory based on the entries in
the foreign system.
## Preparing for migrations
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 %}
$ mkdir _import
$ gem install sequel mysqlplus
$ gem install jekyll-import
{% 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">
<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>
<!-- TODO all these need to be fixed -->
## WordPress
### Wordpress export files
If hpricot is not already installed, you will need to run `gem install hpricot`. Next, export your blog using the Wordpress export utility. Assuming that 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 %}
$ ruby -rubygems -e 'require "jekyll/migrators/wordpressdotcom";
@ -48,7 +72,11 @@ $ ruby -rubygems -e 'require "jekyll/migrators/wordpress";
Jekyll::WordPress.process("database", "user", "pass")'
{% 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 %}
$ ruby -rubygems -e 'require "jekyll/migrators/wordpress";
@ -57,15 +85,27 @@ $ ruby -rubygems -e 'require "jekyll/migrators/wordpress";
### Further Wordpress migration alternatives
While the above methods work, they do not import much of the metadata that is usually stored in Wordpress posts and pages. If you need to export things like pages, tags, custom fields, image attachments and so on, the following resources might be useful to you:
While the above methods work, they do not import much of the metadata that is
usually stored in Wordpress posts and pages. If you need to export things like
pages, tags, custom fields, image attachments and so on, the following resources
might be useful to you:
- [Exitwp](https://github.com/thomasf/exitwp) is a configurable tool written in Python for migrating one or more Wordpress blogs into Jekyll (Markdown) format while keeping as much metadata as possible. Exitwp also downloads attachments and pages.
- [A great article](http://vitobotta.com/how-to-migrate-from-wordpress-to-jekyll/) with a step-by-step guide for migrating a Wordpress blog to Jekyll while keeping most of the structure and metadata.
- [wpXml2Jekyll](https://github.com/theaob/wpXml2Jekyll) is an executable windows application for creating Markdown posts from your Wordpress XML file.
- [Exitwp](https://github.com/thomasf/exitwp) is a configurable tool written in
Python for migrating one or more Wordpress blogs into Jekyll (Markdown) format
while keeping as much metadata as possible. Exitwp also downloads attachments
and pages.
- [A great
article](http://vitobotta.com/how-to-migrate-from-wordpress-to-jekyll/) with a
step-by-step guide for migrating a Wordpress blog to Jekyll while keeping most
of the structure and metadata.
- [wpXml2Jekyll](https://github.com/theaob/wpXml2Jekyll) is an executable
windows application for creating Markdown posts from your Wordpress XML file.
## Drupal
If you’re migrating from [Drupal](), 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 %}
$ ruby -rubygems -e 'require "jekyll/migrators/drupal";
@ -74,7 +114,9 @@ $ ruby -rubygems -e 'require "jekyll/migrators/drupal";
<div class="note warning">
<h5>Warning: Drupal Version Compatibility</h5>
<p>This migrator was written for Drupal 6.1 and may not work as expected on future versions of Drupal. Please update it and send us a pull request if necessary.</p>
<p>This migrator was written for Drupal 6.1 and may not work as expected with
newer versions of Drupal. Please update it and send us a pull request if
necessary.</p>
</div>
## Movable Type
@ -95,7 +137,7 @@ $ ruby -rubygems -e 'require "jekyll/migrators/typo";
Jekyll::Typo.process("database", "user", "pass")'
{% endhighlight %}
This code also has only been tested with Typo version 4+.
This code has only been tested with Typo version 4+.
## TextPattern
@ -106,7 +148,12 @@ $ ruby -rubygems -e 'require "jekyll/migrators/textpattern";
Jekyll::TextPattern.process("database_name", "username", "password", "hostname")'
{% endhighlight %}
You will need to run the above from the parent directory of your `_import` folder. For example, if `_import` is located in `/path/source/_import`, you will need to run this code from `/path/source`. The hostname defaults to `localhost`, all other variables are required. You may need to adjust the code used to filter entries. Left alone, it will attempt to pull all entries that are live or sticky.
You will need to run the above from the parent directory of your `_import`
folder. For example, if `_import` is located in `/path/source/_import`, you will
need to run this code from `/path/source`. The hostname defaults to `localhost`,
all other variables are required. You may need to adjust the code used to filter
entries. Left alone, it will attempt to pull all entries that are live or
sticky.
## Mephisto
@ -126,11 +173,22 @@ $ ruby -rubygems -e 'require "jekyll/migrators/mephisto";
## Blogger (Blogspot)
To import posts from Blogger, see [this post about migrating from Blogger to Jekyll](http://coolaj86.info/articles/migrate-from-blogger-to-jekyll.html). If that doesn’t work for you, you might want to try some of the following alternatives:
To import posts from Blogger, see [this post about migrating from Blogger to
Jekyll](http://coolaj86.info/articles/migrate-from-blogger-to-jekyll.html). If
that doesn’t work for you, you might want to try some of the following
alternatives:
- [@kennym](https://github.com/kennym) created a [little migration script](https://gist.github.com/1115810), because the solutions in the previous article didn't work out for him.
- [@ngauthier](https://github.com/ngauthier) created [another importer](https://gist.github.com/1506614) that imports comments, and does so via blogger’s archive instead of the RSS feed.
- [@juniorz](https://github.com/juniorz) created [yet another importer](https://gist.github.com/1564581) that works for [Octopress](http://octopress.org). It is like [@ngauthier’s version](https://gist.github.com/1506614) but separates drafts from posts, as well as importing tags and permalinks.
- [@kennym](https://github.com/kennym) created a [little migration
script](https://gist.github.com/1115810), because the solutions in the
previous article didn't work out for him.
- [@ngauthier](https://github.com/ngauthier) created [another
importer](https://gist.github.com/1506614) that imports comments, and does so
via blogger’s archive instead of the RSS feed.
- [@juniorz](https://github.com/juniorz) created [yet another
importer](https://gist.github.com/1564581) that works for
[Octopress](http://octopress.org). It is like [@ngauthier’s
version](https://gist.github.com/1506614) but separates drafts from posts, as
well as importing tags and permalinks.
## Posterous
@ -141,14 +199,17 @@ $ ruby -rubygems -e 'require "jekyll/migrators/posterous";
Jekyll::Posterous.process("my_email", "my_pass")'
{% endhighlight %}
For any other Posterous blog on your account, you will need to specify the `blog_id` for the blog:
For any other Posterous blog on your account, you will need to specify the
`blog_id` for the blog:
{% highlight bash %}
$ ruby -rubygems -e 'require "jekyll/migrators/posterous";
Jekyll::Posterous.process("my_email", "my_pass", "blog_id")'
{% endhighlight %}
There is also an [alternative Posterous migrator](https://github.com/pepijndevos/jekyll/blob/patch-1/lib/jekyll/migrators/posterous.rb) that maintains permalinks and attempts to import images too.
There is also an [alternative Posterous
migrator](https://github.com/pepijndevos/jekyll/blob/patch-1/lib/jekyll/migrators/posterous.rb)
that maintains permalinks and attempts to import images too.
## Tumblr
@ -159,9 +220,12 @@ $ ruby -rubygems -e 'require "jekyll/migrators/tumblr";
Jekyll::Tumblr.process("http://www.your_blog_url.com", true)'
{% endhighlight %}
There is also [a modified Tumblr migrator](https://github.com/stephenmcd/jekyll/blob/master/lib/jekyll/migrators/tumblr.rb) that exports posts as Markdown and preserves post tags.
There is also [a modified Tumblr
migrator](https://github.com/stephenmcd/jekyll/blob/master/lib/jekyll/migrators/tumblr.rb)
that exports posts as Markdown and preserves post tags.
The migrator above requires the `json` gem and Python's `html2text` to be installed as follows:
The migrator above requires the `json` gem and Python's `html2text` to be
installed as follows:
{% highlight bash %}
$ gem install json
@ -177,4 +241,5 @@ $ ruby -rubygems -e 'require "jekyll/migrators/tumblr";
## 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 for which there is currently no migrator, consider writing
one and sending us a pull request.

63
site/_posts/2012-07-01-pages.md
View File

@ -5,37 +5,53 @@ prev_section: posts
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
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">
<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>
## 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.
- Create a folder in the site root for each page, and placing an index.html file in each page folder.
- Place named HTML files for each page in your site's root folder.
- Create a folder in the site's root for each page, and place an index.html file
in each page folder.
Both methods work fine (and can be used in 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
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 %}
.
|-- _config.yml
|-- _includes
|-- _layouts
|-- _posts
|-- _site
|-- _includes/
|-- _layouts/
|-- _posts/
|-- _site/
|-- about.html # => http://yoursite.com/about.html
|-- index.html # => http://yoursite.com/
└── contact.html # => http://yoursite.com/contact.html
@ -43,20 +59,27 @@ The simplest way of adding a page is just to add a HTML file in the root directo
### 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 %}
.
├── _config.yml
├── _includes
├── _layouts
├── _posts
├── _site
├── about
├── _includes/
├── _layouts/
├── _posts/
├── _site/
├── about/
| └── index.html # => http://yoursite.com/about/
├── contact
├── contact/
| └── index.html # => http://yoursite.com/contact/
└── index.html # => http://yoursite.com/
{% 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!

184
site/_posts/2012-07-01-pagination.md
View File

@ -5,117 +5,213 @@ prev_section: permalinks
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">
<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>
## 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 %}
paginate: 5
{% 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.
## Liquid Attributes Available
The pagination plugin exposes the `paginator` liquid object with the following
attributes:
<table>
<thead>
<tr>
<th>Attribute</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><p><code>page</code></p></td>
<td><p>current page number</p></td>
</tr>
<tr>
<td><p><code>per_page</code></p></td>
<td><p>number of posts per page</p></td>
</tr>
<tr>
<td><p><code>posts</code></p></td>
<td><p>a list of posts for the current page</p></td>
</tr>
<tr>
<td><p><code>total_posts</code></p></td>
<td><p>total number of posts in the site</p></td>
</tr>
<tr>
<td><p><code>total_pages</code></p></td>
<td><p>number of pagination pages</p></td>
</tr>
<tr>
<td><p><code>previous_page</code></p></td>
<td>
<p>
page number of the previous pagination page,
or <code>nil</code> if no previous page exists
</p>
</td>
</tr>
<tr>
<td><p><code>previous_page_path</code></p></td>
<td>
<p>
path of previous pagination page,
or <code>nil</code> if no previous page exists
</p>
</td>
</tr>
<tr>
<td><p><code>next_page</code></p></td>
<td>
<p>
page number of the next pagination page,
or <code>nil</code> if no subsequent page exists
</p>
</td>
</tr>
<tr>
<td><p><code>next_page_path</code></p></td>
<td>
<p>
path of next pagination page,
or <code>nil</code> if no subsequent page exists
</p>
</td>
</tr>
</tbody>
</table>
<div class="note info">
<h5>Pagination does not support tags or categories</h5>
<p>Pagination pages through every post in the <code>posts</code> variable regardless of variables defined in the YAML Front Matter of each. It does not currently allow paging over groups of posts linked by a common tag or category.</p>
<p>Pagination pages through every post in the <code>posts</code>
variable regardless of variables defined in the YAML Front Matter of
each. It does not currently allow paging over groups of posts linked
by a common tag or category.</p>
</div>
## Render the paginated posts
## 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 %}
{% raw %}
---
layout: default
title: My Blog
---
<!-- This loops through the paginated posts -->
{{ "{% for post in paginator.posts " }}%}
<h1><a href="{{ "{{ post.url " }}}}">{{ "{{ post.title " }}}}</a></h1>
{% for post in paginator.posts %}
<h1><a href="{{ post.url }}">{{ post.title }}</a></h1>
<p class="author">
<span class="date">{{ "{{post.date" }}}}</span>
<span class="date">{{ post.date }}</span>
</p>
<div class="content">
{{ "{{ post.content " }}}}
{{ post.content }}
</div>
{{ "{% endfor " }}%}
{% endfor %}
<!-- Pagination links -->
<div class="pagination">
{{ "{% if paginator.previous_page " }}%}
<a href="/page{{ "{{paginator.previous_page" }}}}" class="previous">Previous</a>
{{ "{% else " }}%}
{% if paginator.previous_page %}
<a href="/page{{ paginator.previous_page }}" class="previous">Previous</a>
{% else %}
<span class="previous">Previous</span>
{{ "{% endif " }}%}
<span class="page_number ">Page: {{ "{{paginator.page" }}}} of {{ "{{paginator.total_pages" }}}}</span>
{{ "{% if paginator.next_page " }}%}
<a href="/page{{ "{{paginator.next_page" }}}}" class="next ">Next</a>
{{ "{% else " }}%}
{% endif %}
<span class="page_number ">Page: {{ paginator.page }} of {{ paginator.total_pages }}</span>
{% if paginator.next_page %}
<a href="/page{{ paginator.next_page }}" class="next">Next</a>
{% else %}
<span class="next ">Next</span>
{{ "{% endif " }}%}
{% endif %}
</div>
{% endraw %}
{% endhighlight %}
<div class="note warning">
<h5>Beware the page one edge-case</h5>
<p>Jekyll does not generate a ‘page1’ folder, so the above code will not work when a <code>/page1</code> link is produced. See below for a way to handle this if it’s a problem for you.</p>
<p>
Jekyll does not generate a ‘page1’ folder, so the above code will not work
when a <code>/page1</code> link is produced. See below for a way to handle
this if it’s a problem for you.
</p>
</div>
The following HTML snippet should handle page one, and render a list of each page with links to all but the current page.
The following HTML snippet should handle page one, and render a list of each
page with links to all but the current page.
{% highlight html %}
{% raw %}
<div id="post-pagination" class="pagination">
{{ "{% if paginator.previous_page " }}%}
{% if paginator.previous_page %}
<p class="previous">
{{ "{% if paginator.previous_page == 1 " }}%}
{% if paginator.previous_page == 1 %}
<a href="/">Previous</a>
{{ "{% else " }}%}
<a href="/page{{ "{{paginator.previous_page" }}}}">Previous</a>
{{ "{% endif " }}%}
{% else %}
<a href="{{ paginator.previous_page_path }}">Previous</a>
{% endif %}
</p>
{{ "{% else " }}%}
{% else %}
<p class="previous disabled">
<span>Previous</span>
</p>
{{ "{% endif " }}%}
{% endif %}
<ul class="pages">
<li class="page">
{{ "{% if paginator.page == 1 " }}%}
{% if paginator.page == 1 %}
<span class="current-page">1</span>
{{ "{% else " }}%}
{% else %}
<a href="/">1</a>
{{ "{% endif " }}%}
{% endif %}
</li>
{{ "{% for count in (2..paginator.total_pages) " }}%}
{% for count in (2..paginator.total_pages) %}
<li class="page">
{{ "{% if count == paginator.page " }}%}
<span class="current-page">{{ "{{count" }}}}</span>
{{ "{% else " }}%}
<a href="/page{{ "{{count" }}}}">{{ "{{count" }}}}</a>
{{ "{% endif " }}%}
{% if count == paginator.page %}
<span class="current-page">{{ count }}</span>
{% else %}
<a href="/page{{ count }}">{{ count }}</a>
{% endif %}
</li>
{{ "{% endfor " }}%}
{% endfor %}
</ul>
{{ "{% if paginator.next_page " }}%}
{% if paginator.next_page %}
<p class="next">
<a href="/page{{ "{{paginator.next_page" }}}}">Next</a>
<a href="{{ paginator.next_page_path }}">Next</a>
</p>
{{ "{% else " }}%}
{% else %}
<p class="next disabled">
<span>Next</span>
</p>
{{ "{% endif " }}%}
{% endif %}
</div>
{% endraw %}
{% endhighlight %}

71
site/_posts/2012-07-01-permalinks.md
View File

@ -5,8 +5,15 @@ prev_section: templates
next_section: pagination
---
Jekyll supports a flexible way to build your site’s URLs. You can
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`.
Jekyll supports a flexible way to build your site’s URLs. You can specify the
permalinks for your site through the [Configuration](../configuration) or in the
[YAML Front Matter](../frontmatter) for each post. You’re free to choose one of
the built-in styles to create your links or craft your own. The default style is
`date`.
Permalinks are constructed by creating a template URL where dynamic elements are
represented by colon-prefixed keywords. For example, the default `date`
permalink is defined as `/:categories/:year/:month/:day/:title.html`.
## Template variables
@ -24,7 +31,7 @@ specify the permalinks for your site through the [Configuration](../configuratio
<p><code>year</code></p>
</td>
<td>
<p>Year from the post’s filename</p>
<p>Year from the Post’s filename</p>
</td>
</tr>
<tr>
@ -32,31 +39,7 @@ specify the permalinks for your site through the [Configuration](../configuratio
<p><code>month</code></p>
</td>
<td>
<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>
<p>Month from the Post’s filename</p>
</td>
</tr>
<tr>
@ -64,7 +47,15 @@ specify the permalinks for your site through the [Configuration](../configuratio
<p><code>i_month</code></p>
</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>
</tr>
<tr>
@ -72,7 +63,27 @@ specify the permalinks for your site through the [Configuration](../configuratio
<p><code>i_day</code></p>
</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>
</tr>
</tbody>

144
site/_posts/2012-07-01-plugins.md
View File

@ -6,19 +6,27 @@ next_section: extras
---
Jekyll has a plugin system with hooks that allow you to create custom generated
content specific to your site. You can run custom code for your site
without having to modify the Jekyll source itself.
content specific to your site. You can run custom code for your site without
having to modify the Jekyll source itself.
<div class="note info">
<h5>Plugins on GitHub Pages</h5>
<p>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>
## Installing a plugin
In your site source root, make a `_plugins` directory. Place your plugins
here. Any file ending in `*.rb` inside this directory will be required
when Jekyll generates your site.
In your site source root, make a `_plugins` directory. Place your plugins here.
Any file ending in `*.rb` inside this directory will be loaded before Jekyll
generates your site.
In general, plugins you make will fall into one of three categories:
@ -28,9 +36,8 @@ In general, plugins you make will fall into one of three categories:
## Generators
You can create a generator when you need Jekyll to create additional
content based on your own rules. For example, a generator might look
like this:
You can create a generator when you need Jekyll to create additional content
based on your own rules. For example, a generator might look like this:
{% highlight ruby %}
module Jekyll
@ -68,8 +75,8 @@ end
{% endhighlight %}
In this example, our generator will create a series of files under the
`categories` directory for each category, listing the posts in each
category using the `category_index.html` layout.
`categories` directory for each category, listing the posts in each category
using the `category_index.html` layout.
Generators are only required to implement one method:
@ -96,18 +103,20 @@ Generators are only required to implement one method:
## Converters
If you have a new markup language you’d like to include in your site,
you can include it by implementing your own converter. Both the markdown
and textile markup languages are implemented using this method.
If you have a new markup language you’d like to use with your site, you can
include it by implementing your own converter. Both the Markdown and Textile
markup languages are implemented using this method.
<div class="note info">
<h5>Remember your YAML front-matter</h5>
<p>Jekyll will only convert files that have a YAML header at
the top, even for converters you add using a plugin. If there is no YAML header, Jekyll will ignore the file and not send it through the converter.</p>
<p>
Jekyll will only convert files that have a YAML header at the top, even for
converters you add using a plugin.
</p>
</div>
Below is a converter that will take all posts ending in .upcase and
process them using the UpcaseConverter:
Below is a converter that will take all posts ending in `.upcase` and process
them using the `UpcaseConverter`:
{% highlight ruby %}
module Jekyll
@ -116,7 +125,7 @@ module Jekyll
priority :low
def matches(ext)
ext =~ /upcase/i
ext =~ /^\.upcase$/i
end
def output_ext(ext)
@ -145,38 +154,47 @@ Converters should implement at a minimum 3 methods:
<td>
<p><code>matches</code></p>
</td>
<td>
<p>Called to determine whether the specific converter will
run on the page.</p>
</td>
<td><p>
Does the given extension match this converter's list of acceptable
extensions? Takes one argument: the file's extension (including the
dot). Must return <code>true</code> if it matches, <code>false</code>
otherwise.
</p></td>
</tr>
<tr>
<td>
<p><code>output_ext</code></p>
</td>
<td>
<p>The extension of the outputted file, usually this will be <code>.html</code></p>
</td>
<td><p>
The extension to be given to the output file (including the dot).
Usually this will be <code>".html"</code>.
</p></td>
</tr>
<tr>
<td>
<p><code>convert</code></p>
</td>
<td>
<p>Logic to do the content conversion</p>
</td>
<td><p>
Logic to do the content conversion. Takes one argument: the raw content
of the file (without YAML front matter). Must return a String.
</p></td>
</tr>
</tbody>
</table>
</div>
In our example, UpcaseConverter-matches checks if our filename extension is `.upcase`, and will render using the converter if it is. It will call UpcaseConverter-convert to process the content - in our simple converter we’re simply 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
If you’d like to include custom liquid tags in your site, you can do so
by hooking into the tagging system. Built-in examples added by Jekyll
include the `{{"{% highlight "}}%}` and `{{"{% include "}}%}` tags. Below is an example custom liquid tag that will output the time the page was rendered:
If you’d like to include custom liquid tags in your site, you can do so by
hooking into the tagging system. Built-in examples added by Jekyll include the
`highlight` and `include` tags. Below is an example of a custom liquid tag that
will output the time the page was rendered:
{% highlight ruby %}
module Jekyll
@ -219,16 +237,20 @@ At a minimum, liquid tags must implement:
</table>
</div>
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 %}
Liquid::Template.register_tag('render_time', Jekyll::RenderTimeTag)
{% endhighlight %}
In the example above, we can place the following tag anywhere in one of our pages:
In the example above, we can place the following tag anywhere in one of our
pages:
{% highlight ruby %}
<p>{{"{% render_time page rendered at: "}}%}</p>
{% raw %}
<p>{% render_time page rendered at: %}</p>
{% endraw %}
{% endhighlight %}
And we would get something like this on the page:
@ -239,7 +261,10 @@ And we would get something like this on the page:
### 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 %}
module Jekyll
@ -255,7 +280,12 @@ Liquid::Template.register_filter(Jekyll::AssetFilter)
<div class="note">
<h5>ProTip™: Access the site object using Liquid</h5>
<p>Jekyll lets you access the <code>site</code> object through the <code>context.registers</code> feature of liquid. For example, you can access the global configuration file <code>_config.yml</code> using <code>context.registers.config</code>.</p>
<p>
Jekyll lets you access the <code>site</code> object through the
<code>context.registers</code> feature of Liquid. For example, you can
access the global configuration file <code>_config.yml</code> using
<code>context.registers.config</code>.
</p>
</div>
### Flags
@ -276,25 +306,36 @@ There are two flags to be aware of when writing a plugin:
<p><code>safe</code></p>
</td>
<td>
<p>A boolean flag that allows a plugin to be safely included in
Jekyll core for exclusion from use with GitHub Pages. In general, set
this to <code>true</code>.</p>
<p>
A boolean flag that informs Jekyll whether this plugin may be safely
executed in an environment where arbitrary code execution is not
allowed. This is used by GitHub Pages to determine which core plugins
may be used, and which are unsafe to run. If your plugin does not
allow for arbitrary code, execution, set this to <code>true</code>.
GitHub Pages still won't load your plugin, but if you submit it for
inclusion in core, it's best for this to be correct!
</p>
</td>
</tr>
<tr>
<td>
<p><code>priortiy</code></p>
<p><code>priority</code></p>
</td>
<td>
<p>This flag determines what order the plugin is loaded in. Valid
values are: <code>:lowest</code>, <code>:low</code>, <code>:normal</code>, <code>:high</code>, and <code>:highest</code>.</p>
<p>
This flag determines what order the plugin is loaded in. Valid values
are: <code>:lowest</code>, <code>:low</code>, <code>:normal</code>,
<code>:high</code>, and <code>:highest</code>. Highest priority
matches are applied first, lowest priority are applied last.
</p>
</td>
</tr>
</tbody>
</table>
</div>
To use one of the example plugins above as an illustration, here is how you’d specify these two flags:
To use one of the example plugins above as an illustration, here is how you’d
specify these two flags:
{% highlight ruby %}
module Jekyll
@ -306,16 +347,15 @@ module Jekyll
end
{% endhighlight %}
## Available Plugins
There are a few useful, prebuilt plugins at the following locations:
- [Truncate HTML while preserving markup structure](https://github.com/MattHall/truncatehtml) by [Matt Hall](http://codebeef.com)
- [Generic Blog Plugins by Jose Diaz-Gonzalez](https://github.com/josegonzalez/josediazgonzalez.com/tree/master/_plugins): Contains plugins for tags, categories, archives, as well as a few liquid extensions
- [Generic Blog Plugins by Jose Diaz-Gonzalez](https://github.com/josegonzalez/josediazgonzalez.com/tree/master/_plugins): Contains plugins for tags, categories, archives, as well as a few Liquid extensions
- [Domain Name Filter by Lawrence Woodman](https://github.com/LawrenceWoodman/domain_name-liquid_filter): Filters the input text so that just the domain name is left
- [Jekyll Plugins by Recursive Design](http://recursive-design.com/projects/jekyll-plugins/): Plugin to generate Project pages from github readmes, a Category page plugin, and a Sitemap generator
- [Tag Cloud Plugin from a Jekyll walk-through](http://vitobotta.com/how-to-migrate-from-wordpress-to-jekyll/): Plugin to generate a Tag Cloud
- [Jekyll Plugins by Recursive Design](http://recursive-design.com/projects/jekyll-plugins/): Plugin to generate Project pages from GitHub readmes, a Category page plugin, and a Sitemap generator
- [Tag Cloud Plugin from a Jekyll walk-through](http://vitobotta.com/how-to-migrate-from-wordpress-to-jekyll/): Plugin to generate a tag cloud
- [Pygments Cache Path by Raimonds Simanovskis](https://github.com/rsim/blog.rayapps.com/blob/master/_plugins/pygments_cache_patch.rb): Plugin to cache syntax-highlighted code from Pygments
- [Delicious Plugin by Christian Hellsten](https://github.com/christianhellsten/jekyll-plugins): Fetches and renders bookmarks from delicious.com.
- [Ultraviolet plugin by Steve Alex](https://gist.github.com/480380): Jekyll Plugin for Ultraviolet
@ -388,5 +428,9 @@ There are a few useful, prebuilt plugins at the following locations:
<div class="note info">
<h5>Jekyll Plugins Wanted</h5>
<p>If you have a Jekyll plugin that you would like to see added to this list, you should <a href="../contributing">read the contributing page</a> to find out how to make that happen.</p>
<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>

99
site/_posts/2012-07-01-posts.md
View File

@ -5,77 +5,121 @@ prev_section: frontmatter
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
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
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 %}
YEAR-MONTH-DAY-title.MARKUP
{% 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 %}
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
{% endhighlight %}
### 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
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:
{% highlight bash %}
{% highlight text %}
… which is shown in the screenshot below:
![My helpful screenshot]({{ "{{ site.url " }}}}/assets/screenshot.jpg)
![My helpful screenshot]({% raw %}{{ site.url }}{% endraw %}/assets/screenshot.jpg)
{% endhighlight %}
Linking to a PDF for readers to download:
{% highlight bash %}
… you can [get the PDF]({{ "{{ site.url " }}}}/assets/mydoc.pdf) directly.
{% highlight text %}
… you can [get the PDF]({% raw %}{{ site.url }}{% endraw %}/assets/mydoc.pdf) directly.
{% endhighlight %}
<div class="note">
<h5>ProTip™: Link using just the site root URL</h5>
<p>You can skip the <code>{{ "{{ 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>
## 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 %}
<ul>
{{ "{% for post in site.posts " }}%}
{% raw %}{% for post in site.posts %}{% endraw %}
<li>
<a href="{{ "{{ post.url "}}}}">{{ "{{ post.title "}}}}</a>
<a href="{% raw %}{{ post.url }}{% endraw %}">{% raw %}{{ post.title }}{% endraw %}</a>
</li>
{{ "{% endfor " }}%}
{% raw %}{% endfor %}{% endraw %}
</ul>
{% endhighlight %}
Of course, you have full control over how (and where) you display your posts, and how you structure your site. You should read more about [how templates work](../templates) with Jekyll if you’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
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 ruby"}} %}
{% highlight text %}
{% raw %}{% highlight ruby %}{% endraw %}
def show
@widget = Widget(params[:id])
respond_to do |format|
@ -83,7 +127,7 @@ def show
format.json { render json: @widget }
end
end
{{ "{% endhighlight"}} %}
{% raw %}{% endhighlight %}{% endraw %}
{% endhighlight %}
And the output will look like this:
@ -100,7 +144,14 @@ end
<div class="note">
<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>
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.

76
site/_posts/2012-07-01-structure.md
View File

@ -5,7 +5,13 @@ prev_section: usage
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:
@ -41,7 +47,13 @@ An overview of what each of these does:
<p><code>_config.yml</code></p>
</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>
</tr>
<tr>
@ -49,7 +61,15 @@ An overview of what each of these does:
<p><code>_includes</code></p>
</td>
<td>
<p>These are the partials that can be mixed and matched by your _layouts and _posts to facilitate reuse. The liquid tag <code>{{ "{% 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>
</tr>
<tr>
@ -57,7 +77,15 @@ An overview of what each of these does:
<p><code>_layouts</code></p>
</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>
</tr>
<tr>
@ -65,7 +93,16 @@ An overview of what each of these does:
<p><code>_posts</code></p>
</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>
</tr>
<tr>
@ -73,7 +110,13 @@ An overview of what each of these does:
<p><code>_site</code></p>
</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>
</tr>
<tr>
@ -81,7 +124,15 @@ An overview of what each of these does:
<p><code>index.html</code> and other HTML, Markdown, Textile files</p>
</td>
<td>
<p>Provided that the file has a <a href="../frontmatter">YAML Front Matter</a> section, it will be transformed by Jekyll. The same will happen for any <code>.html</code>, <code>.markdown</code>, <code>.md</code>, or <code>.textile</code> file in your site's root directory or directories not listed above.</p>
<p>
Provided that the file has a <a href="../frontmatter">YAML Front
Matter</a> section, it will be transformed by Jekyll. The same will
happen for any <code>.html</code>, <code>.markdown</code>,
<code>.md</code>, or <code>.textile</code> file in your site's root
directory or directories not listed above.
</p>
</td>
</tr>
<tr>
@ -89,7 +140,16 @@ An overview of what each of these does:
<p>Other Files/Folders</p>
</td>
<td>
<p>Every other directory and file except for those listed above—such as <code>css</code> and <code>images</code> folders, <code>favicon.ico</code> files, and so forth—will be 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>
</tr>
</tbody>

107
site/_posts/2012-07-01-templates.md
View File

@ -5,7 +5,11 @@ prev_section: migrations
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
@ -25,7 +29,7 @@ Jekyll uses the [Liquid](http://www.liquidmarkup.org/) templating language to pr
</td>
<td class='align-center'>
<p>
<code class='filter'>{{ "{{ site.time | date_to_xmlschema " }}}}</code>
<code class='filter'>{% raw %}{{ site.time | date_to_xmlschema }}{% endraw %}</code>
</p>
<p>
<code class='output'>2008-11-17T13:07:54-08:00</code>
@ -39,7 +43,7 @@ Jekyll uses the [Liquid](http://www.liquidmarkup.org/) templating language to pr
</td>
<td class='align-center'>
<p>
<code class='filter'>{{ "{{ site.time | date_to_string " }}}}</code>
<code class='filter'>{% raw %}{{ site.time | date_to_string }}{% endraw %}</code>
</p>
<p>
<code class='output'>17 Nov 2008</code>
@ -53,7 +57,7 @@ Jekyll uses the [Liquid](http://www.liquidmarkup.org/) templating language to pr
</td>
<td class='align-center'>
<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>
<code class='output'>17 November 2008</code>
@ -67,18 +71,21 @@ Jekyll uses the [Liquid](http://www.liquidmarkup.org/) templating language to pr
</td>
<td class='align-center'>
<p>
<code class='filter'>{{ "{{ page.content | xml_escape " }}}}</code>
<code class='filter'>{% raw %}{{ page.content | xml_escape }}{% endraw %}</code>
</p>
</td>
</tr>
<tr>
<td>
<p class='name'><strong>CGI Escape</strong></p>
<p>CGI escape a string for use in a URL. Replaces any special characters with appropriate %XX replacements.</p>
<p>
CGI escape a string for use in a URL. Replaces any special characters
with appropriate %XX replacements.
</p>
</td>
<td class='align-center'>
<p>
<code class='filter'>{{ "{{ “foo,bar;baz?” | cgi_escape " }}}}</code>
<code class='filter'>{% raw %}{{ “foo,bar;baz?” | cgi_escape }}{% endraw %}</code>
</p>
<p>
<code class='output'>foo%2Cbar%3Bbaz%3F</code>
@ -92,7 +99,7 @@ Jekyll uses the [Liquid](http://www.liquidmarkup.org/) templating language to pr
</td>
<td class='align-center'>
<p>
<code class='filter'>{{ "{{ page.content | number_of_words " }}}}</code>
<code class='filter'>{% raw %}{{ page.content | number_of_words }}{% endraw %}</code>
</p>
<p>
<code class='output'>1337</code>
@ -106,7 +113,7 @@ Jekyll uses the [Liquid](http://www.liquidmarkup.org/) templating language to pr
</td>
<td class='align-center'>
<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>
<code class='output'>foo, bar, and baz</code>
@ -120,7 +127,7 @@ Jekyll uses the [Liquid](http://www.liquidmarkup.org/) templating language to pr
</td>
<td class='align-center'>
<p>
<code class='filter'>{{ "{{ page.excerpt | textilize " }}}}</code>
<code class='filter'>{% raw %}{{ page.excerpt | textilize }}{% endraw %}</code>
</p>
</td>
</tr>
@ -131,7 +138,7 @@ Jekyll uses the [Liquid](http://www.liquidmarkup.org/) templating language to pr
</td>
<td class='align-center'>
<p>
<code class='filter'>{{ "{{ page.excerpt | markdownify " }}}}</code>
<code class='filter'>{% raw %}{{ page.excerpt | markdownify }}{% endraw %}</code>
</p>
</td>
</tr>
@ -141,78 +148,88 @@ Jekyll uses the [Liquid](http://www.liquidmarkup.org/) templating language to pr
## Tags
### Includes (Partials)
### Includes
If you have small page fragments that you wish to include in multiple
places on your site, you can use the `include` tag.
If you have small page fragments that you wish to include in multiple places on
your site, you can use the `include` tag.
{% highlight ruby %}
{{ "{% include sig.textile " }}%}
{% raw %}{% include sig.md %}{% endraw %}
{% endhighlight %}
Jekyll expects all include files to be placed in an `_includes`
directory at the root of your source dir. So this will embed the
contents of `/path/to/your/site/_includes/sig.textile` into the calling
file.
Jekyll expects all include files to be placed in an `_includes` directory at the
root of your source directory. This will embed the contents of
`<source>/_includes/sig.md` into the calling file.
### Code snippet highlighting
Jekyll has built in support for syntax highlighting of [over 100
languages](http://pygments.org/languages/) thanks to
[Pygments](http://pygments.org/). In order to take advantage of this
you’ll need to have Pygments installed, and the `pygmentize` binary must
be in your `$PATH`. When you run Jekyll, make sure you run it with
[Pygments enabled](../extras).
[Pygments](http://pygments.org/). In order to take advantage of this you’ll need
to have Pygments installed, and the `pygmentize` binary must be in your `$PATH`.
When you run Jekyll, make sure you run it with [Pygments enabled](../extras).
To render a code block with syntax highlighting, surround your code as follows:
{% highlight text %}
{% raw %}
{% highlight ruby %}
{{ "{% highlight ruby " }}%}
def foo
puts 'foo'
end
{{ "{% endhighlight " }}%}
{% endhighlight %}
{% endraw %}
{% endhighlight %}
The argument to the `highlight` tag (`ruby` in the example above) is the language identifier. To find the appropriate identifier to use for the language you want to highlight, look for the “short name” on the [Lexers page](http://pygments.org/docs/lexers/).
The argument to the `highlight` tag (`ruby` in the example above) is the
language identifier. To find the appropriate identifier to use for the language
you want to highlight, look for the “short name” on the [Lexers
page](http://pygments.org/docs/lexers/).
#### Line numbers
There is a second argument to `highlight` called `linenos` that is
optional. Including the `linenos` argument will force the highlighted
code to include line numbers. For instance, the following code block
would include line numbers next to each line:
There is a second argument to `highlight` called `linenos` that is optional.
Including the `linenos` argument will force the highlighted code to include line
numbers. For instance, the following code block would include line numbers next
to each line:
{% highlight ruby %}
{{ "{% highlight ruby linenos " }}%}
{% highlight text %}
{% raw %}
{% highlight ruby linenos %}
def foo
puts 'foo'
end
{{ "{% endhighlight " }}%}
{% endhighlight %}
{% endraw %}
{% endhighlight %}
#### Stylesheets for syntax highlighting
In order for the highlighting to show up, you’ll need to include a
highlighting stylesheet. For an example stylesheet you can look at
[syntax.css](http://github.com/mojombo/tpw/tree/master/css/syntax.css).
These are the same styles as used by GitHub and you are free to use them
for your own site. If you use linenos, you might want to include an
additional CSS class definition for the `.lineno` class in `syntax.css` to
distinguish the line numbers from the highlighted code.
In order for the highlighting to show up, you’ll need to include a highlighting
stylesheet. For an example stylesheet you can look at
[syntax.css](http://github.com/mojombo/tpw/tree/master/css/syntax.css). These
are the same styles as used by GitHub and you are free to use them for your own
site. If you use `linenos`, you might want to include an additional CSS class
definition for the `.lineno` class in `syntax.css` to distinguish the line
numbers from the highlighted code.
### Post URL
If you would like to include a link to a post on your site, the `post_url` tag will generate the correct permalink URL for the post you specify.
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 %}
{{ "{% post_url 2010-07-21-name-of-post " }}%}
{% highlight text %}
{% raw %}
{% post_url 2010-07-21-name-of-post %}
{% endraw %}
{% endhighlight %}
There is no need to include the file extension when using the `post_url` tag.
You can also use this tag to create a link to a post in Markdown as follows:
{% highlight html %}
[Name of Link]({{ "{% post_url 2010-07-21-name-of-post " }}%})
{% highlight text %}
{% raw %}
[Name of Link]({% post_url 2010-07-21-name-of-post %})
{% endraw %}
{% endhighlight %}

51
site/_posts/2012-07-01-usage.md
View File

@ -5,34 +5,53 @@ prev_section: installation
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 %}
jekyll build
#=> The current folder will get generated into ./_site
jekyll build --destination <destination>
#=> The current folder will get generated into <destination>
jekyll build --source <source> --destination <destination>
#=> The <source> folder will get generated into <destination>
jekyll build --watch
#=> The current folder will get generated into ./_site,
# and watch for changes and regenerate automatically.
$ jekyll build
# => The current folder will be generated into ./_site
$ jekyll build --destination <destination>
# => The current folder will be generated into <destination>
$ jekyll build --source <source> --destination <destination>
# => The <source> folder will be generated into <destination>
$ jekyll build --watch
# => The current folder will be generated into ./_site,
# watched for changes, and regenerated automatically.
{% endhighlight %}
Jekyll also comes with a built-in development server that will allow you to preview what the generated site will look like in your browser locally.
Jekyll also comes with a built-in development server that will allow you to
preview what the generated site will look like in your browser locally.
{% highlight bash %}
jekyll serve
$ jekyll serve
# => 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 %}
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 %}
source: _source
destination: _deploy
{% 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.

182
site/_posts/2012-07-01-variables.md
View File

@ -5,7 +5,11 @@ prev_section: pages
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
@ -20,19 +24,41 @@ Jekyll traverses your site looking for files to process. Any files with [YAML Fr
<tbody>
<tr>
<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>
<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>
<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>
<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>
</tbody>
</table>
@ -51,27 +77,61 @@ Jekyll traverses your site looking for files to process. Any files with [YAML Fr
<tbody>
<tr>
<td><p><code>site.time</code></p></td>
<td><p>The current time (when you run the <code>jekyll</code> command).</p></td>
<td><p>
The current time (when you run the <code>jekyll</code> command).
</p></td>
</tr>
<tr>
<td><p><code>site.posts</code></p></td>
<td><p>A reverse chronological list of all Posts.</p></td>
<td><p>
A reverse chronological list of all Posts.
</p></td>
</tr>
<tr>
<td><p><code>site.related_posts</code></p></td>
<td><p>If the page being processed is a Post, this contains a list of up to ten related Posts. By default, these are low quality but fast to compute. For high quality but slow to compute results, run the <code>jekyll</code> command with the <code>--lsi</code> (latent semantic indexing) option.</p></td>
<td><p>
If the page being processed is a Post, this contains a list of up to ten
related Posts. By default, these are low quality but fast to compute.
For high quality but slow to compute results, run the
<code>jekyll</code> command with the <code>--lsi</code> (latent semantic
indexing) option.
</p></td>
</tr>
<tr>
<td><p><code>site.categories.CATEGORY</code></p></td>
<td><p>The list of all Posts in category <code>CATEGORY</code>.</p></td>
<td><p>
The list of all Posts in category <code>CATEGORY</code>.
</p></td>
</tr>
<tr>
<td><p><code>site.tags.TAG</code></p></td>
<td><p>The list of all Posts with tag <code>TAG</code>.</p></td>
<td><p>
The list of all Posts with tag <code>TAG</code>.
</p></td>
</tr>
<tr>
<td><p><code>site.[CONFIGURATION_DATA]</code></p></td>
<td><p>All 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>
</tbody>
</table>
@ -90,31 +150,87 @@ Jekyll traverses your site looking for files to process. Any files with [YAML Fr
<tbody>
<tr>
<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>
<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>
<td><p><code>page.excerpt</code></p></td>
<td><p>
The un-rendered excerpt of the Page.
</p></td>
</tr>
<tr>
<td><p><code>page.url</code></p></td>
<td><p>The URL of the Post without the domain. 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>
<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>
<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>
<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>
<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>
<td><p><code>page.path</code></p></td>
<td><p>
The path to the raw post or page. Example usage: Linking back to the
page or post's source on GitHub. This can be overridden in the
<a href="../frontmatter">YAML Front Matter</a>.
</p></td>
</tr>
</tbody>
</table>
@ -122,7 +238,14 @@ Jekyll traverses your site looking for files to process. Any files with [YAML Fr
<div class="note">
<h5>ProTip™: Use custom front-matter</h5>
<p>Any custom front matter that you specify will be available under <code>page</code>. For example, if you specify <code>custom_css: true</code> in a page’s front matter, that value will be available 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>
## Paginator
@ -138,7 +261,7 @@ Jekyll traverses your site looking for files to process. Any files with [YAML Fr
<tbody>
<tr>
<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>
<td><p><code>paginator.posts</code></p></td>
@ -146,11 +269,11 @@ Jekyll traverses your site looking for files to process. Any files with [YAML Fr
</tr>
<tr>
<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>
<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>
<td><p><code>paginator.page</code></p></td>
@ -160,15 +283,28 @@ Jekyll traverses your site looking for files to process. Any files with [YAML Fr
<td><p><code>paginator.previous_page</code></p></td>
<td><p>The number of the previous page.</p></td>
</tr>
<tr>
<td><p><code>paginator.previous_page_path</code></p></td>
<td><p>The path to the previous page.</p></td>
</tr>
<tr>
<td><p><code>paginator.next_page</code></p></td>
<td><p>The number of the next page.</p></td>
</tr>
<tr>
<td><p><code>paginator.next_page_path</code></p></td>
<td><p>The path to the next page.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="note info">
<h5>Paginator variable availability</h5>
<p>These are only available in index files, however they can be located in a subdirectory, such as <code>/blog/index.html</code>.</p>
<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>

2
site/css/style.css
View File

@ -520,7 +520,7 @@ pre, code {
}
}
.highlight, p > pre, p > code {
.highlight, p > pre, p > code, p > nobr > code, li > code {
background: #333;
color: #fff;
border-radius: 5px;

9
site/index.html
View File

@ -51,10 +51,15 @@ overview: true
<p class="line">
<span class="path">~</span>
<span class="prompt">$</span>
<span class="command">cd my/awesome/site</span>
<span class="command">jekyll new my-awesome-site</span>
</p>
<p class="line">
<span class="path">~/my/awesome/site</span>
<span class="path">~</span>
<span class="prompt">$</span>
<span class="command">cd my-awesome-site</span>
</p>
<p class="line">
<span class="path">~/my-awesome-site</span>
<span class="prompt">$</span>
<span class="command">jekyll serve</span>
</p>

0
test/source/_posts/2013-03-19-not-a-post.markdown/.gitkeep Normal file
View File

10
test/source/_posts/2013-04-11-custom-excerpt.markdown Normal file
View File

@ -0,0 +1,10 @@
---
layout: ~
excerpt: 'I can set a custom excerpt'
---
This is not my excerpt.
Neither is this.
I can use the excerpt: <quote>{{page.excerpt}}</quote>

100
test/test_configuration.rb
View File

@ -1,6 +1,72 @@
require 'helper'
class TestConfiguration < Test::Unit::TestCase
context "#stringify_keys" do
setup do
@mixed_keys = Configuration[{
'markdown' => 'maruku',
:permalink => 'date',
'baseurl' => '/',
:include => ['.htaccess'],
:source => './'
}]
@string_keys = Configuration[{
'markdown' => 'maruku',
'permalink' => 'date',
'baseurl' => '/',
'include' => ['.htaccess'],
'source' => './'
}]
end
should "stringify symbol keys" do
assert_equal @string_keys, @mixed_keys.stringify_keys
end
should "not mess with keys already strings" do
assert_equal @string_keys, @string_keys.stringify_keys
end
end
context "#config_files" do
setup do
@config = Configuration[{"source" => source_dir}]
@no_override = {}
@one_config_file = {"config" => "config.yml"}
@multiple_files = {"config" => %w[config/site.yml config/deploy.yml configuration.yml]}
end
should "always return an array" do
assert @config.config_files(@no_override).is_a?(Array)
assert @config.config_files(@one_config_file).is_a?(Array)
assert @config.config_files(@multiple_files).is_a?(Array)
end
should "return the default config path if no config files are specified" do
assert_equal [File.join(source_dir, "_config.yml")], @config.config_files(@no_override)
end
should "return the config if given one config file" do
assert_equal %w[config.yml], @config.config_files(@one_config_file)
end
should "return an array of the config files if given many config files" do
assert_equal %w[config/site.yml config/deploy.yml configuration.yml], @config.config_files(@multiple_files)
end
end
context "#backwards_compatibilize" do
setup do
@config = Configuration[{
"auto" => true,
"watch" => true,
"server" => true
}]
end
should "unset 'auto' and 'watch'" do
assert @config.has_key?("auto")
assert @config.has_key?("watch")
assert !@config.backwards_compatibilize.has_key?("auto")
assert !@config.backwards_compatibilize.has_key?("watch")
end
should "unset 'server'" do
assert @config.has_key?("server")
assert !@config.backwards_compatibilize.has_key?("server")
end
end
context "loading configuration" do
setup do
@path = File.join(Dir.pwd, '_config.yml')
@ -8,21 +74,21 @@ class TestConfiguration < Test::Unit::TestCase
should "fire warning with no _config.yml" do
mock(YAML).safe_load_file(@path) { raise SystemCallError, "No such file or directory - #{@path}" }
mock($stderr).puts("Configuration file: none")
assert_equal Jekyll::DEFAULTS, Jekyll.configuration({})
mock($stderr).puts("Configuration file: none".yellow)
assert_equal Jekyll::Configuration::DEFAULTS, Jekyll.configuration({})
end
should "load configuration as hash" do
mock(YAML).safe_load_file(@path) { Hash.new }
mock($stdout).puts("Configuration file: #{@path}")
assert_equal Jekyll::DEFAULTS, Jekyll.configuration({})
assert_equal Jekyll::Configuration::DEFAULTS, Jekyll.configuration({})
end
should "fire warning with bad config" do
mock(YAML).safe_load_file(@path) { Array.new }
mock($stderr).puts(" WARNING: Error reading configuration. Using defaults (and options).")
mock($stderr).puts("Configuration file: (INVALID) #{@path}")
assert_equal Jekyll::DEFAULTS, Jekyll.configuration({})
mock($stderr).puts(("WARNING: ".rjust(20) + "Error reading configuration. Using defaults (and options).").yellow)
mock($stderr).puts("Configuration file: (INVALID) #{@path}".yellow)
assert_equal Jekyll::Configuration::DEFAULTS, Jekyll.configuration({})
end
end
context "loading config from external file" do
@ -37,19 +103,35 @@ class TestConfiguration < Test::Unit::TestCase
should "load default config if no config_file is set" do
mock(YAML).safe_load_file(@paths[:default]) { Hash.new }
mock($stdout).puts("Configuration file: #{@paths[:default]}")
assert_equal Jekyll::DEFAULTS, Jekyll.configuration({})
assert_equal Jekyll::Configuration::DEFAULTS, Jekyll.configuration({})
end
should "load different config if specified" do
mock(YAML).safe_load_file(@paths[:other]) { {"baseurl" => "http://wahoo.dev"} }
mock($stdout).puts("Configuration file: #{@paths[:other]}")
assert_equal Jekyll::DEFAULTS.deep_merge({ "baseurl" => "http://wahoo.dev" }), Jekyll.configuration({ "config" => @paths[:other] })
assert_equal Jekyll::Configuration::DEFAULTS.deep_merge({ "baseurl" => "http://wahoo.dev" }), Jekyll.configuration({ "config" => @paths[:other] })
end
should "load default config if path passed is empty" do
mock(YAML).safe_load_file(@paths[:default]) { Hash.new }
mock($stdout).puts("Configuration file: #{@paths[:default]}")
assert_equal Jekyll::DEFAULTS, Jekyll.configuration({ "config" => @paths[:empty] })
assert_equal Jekyll::Configuration::DEFAULTS, Jekyll.configuration({ "config" => @paths[:empty] })
end
should "load multiple config files" do
mock(YAML).safe_load_file(@paths[:default]) { Hash.new }
mock(YAML).safe_load_file(@paths[:other]) { Hash.new }
mock($stdout).puts("Configuration file: #{@paths[:default]}")
mock($stdout).puts("Configuration file: #{@paths[:other]}")
assert_equal Jekyll::Configuration::DEFAULTS, Jekyll.configuration({ "config" => [@paths[:default], @paths[:other]] })
end
should "load multiple config files and last config should win" do
mock(YAML).safe_load_file(@paths[:default]) { {"baseurl" => "http://example.dev"} }
mock(YAML).safe_load_file(@paths[:other]) { {"baseurl" => "http://wahoo.dev"} }
mock($stdout).puts("Configuration file: #{@paths[:default]}")
mock($stdout).puts("Configuration file: #{@paths[:other]}")
assert_equal Jekyll::Configuration::DEFAULTS.deep_merge({ "baseurl" => "http://wahoo.dev" }), Jekyll.configuration({ "config" => [@paths[:default], @paths[:other]] })
end
end
end

2
test/test_convertible.rb
View File

@ -25,7 +25,7 @@ class TestConvertible < Test::Unit::TestCase
ret = @convertible.read_yaml(@base, name)
assert_equal({}, ret)
end
assert_match(/YAML Exception|syntax error/, out)
assert_match(/YAML Exception|syntax error|Error reading file/, out)
assert_match(/#{File.join(@base, name)}/, out)
end

17
test/test_filters.rb
View File

@ -13,6 +13,7 @@ class TestFilters < Test::Unit::TestCase
context "filters" do
setup do
@filter = JekyllFilter.new
@sample_time = Time.utc(2013, 03, 27, 11, 22, 33)
end
should "textilize with simple string" do
@ -42,6 +43,22 @@ class TestFilters < Test::Unit::TestCase
assert_equal "chunky, bacon, bits, and pieces", @filter.array_to_sentence_string(["chunky", "bacon", "bits", "pieces"])
end
should "format a date with short format" do
assert_equal "27 Mar 2013", @filter.date_to_string(@sample_time)
end
should "format a date with long format" do
assert_equal "27 March 2013", @filter.date_to_long_string(@sample_time)
end
should "format a time with xmlschema" do
assert_equal "2013-03-27T11:22:33Z", @filter.date_to_xmlschema(@sample_time)
end
should "format a time according to RFC-822" do
assert_equal "Wed, 27 Mar 2013 11:22:33 -0000", @filter.date_to_rfc822(@sample_time)
end
should "escape xml with ampersands" do
assert_equal "AT&amp;T", @filter.xml_escape("AT&T")
assert_equal "&lt;code&gt;command &amp;lt;filename&amp;gt;&lt;/code&gt;", @filter.xml_escape("<code>command &lt;filename&gt;</code>")

21
test/test_generated_site.rb
View File

@ -5,7 +5,7 @@ class TestGeneratedSite < Test::Unit::TestCase
setup do
clear_dest
stub(Jekyll).configuration do
Jekyll::DEFAULTS.merge({'source' => source_dir, 'destination' => dest_dir})
Jekyll::Configuration::DEFAULTS.merge({'source' => source_dir, 'destination' => dest_dir})
end
@site = Site.new(Jekyll.configuration)
@ -14,7 +14,7 @@ class TestGeneratedSite < Test::Unit::TestCase
end
should "ensure post count is as expected" do
assert_equal 31, @site.posts.size
assert_equal 32, @site.posts.size
end
should "insert site.posts into the index" do
@ -46,7 +46,7 @@ class TestGeneratedSite < Test::Unit::TestCase
setup do
clear_dest
stub(Jekyll).configuration do
Jekyll::DEFAULTS.merge({'source' => source_dir, 'destination' => dest_dir, 'limit_posts' => 5})
Jekyll::Configuration::DEFAULTS.merge({'source' => source_dir, 'destination' => dest_dir, 'limit_posts' => 5})
end
@site = Site.new(Jekyll.configuration)
@ -58,11 +58,22 @@ class TestGeneratedSite < Test::Unit::TestCase
assert_equal 5, @site.posts.size
end
should "ensure limit posts is 1 or more" do
should "ensure limit posts is 0 or more" do
assert_raise ArgumentError do
clear_dest
stub(Jekyll).configuration do
Jekyll::DEFAULTS.merge({'source' => source_dir, 'destination' => dest_dir, 'limit_posts' => 0})
Jekyll::Configuration::DEFAULTS.merge({'source' => source_dir, 'destination' => dest_dir, 'limit_posts' => -1})
end
@site = Site.new(Jekyll.configuration)
end
end
should "acceptable limit post is 0" do
assert_nothing_raised ArgumentError do
clear_dest
stub(Jekyll).configuration do
Jekyll::Configuration::DEFAULTS.merge({'source' => source_dir, 'destination' => dest_dir, 'limit_posts' => 0})
end
@site = Site.new(Jekyll.configuration)

6
test/test_kramdown.rb
View File

@ -1,3 +1,5 @@
# encoding: UTF-8
require 'helper'
class TestKramdown < Test::Unit::TestCase
@ -23,11 +25,11 @@ class TestKramdown < Test::Unit::TestCase
should "convert quotes to smart quotes" do
markdown = Converters::Markdown.new(@config)
assert_equal "<p>&#8220;Pit&#8217;hy&#8221;</p>", markdown.convert(%{"Pit'hy"}).strip
assert_match /<p>(&#8220;|“)Pit(&#8217;|’)hy(&#8221;|”)<\/p>/, markdown.convert(%{"Pit'hy"}).strip
override = { 'kramdown' => { 'smart_quotes' => 'lsaquo,rsaquo,laquo,raquo' } }
markdown = Converters::Markdown.new(@config.deep_merge(override))
assert_equal "<p>&#171;Pit&#8250;hy&#187;</p>", markdown.convert(%{"Pit'hy"}).strip
assert_match /<p>(&#171;|«)Pit(&#8250;|›)hy(&#187;|»)<\/p>/, markdown.convert(%{"Pit'hy"}).strip
end
end
end

12
test/test_page.rb
View File

@ -15,7 +15,7 @@ class TestPage < Test::Unit::TestCase
context "A Page" do
setup do
clear_dest
stub(Jekyll).configuration { Jekyll::DEFAULTS }
stub(Jekyll).configuration { Jekyll::Configuration::DEFAULTS }
@site = Site.new(Jekyll.configuration)
end
@ -103,16 +103,6 @@ class TestPage < Test::Unit::TestCase
end
end
context "with unspecified layout" do
setup do
@page = setup_page('contacts.html')
end
should "default to 'post' layout" do
assert_equal "page", @page.data["layout"]
end
end
context "with specified layout of nil" do
setup do
@page = setup_page('sitemap.xml')

4
test/test_pager.rb
View File

@ -14,7 +14,7 @@ class TestPager < Test::Unit::TestCase
context "pagination disabled" do
setup do
stub(Jekyll).configuration do
Jekyll::DEFAULTS.merge({
Jekyll::Configuration::DEFAULTS.merge({
'source' => source_dir,
'destination' => dest_dir
})
@ -31,7 +31,7 @@ class TestPager < Test::Unit::TestCase
context "pagination enabled for 2" do
setup do
stub(Jekyll).configuration do
Jekyll::DEFAULTS.merge({
Jekyll::Configuration::DEFAULTS.merge({
'source' => source_dir,
'destination' => dest_dir,
'paginate' => 2

61
test/test_post.rb
View File

@ -13,7 +13,7 @@ class TestPost < Test::Unit::TestCase
context "A Post" do
setup do
clear_dest
stub(Jekyll).configuration { Jekyll::DEFAULTS }
stub(Jekyll).configuration { Jekyll::Configuration::DEFAULTS }
@site = Site.new(Jekyll.configuration)
end
@ -95,7 +95,7 @@ class TestPost < Test::Unit::TestCase
should "consume the embedded dashes" do
@post.read_yaml(@source, @real_file)
assert_equal({"title" => "Foo --- Bar", "layout" => "post"}, @post.data)
assert_equal({"title" => "Foo --- Bar"}, @post.data)
assert_equal "Triple the fun!", @post.content
end
end
@ -140,18 +140,6 @@ class TestPost < Test::Unit::TestCase
end
end
context "with unspecified layout" do
setup do
file = '2013-01-12-no-layout.textile'
@post = setup_post(file)
@post.process(file)
end
should "default to 'post' layout" do
assert_equal "post", @post.data["layout"]
end
end
context "with specified layout of nil" do
setup do
file = '2013-01-12-nil-layout.textile'
@ -214,6 +202,18 @@ class TestPost < Test::Unit::TestCase
end
end
context "with ordinal style" do
setup do
@post.site.permalink_style = :ordinal
@post.process(@fake_file)
end
should "process the url correctly" do
assert_equal "/:categories/:year/:y_day/:title.html", @post.template
assert_equal "/2008/253/foo-bar.html", @post.url
end
end
context "with custom date permalink" do
setup do
@post.site.permalink_style = '/:categories/:year/:i_month/:i_day/:title/'
@ -225,6 +225,17 @@ class TestPost < Test::Unit::TestCase
end
end
context "with custom abbreviated month date permalink" do
setup do
@post.site.permalink_style = '/:categories/:year/:short_month/:day/:title/'
@post.process(@fake_file)
end
should "process the url correctly" do
assert_equal "/2008/Sep/09/foo-bar/", @post.url
end
end
context "with prefix style and no extension" do
setup do
@post.site.permalink_style = "/prefix/:title"
@ -297,13 +308,31 @@ class TestPost < Test::Unit::TestCase
assert !@post.excerpt.include?("---"), "does not contains separator"
end
end
context "with custom excerpt" do
setup do
file = "2013-04-11-custom-excerpt.markdown"
@post = setup_post(file)
do_render(@post)
end
should "use custom excerpt" do
assert_equal("I can set a custom excerpt", @post.excerpt)
end
should "expose custom excerpt to liquid" do
assert @post.content.include?("I can use the excerpt: <quote>I can set a custom excerpt</quote>"), "Exposes incorrect excerpt to liquid."
end
end
end
end
context "when in a site" do
setup do
clear_dest
stub(Jekyll).configuration { Jekyll::DEFAULTS }
stub(Jekyll).configuration { Jekyll::Configuration::DEFAULTS }
@site = Site.new(Jekyll.configuration)
@site.posts = [setup_post('2008-02-02-published.textile'),
setup_post('2009-01-27-categories.textile')]
@ -496,7 +525,7 @@ class TestPost < Test::Unit::TestCase
context "converter file extension settings" do
setup do
stub(Jekyll).configuration { Jekyll::DEFAULTS }
stub(Jekyll).configuration { Jekyll::Configuration::DEFAULTS }
@site = Site.new(Jekyll.configuration)
end

36
test/test_site.rb
View File

@ -3,49 +3,49 @@ require 'helper'
class TestSite < Test::Unit::TestCase
context "configuring sites" do
should "have an array for plugins by default" do
site = Site.new(Jekyll::DEFAULTS)
site = Site.new(Jekyll::Configuration::DEFAULTS)
assert_equal [File.join(Dir.pwd, '_plugins')], site.plugins
end
should "look for plugins under the site directory by default" do
site = Site.new(Jekyll::DEFAULTS.merge({'source' => File.expand_path(source_dir)}))
site = Site.new(Jekyll::Configuration::DEFAULTS.merge({'source' => File.expand_path(source_dir)}))
assert_equal [File.join(source_dir, '_plugins')], site.plugins
end
should "have an array for plugins if passed as a string" do
site = Site.new(Jekyll::DEFAULTS.merge({'plugins' => '/tmp/plugins'}))
site = Site.new(Jekyll::Configuration::DEFAULTS.merge({'plugins' => '/tmp/plugins'}))
assert_equal ['/tmp/plugins'], site.plugins
end
should "have an array for plugins if passed as an array" do
site = Site.new(Jekyll::DEFAULTS.merge({'plugins' => ['/tmp/plugins', '/tmp/otherplugins']}))
site = Site.new(Jekyll::Configuration::DEFAULTS.merge({'plugins' => ['/tmp/plugins', '/tmp/otherplugins']}))
assert_equal ['/tmp/plugins', '/tmp/otherplugins'], site.plugins
end
should "have an empty array for plugins if nothing is passed" do
site = Site.new(Jekyll::DEFAULTS.merge({'plugins' => []}))
site = Site.new(Jekyll::Configuration::DEFAULTS.merge({'plugins' => []}))
assert_equal [], site.plugins
end
should "have an empty array for plugins if nil is passed" do
site = Site.new(Jekyll::DEFAULTS.merge({'plugins' => nil}))
site = Site.new(Jekyll::Configuration::DEFAULTS.merge({'plugins' => nil}))
assert_equal [], site.plugins
end
should "expose default baseurl" do
site = Site.new(Jekyll::DEFAULTS)
assert_equal Jekyll::DEFAULTS['baseurl'], site.baseurl
site = Site.new(Jekyll::Configuration::DEFAULTS)
assert_equal Jekyll::Configuration::DEFAULTS['baseurl'], site.baseurl
end
should "expose baseurl passed in from config" do
site = Site.new(Jekyll::DEFAULTS.merge({'baseurl' => '/blog'}))
site = Site.new(Jekyll::Configuration::DEFAULTS.merge({'baseurl' => '/blog'}))
assert_equal '/blog', site.baseurl
end
end
context "creating sites" do
setup do
stub(Jekyll).configuration do
Jekyll::DEFAULTS.merge({'source' => source_dir, 'destination' => dest_dir})
Jekyll::Configuration::DEFAULTS.merge({'source' => source_dir, 'destination' => dest_dir})
end
@site = Site.new(Jekyll.configuration)
end
@ -161,6 +161,7 @@ class TestSite < Test::Unit::TestCase
should "read posts" do
@site.read_posts('')
posts = Dir[source_dir('_posts', '*')]
posts.delete_if { |post| File.directory?(post) }
assert_equal posts.size - 1, @site.posts.size
end
@ -169,9 +170,10 @@ class TestSite < Test::Unit::TestCase
@site.process
posts = Dir[source_dir("**", "_posts", "*")]
posts.delete_if { |post| File.directory?(post) }
categories = %w(bar baz category foo z_category publish_test win).sort
assert_equal posts.size - 1, @site.posts.size
assert_equal posts.size, @site.posts.size
assert_equal categories, @site.categories.keys.sort
assert_equal 4, @site.categories['foo'].size
end
@ -203,7 +205,7 @@ class TestSite < Test::Unit::TestCase
should "filter symlink entries when safe mode enabled" do
stub(Jekyll).configuration do
Jekyll::DEFAULTS.merge({'source' => source_dir, 'destination' => dest_dir, 'safe' => true})
Jekyll::Configuration::DEFAULTS.merge({'source' => source_dir, 'destination' => dest_dir, 'safe' => true})
end
site = Site.new(Jekyll.configuration)
stub(File).symlink?('symlink.js') {true}
@ -219,7 +221,7 @@ class TestSite < Test::Unit::TestCase
should "not include symlinks in safe mode" do
stub(Jekyll).configuration do
Jekyll::DEFAULTS.merge({'source' => source_dir, 'destination' => dest_dir, 'safe' => true})
Jekyll::Configuration::DEFAULTS.merge({'source' => source_dir, 'destination' => dest_dir, 'safe' => true})
end
site = Site.new(Jekyll.configuration)
@ -230,7 +232,7 @@ class TestSite < Test::Unit::TestCase
should "include symlinks in unsafe mode" do
stub(Jekyll).configuration do
Jekyll::DEFAULTS.merge({'source' => source_dir, 'destination' => dest_dir, 'safe' => false})
Jekyll::Configuration::DEFAULTS.merge({'source' => source_dir, 'destination' => dest_dir, 'safe' => false})
end
site = Site.new(Jekyll.configuration)
@ -242,7 +244,7 @@ class TestSite < Test::Unit::TestCase
context 'error handling' do
should "raise if destination is included in source" do
stub(Jekyll).configuration do
Jekyll::DEFAULTS.merge({'source' => source_dir, 'destination' => source_dir})
Jekyll::Configuration::DEFAULTS.merge({'source' => source_dir, 'destination' => source_dir})
end
assert_raise Jekyll::FatalException do
@ -252,7 +254,7 @@ class TestSite < Test::Unit::TestCase
should "raise if destination is source" do
stub(Jekyll).configuration do
Jekyll::DEFAULTS.merge({'source' => source_dir, 'destination' => File.join(source_dir, "..")})
Jekyll::Configuration::DEFAULTS.merge({'source' => source_dir, 'destination' => File.join(source_dir, "..")})
end
assert_raise Jekyll::FatalException do
@ -301,7 +303,7 @@ class TestSite < Test::Unit::TestCase
end
should 'remove orphaned files in destination - keep_files .svn' do
config = Jekyll::DEFAULTS.merge({'source' => source_dir, 'destination' => dest_dir, 'keep_files' => ['.svn']})
config = Jekyll::Configuration::DEFAULTS.merge({'source' => source_dir, 'destination' => dest_dir, 'keep_files' => ['.svn']})
@site = Site.new(config)
@site.process
assert !File.exist?(dest_dir('.htpasswd'))

2
test/test_tags.rb
View File

@ -6,7 +6,7 @@ class TestTags < Test::Unit::TestCase
def create_post(content, override = {}, converter_class = Jekyll::Converters::Markdown)
stub(Jekyll).configuration do
Jekyll::DEFAULTS.deep_merge({'pygments' => true}).deep_merge(override)
Jekyll::Configuration::DEFAULTS.deep_merge({'pygments' => true}).deep_merge(override)
end
site = Site.new(Jekyll.configuration)