Jekyll Plugins

$ git clone git://github.com/recurser/jekyll-plugins.git

 

About

This is a collection of Jekyll plugins and generators that I’ve written for use on recursive-design.com.

License

The plugins are distributed under the MIT License See the License file for details.

Installation

To install the plugins simply put them in a directory named _plugins in your project directory.

Bug Reports

If you come across any problems, please create a ticket and we’ll try to get it fixed as soon as possible.

Want to make your own plugins?

More information on the Jekyll plugin architecture is available from the Jekyll wiki.

generate_projects.rb

A generator that creates project pages for Jekyll sites from git repositories.

This was inspired by the project pages on GitHub, which use the project README file as the index page. It takes git repositories, and automatically builds project pages for them using the README file, along with downloadable zipped copies of the projects themselves (for example, the project page for this plugin repository is auto-generated with this plugin).

Usage

To use it, simply drop the generateprojects.rb_ script into the _plugins directory of your Jekyll site. Next, create a _projects folder in the base of your Jekyll site. This folder should contain .yml files describing how to build a page for your project. Here is an example _projects/jekyll-plugins.yml):

layout:     default
title:      Jekyll Plugins
repository: git://recursive-design.com/jekyll-plugins.git
published:  true

How it works

When you compile your Jekyll site, the plugin will download the git repository of each project in your _projects folder, create an index page from the README file (using the specified layout), and create a downloadable .zip file of the project. The goal is to automate the construction of online project pages, keep them in sync with README documentation, and provide an up-to-date zip archive for download.

Required files

Your project’s git repository should contain:

  • README : The contents of this will be used as the body of your project page will be created from. Any extension other than .markdown, .textile or .html will be treated as a .textile file.
  • versions.txt : Contains the version string (eg 1.0.0). Used when naming the downloadable zip-file (optional). If the version.txt file is not available, a YYYYMMDDHHMM timestamp will be used for the version instead.

Required gems

  • git (>= 1.2.5)
  • rubyzip (>= 0.9.4)

Available _config.yml settings

  • projectdir_ : The subfolder to compile projects to (default is ‘projects’).

Available YAML settings

  • repository : Git repository of your project (required).
  • layout : Layout to use when creating the project page.
  • title : Project title, which can be accessed in the layout.
  • published : Project won’t be published if this is false.

There is also an optional zipfolder_name_ setting, in case you want the unzipped folder to be named something other than the project name. This is useful (for eaxmple) if you want it to unzip as an OS X ‘Something.app’ application bundle.

generate_categories.rb

A generator that creates category pages for Jekyll sites (for example our plugin category.

Usage

To use it, simply drop the generatecategories.rb_ script into the _plugins directory of your Jekyll site.

You should also copy the category_index.html file to the _layouts directory of your own project. This file is provided as an example layout, and obviously you can change the HTML above as you see fit.

How it works

When you compile your Jekyll site, this plugin will loop through the list of categories in your site, and use the layout above to generate a page for each one with a list of links to the individual posts.

Included filters

  • categorylinks_ : Outputs the list of categories as comma-separated links.
  • dateto_html_string_ : Outputs the post.date as formatted html, with hooks for CSS styling.

Available _config.yml settings

  • categorydir_ : The subfolder to build category pages in (default is ‘categories’).
  • categorytitle_prefix_ : The string used before the category name in the page title (default is ‘Category: ‘).

generate_sitemap.rb

A simple generator that creates a sitemap.xml page for Jekyll sites, suitable for submission to Google etc (for example the sitemap.xml for recursive-design.com.

Usage

To use it, simply drop the generatesitemap.rb_ script into the _plugins directory of your Jekyll site.

How it works

When you compile your Jekyll site, the plugin will loop through the list of pages in your site, and generate an entry in sitemap.xml for each one.

Available YAML settings

  • changefreq : How often this page will change. This setting is optional, but if specified its value must be one of always, hourly, daily, weekly, monthly, yearly, or never. See the sitemap specification for more details on what this is used for. By default, this property is omitted for static pages and never for the files in _posts (since these are typically blog entries or the like).

Change history

  • Version 0.1.8 (2011-08-15) : A bunch of fixes and improvements (thanks bdesham!).
  • Version 0.1.7 (2011-07-19) : Sitemap base URL fix (thanks ojilles!).
  • Version 0.1.6 (2011-05-21) : Added optional zipfolder_name_ YAML config setting.
  • Version 0.1.5 (2011-05-21) : Replace github-style code markup to pygments-compatible ‘highlight’ format.
  • Version 0.1.4 (2011-05-08) : Applied patch to fix permalink problem in generate_sitemap.rb (thanks ejel!).
  • Version 0.1.3 (2011-01-06) : Fixed pygments code formatting bug introduced in generate_projects.rb v0.1.2.
  • Version 0.1.2 (2011-01-06) : Add generated pages to the Site::pages list, to stop them being deleted automatically by Site::cleanup(); Fixed a file extension problem with generateprojects.rb_.
  • Version 0.1.1 (2010-12-10) : Use mtime instead of ctime for sitemap modification dates; Fixed sitemap extension bug.
  • Version 0.1.0 (2010-12-08) : Initial release.

Contributing

Once you’ve made your commits:

  1. Fork jekyll-plugins
  2. Create a topic branch - git checkout -b my_branch
  3. Push to your branch - git push origin my_branch
  4. Create a Pull Request from your branch
  5. That’s it!

Author

Dave Perrett :: mail@recursive-design.com :: @recurser

Copyright

Copyright (c) 2010 Dave Perrett. See License for details.

 
 
If you want to keep up to date on this project, why not subscribe to our feed or follow us on twitter.