/jekyll-plugins

A collection of Jekyll plugins and generators that I've written for recursive-design.com

Primary LanguageRubyMIT LicenseMIT

About

This is a collection of Jekyll plugins and generators that I've written for use on daveperrett.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 generate_projects.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://daveperrett.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

  • project_dir : 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 zip_folder_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 generate_categories.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 as you see fit.

You can also (optionally) generate an atom.xml feed for each category. To do this, copy the category_feed.xml file to the _includes/custom directory of your own project. You'll also need to copy the octopress_filters.rb file into the _plugins directory of your project, as the category_feed.xml requires a couple of extra filters.

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

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

Available _config.yml settings

  • category_dir : The subfolder to build category pages in (default is 'categories').
  • category_title_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 daveperrett.com.

Usage

To use it, simply drop the generate_sitemap.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.2.1 (2012-10-15) : Merged some updates from Octopress back in.
    • Add support for atom.xml feed generation for categories.
    • Improved handling of multibyte and multi-word category names in URLs.
  • Version 0.2.0 (2012-10-14) :
    • Add support for priority in generate_sitemap.rb (thanks hez!).
    • Remove hard-coded category directory in generate_categories.rb (thanks ghinda and MrWerewolf!).
    • Improved slash handling in generate_sitemap.rb.
  • 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 zip_folder_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 generate_projects.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 :: hello@daveperrett.com :: @daveperrett

Copyright

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