README

Octopress plugin to display tag clouds. Based on https://gist.github.com/1577100 by tokkonopapa

Version: 0.4

Getting Started

This won't work without a plugin to generate some tag pages. See https://github.com/robbyedwards/octopress-tag-pages for a plugin to take care of this.

Put tag_cloud.rb in the /plugins folder. Then add {% tag_cloud %} where the tag cloud should appear. A couple of sample files are included to demonstrate basic usage, and several options are provided to control the appearance of the tag cloud.

Usage

Defines a tag_cloud tag that is rendered by Liquid into a tag cloud:

<div class="cloud">
    {% tag_cloud %}
</div>

Available _config.yml settings :

• tag_dir: The subfolder to build tag pages in (default is tags).

The tag cloud itself is a collection of anchor tags, styled dynamically with the font-size CSS property. The range of values, and unit to use for font-size can be specified with a very simple syntax:

{% tag_cloud font-size: 16 - 28px %}

The output is automatically formatted to use the same number of decimal places as used in the argument:

{% tag_cloud font-size: 0.8  - 1.8em  %}  # => 1
{% tag_cloud font-size: 0.80 - 1.80em %}  # => 2

Tags that have been used less than a certain number of times can be filtered out from the tag cloud with the optional threshold parameter:

{% tag_cloud threshold: 2 %}

The ouptput can be limited to a certain number of the most frequently occurring tags when the sort method is alphabetical or frequency; i.e., {% tag_cloud limit: 8 %} => results in a tag cloud with the eight most frequent tags sorted alphabetically.

When the sort method is random then output is randomly sorted and limited to @limit items. Setting the limit parameter to zero (the default) will display all tags.

The output can be sorted in three ways:

{% tag_cloud sort: freq|rand|alpha %}

• freq will sort by the frequency of the tag`s occurrence
• rand will sort randomly each time the cloud is generated
• alpha (the default) will sort the tags in alphabetical order

An optional order parameter can also be set, which will change the sort order:

{% tag_cloud sort: freq|rand|alpha [asc|desc] %}

By default, alphabetical sorts will be asc, and frequency sorts will be desc. The order parameter has no effect on random sorts.

The style parameter provides a basic way to alter the html that is generated by the plugin:

{% tag_cloud style: list|para [{:separator}] %}

• list wraps each anchor tag in an <li> tag for presenting the list as an (un)ordered list. The {% tag_cloud %} block needs to be enclosed in either a <ol> or a <ul> block where it is included in the site's templates. list is the default option. The optional separator will have no effect when the list option is used
• para removes the enclosing <li> tags and separates each item with an optional separator (indicated by :separator above). By default the separator is a comma followed by a space. An alternate separator can be indicated by wrapping the new separator inside curly brackets ({}) following the para option, i.e., {% tag_cloud style: para { — } %}

Multiple parameters can be separated by a comma:

{% tag_cloud font-size: 50 - 150%, threshold: 2 %}

License

Copyright (c) 2012 Robby Edwards, http://robbyedwards.com/ Licensed under the MIT license (http://www.opensource.org/licenses/mit-license.php)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ‘Software’), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.