README.textile in jekyll-0.2.1 vs README.textile in jekyll-0.3.0

- old
+ new

@@ -29,13 +29,14 @@ wanted to have a list of all my blog posts. Jekyll hands me a Hash containing various data about my site. A reverse chronological list of all my blog posts can be found in <code>site.posts</code>. Each post, in turn, contains various fields such as <code>title</code> and <code>date</code>. -Jekyll gets the list of blog posts by parsing the files in the -"_posts":http://github.com/mojombo/tpw/tree/master/_posts directory. Each -post's filename contains the publishing date and slug (what shows up in the +Jekyll gets the list of blog posts by parsing the files in any +"_posts":http://github.com/mojombo/tpw/tree/master/_posts directory found in +subdirectories below the root. +Each post's filename contains the publishing date and slug (what shows up in the URL) that the final HTML file should have. Open up the file corresponding to a blog post: "2008-11-17-blogging-like-a-hacker.textile":http://github.com/mojombo/tpw/tree/master/_posts/2008-11-17-blogging-like-a-hacker.textile. GitHub renders textile files by default, so to better understand the file, click on the @@ -50,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>. +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. + Files that do not reside in directories prefixed with an underscore are mirrored into a corresponding directory structure in the generated site. If a file does not have a YAML preface, it is not run through the Liquid interpreter. Binary files are copied over unmodified. @@ -127,11 +134,19 @@ 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 + +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 +can launch a simple WEBrick server (works well in conjunction with --auto). +Default port is 4000: + $ jekyll --server [PORT] + 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 @@ -147,11 +162,11 @@ computed data (such as URL and date). For regular pages, this is just the YAML front matter. content In layout files, this contains the content of the subview(s). In Posts or - pages, this is undefined. + Pages, this is undefined. h3. Site site.time The current Time (when you run the jekyll command). @@ -163,10 +178,13 @@ 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. + h3. Post post.title The title of the Post. @@ -179,10 +197,22 @@ post.id An identifier unique to the Post (useful in RSS feeds). e.g. /2008/12/14/my-post + post.categories + The list of categories to which this post belongs. Categories are + derived from the directory structure above the _posts directory. For + example, a post at /work/code/_posts/2008-12-24-closures.textile + would have this field set to ['work', 'code']. + + post.topics + 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.content The content of the Post. h2. YAML Front Matter @@ -256,11 +286,12 @@ 1337 h3. Include (Tag) -If you have small page fragments that you wish to include in multiple places on your site, you can use the <code>include</code> tag. +If you have small page fragments that you wish to include in multiple places +on your site, you can use the <code>include</code> tag. <pre>{% include sig.textile %}</pre> Jekyll expects all include files to be placed in an <code>_includes</code> directory at the root of your source dir. So this will embed the contents of @@ -294,10 +325,26 @@ 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. +h2. Categories + +Posts are placed into categories based on the directory structure they are found +within (see above for an example). The categories can be accessed from within +a Liquid template as follows: + +<pre> +{% for post in site.categories.foo %} + <li><span>{{ post.date | date_to_string }}</span> - {{ post.title }}</li> +{% endfor %} +</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. Contribute If you'd like to hack on Jekyll, grab the source from GitHub. To get all of the dependencies, install the gem first. @@ -311,9 +358,27 @@ # Hack away # Do not change the version number, I will do that on my end # If necessary, rebase your commits into logical chunks, without errors # Push the branch up to GitHub # Send me (mojombo) a pull request for your branch + +h2. Blog migrations + +h3. Movable Type + +To migrate your MT blog into Jekyll, you'll need read access to the database. +The lib/jekyll/converters/mt.rb module provides a simple convert to create +.markdown files in a _posts directory based on the entries contained therein. + + $ export DB=my_mtdb + $ export USER=dbuser + $ export PASS=dbpass + $ ruby -r './lib/jekyll/converters/mt' -e 'Jekyll::MT.process( \ + "#{ENV["DB"]}", "#{ENV["USER"]}", "#{ENV["PASS"]}")' + +You may need to adjust the SQL query used to retrieve MT entries. Left alone, +it will attempt to pull all entries across all blogs regardless of status. +Please check the results and verify the posts before publishing. h2. License (The MIT License)