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

- old
+ new

@@ -32,11 +32,11 @@ fields such as <code>title</code> and <code>date</code>. 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 +Each post's filename contains (by default) 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 @@ -143,10 +143,21 @@ can launch a simple WEBrick server (works well in conjunction with --auto). Default port is 4000: $ jekyll --server [PORT] +By default, the permalink for each post begins with its date in 'YYYY/MM/DD' +format. If you do not wish to have the date appear in the URL of each post, +you can change the permalink style to 'none' so that only the 'slug' part of +the filename is used. For example, with the permalink style set to 'none' the +file '2009-01-01-happy-new-year.markdown' will have a permalink like +'http://yoursite.com/happy-new-year.html'. The date of the post will still be +read from the filename (and is required!) to be used elsewhere in Jekyll. +Example usage: + + $ jekyll --permalink none + 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 @@ -284,10 +295,20 @@ becomes 1337 +h3. Array to Sentence String + +Convert an array into a sentence. + + {{ page.tags | array_to_sentence_string }} + +becomes + + foo, bar, and baz + 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. @@ -319,21 +340,37 @@ The argument to <code>highlight</code> is the language identifier. To find the appropriate identifier to use for your favorite language, look for the "short name" on the "Lexers":http://pygments.org/docs/lexers/ page. +There is a second argument to <code>highlight</code> called +<code>linenos</code> that is optional. Including the <code>linenos</code> +argument will force the highlighted code to include line numbers. For +instance, the following code block would include line numbers next to each +line: + +<pre> +{% highlight ruby linenos %} +def foo + puts 'foo' +end +{% endhighlight %} +</pre> + 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. +own site. If you use linenos, you might want to include an additional CSS +class definition for <code>lineno</code> in syntax.css to distinguish the line +numbers from the highlighted code. 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: +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 %} @@ -341,28 +378,10 @@ 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. - - $ git clone git://github.com/mojombo/jekyll - -The best way to get your changes merged back into core is as follows: - -# Fork mojombo/jekyll on GitHub -# Clone down your fork -# Create a topic branch to contain your change -# 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. @@ -376,9 +395,60 @@ "#{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. + +h3. Typo 4+ + +To migrate your Typo blog into Jekyll, you'll need read access to the MySQL +database. The lib/jekyll/converters/typo.rb module provides a simple convert +to create .html, .textile, or .markdown files in a _posts directory based on +the entries contained therein. + + $ export DB=my_typo_db + $ export USER=dbuser + $ export PASS=dbpass + $ ruby -r './lib/jekyll/converters/typo' -e 'Jekyll::Typo.process( \ + "#{ENV["DB"]}", "#{ENV["USER"]}", "#{ENV["PASS"]}")' + +You may need to adjust the code used to filter Typo entries. Left alone, +it will attempt to pull all entries across all blogs that were published. +This code also has only been tested with Typo version 4+. Previous versions +of Typo may not convert correctly. Please check the results and verify the +posts before publishing. + +h3. TextPattern 4 + +To migrate your TextPattern blog into Jekyll, you'll need read access to the MySQL +database. The lib/jekyll/converters/textpattern.rb module provides a simple convert to create .textile files in a _posts directory based on +the entries contained therein. + + $ ruby -r './lib/jekyll/converters/textpattern' -e 'Jekyll::TextPattern.process( \ + "database_name", "username", "password", "hostname")' + +The hostname defaults to _localhost_, all other variables are needed +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. + +h2. Contribute + +If you'd like to hack on Jekyll, start by forking my repo on GitHub: + +http://github.com/mojombo/jekyll + +To get all of the dependencies, install the gem first. The best way to get +your changes merged back into core is as follows: + +# Clone down your fork +# Create a topic branch to contain your change +# Hack away +# Add tests and make sure everything still passes by running `rake` +# If you are adding new functionality, document it in README.textile +# 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. License (The MIT License)