README.textile in henrik-jekyll-0.5.0 vs README.textile in henrik-jekyll-0.5.1
- old
+ new
@@ -51,10 +51,16 @@
Posts are handled in a special way by Jekyll. The date you specify in the
filename is used to construct the URL in the generated site. The example post,
for instance, ends up at
<code>http://tom.preston-werner.com/2008/11/17/blogging-like-a-hacker.html</code>.
+Jekyll also supports specifying the post time in the filename. The format is e.g.
+'2009-04-13_23-45-my-post.html'. Note that the time is prefixed by an underscore,
+not a dash, so post slugs starting with numbers won't be parsed incorrectly.
+Times in the filename must be on a 24-hour clock. Times and dates are treated by
+Jekyll as local time.
+
Categories for posts are derived from the directory structure the posts were
found within. A post that appears in the directory foo/bar/_posts is placed in
the categories 'foo' and 'bar'. By selecting posts from particular categories
in your Liquid templates, you will be able to host multiple blogs within a
site.
@@ -133,20 +139,46 @@
For static code highlighting, you can install Pygments (see below) and then
use that to make your code blocks look pretty. To activate Pygments support
during the conversion:
$ jekyll --pygments
+
+Highlighting a blog post can take a second or two, and with a lot of posts,
+it adds up. You can tell Jekyll to cache pygments output in a directory for
+faster re-rendering:
+ $ jekyll --pygments-cache [PATH]
+
h3. Markdown Processor
By default, Jekyll uses "Maruku":http://maruku.rubyforge.org (pure Ruby) for
Markdown support. If you'd like to use RDiscount (faster, but requires
compilation), you must install it (gem install rdiscount) and then you can
have it used instead:
$ jekyll --rdiscount
+
+h3. Sass
+To transform all ".sass":http://github.com/nex3/haml/tree/master
+files anywhere in your file tree to CSS (e.g. '/css/site.sass' will
+generate '/css/site.css'):
+
+ $ jekyll --sass
+
+h3. Haml
+
+To transform ".haml":http://github.com/nex3/haml/tree/master files to HTML
+(e.g. '/about.haml' will generate '/about.html'):
+
+ $ jekyll --haml
+
+Note that files must have a YAML metadata block at the top to be converted,
+and that Haml cannot currently be used for layouts -- only posts and pages.
+
+Haml content is intentionally not filtered, so you can use any Ruby code.
+
h3. Local Server
When previewing complex sites locally, simply opening the site in a web
browser (using file://) can cause problems with links that are relative to
the site root (e.g., "/stylesheets/style.css"). To get around this, Jekyll
@@ -171,11 +203,24 @@
change the permalink style to 'pretty' and directories corresponding to the
date parts and post name will be made and an index.html will be placed in the
leaf directory resulting in URLs like 2008/11/17/blogging-like-a-hacker/.
$ jekyll --permalink [date|none|pretty]
+
+h3. Permalink Date Format
+By default, unless you set the --permalink option to 'none', permalinks begin
+with the date in a 'YYYY/MM/DD' format.
+
+To customize this format, pass --permalink-date a strftime type format string.
+
+ $ jekyll --permalink-date [format string]
+
+For example, to use only the year and month in the slug:
+
+ $ jekyll --permalink-date %Y/%m
+
h2. Configuration File
All of the options listed above can be specified on a site-by-site basis in
a '_config.yml' file at the root of the site's source. As the filename
suggests, the configuration is given in "YAML":http://www.yaml.org/. As
@@ -209,16 +254,26 @@
Parameters set in a configuration file override the default values. Parameters
set using command line options override both the default values and those set
in a configuration file.
+Additionally, you can set defaults for the post data blocks. For example, you
+can set the default layout for posts, so you don't have to specify it in every
+post:
+
+ post_defaults:
+ layout: post
+
+Any values set in the actual post will override these defaults.
+
h2. Data
Jekyll traverses your site looking for files to process. Any files with YAML
front matter (see below) are subject to processing. For each of these files,
-Jekyll makes a variety of data available to the pages via the Liquid
-templating system. The following is a reference of the available data.
+Jekyll makes a variety of data available to the pages via Haml (regular pages
+only) or the Liquid templating system. The following is a reference of the
+available data.
h3. Global
site
Sitewide information.
@@ -237,31 +292,49 @@
site.time
The current Time (when you run the jekyll command).
site.posts
A reverse chronological list of all Posts.
+
+ site.collated_posts
+ A nested hash by year, then month number, then day, then a list of Posts.
+ Suitable for post archives. You probably need to show these with Haml
+ since Liquid is too limited. For example:
+ - site.collated_posts.sort.reverse.each do |year,months|
+ %h2= year
+ - months.sort.reverse.each do |month,days|
+ %h3= Date::MONTHNAMES[month]
+ - days.sort.reverse.each do |day,posts|
+ %ol
+ - posts.each do |post|
+ %li
+ %strong= "#{day}:"
+ = link_to(h(post.title), post.url)
site.related_posts
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 jekyll command with the
--lsi (latent semantic indexing) option.
site.categories.CATEGORY
The list of all Posts in category CATEGORY.
+ site.tags.TAG
+ The list of all Posts tagged TAG.
+
h3. Post
post.title
The title of the Post.
post.url
The URL of the Post without the domain.
e.g. /2008/12/14/my-post.html
post.date
- The Date assigned to the Post.
+ The Date (actually a Time object) assigned to the Post.
post.id
An identifier unique to the Post (useful in RSS feeds).
e.g. /2008/12/14/my-post
@@ -275,10 +348,14 @@
The list of topics for this Post. Topics are derived from the directory
structure beneath the _posts directory. For example, a post at
/_posts/music/metal/2008-12-24-metalocalypse.textile would have this field
set to ['music', 'metal'].
+ post.tags
+ The list of tags on this post. Tags are much like topics, but can only be
+ specified in the YAML part of a post, and are not reflected in the URL.
+
post.content
The content of the Post.
h2. YAML Front Matter
@@ -300,10 +377,13 @@
layout
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.
+
+ A default layout for posts can be set in the configuration file.
+ See above.
h3. Predefined Post Variables
permalink
If you need your processed URLs to be something other than the default
@@ -311,16 +391,25 @@
be used as the final URL.
published
Set to false if you don't want a post to show up when the site is
generated.
+
+ time
+ If you want posts to have a time, you can set this to e.g. '23:45' or
+ '11:45 pm'. This overrides any time specified in the filename like
+ '2009-04-12_23-44-my-post.html'. Note that you must quote the time:
+ time: "23:45"
category/categories
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.
+ tags
+ Similar to categories and topics but not reflected in the URL.
+
h3. 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 <code>title</code>, you can use that in your layout to
@@ -447,9 +536,13 @@
</pre>
This would list all the posts in the category 'foo' by date and title.
The posts within each category are sorted in reverse chronological order.
+
+h2. Tags
+
+Tags are like categories or topics but not reflected in the URL.
h2. Blog migrations
h3. Movable Type