Module | Nanoc::Helpers::Blogging |
In: |
lib/nanoc/helpers/blogging.rb
|
Provides functionality for building blogs, such as finding articles and constructing feeds.
This helper has a few requirements. First, all blog articles should have the following attributes:
Some functions in this blogging helper, such as the {atom_feed} function, require additional attributes to be set; these attributes are described in the documentation for these functions.
All "time" item attributes, site configuration attributes or method parameters can either be a `Time` instance or a string in any format parseable by `Time.parse`.
The two main functions are {sorted_articles} and {atom_feed}.
Returns a string representing the atom feed containing recent articles, sorted by descending creation date.
The following attributes must be set on blog articles:
The following attributes can optionally be set on blog articles to change the behaviour of the Atom feed:
The site configuration will need to have the following attributes:
The feed item will need to know about the feed title, the feed author name, and the URI corresponding to the author. These can be specified using parameters, as attributes in the feed item, or in the site configuration.
The feed item can have the following optional attributes:
To construct a feed, create a new item and make sure that it is filtered with `:erb` or `:erubis`; it should not be laid out. Ensure that it is routed to the proper path, e.g. `/blog.xml`. It may also be useful to set the `is_hidden` attribute to true, so that helpers such as the sitemap helper will ignore the item. The content of the feed item should be `<%= atom_feed %>`.
@example Defining compilation and routing rules for a feed item
compile '/blog/feed/' do filter :erb end route '/blog/feed/' do '/blog.xml' end
@example Limiting the number of items in a feed
<%= atom_feed :limit => 5 %>
@option params [Number] :limit (5) The maximum number of articles to
show
@option params [Array] :articles (sorted_articles) A list of articles to
include in the feed
@option params [Proc] :content_proc (->{ |article|
article.compiled_content(:snapshot => :pre) }) A proc that returns the content of the given article, which is passed as a parameter. This function may not return nil.
@option params [proc] :excerpt_proc (->{ |article| article[:excerpt] })
A proc that returns the excerpt of the given article, passed as a parameter. This function should return nil if there is no excerpt.
@option params [String] :title The feed‘s title, if it is not given in
the item attributes.
@option params [String] :author_name The name of the feed‘s author, if
it is not given in the item attributes.
@option params [String] :author_uri The URI of the feed‘s author, if it
is not given in the item attributes.
@option params [String] :icon The URI of the feed‘s icon.
@option params [String] :logo The URI of the feed‘s logo.
@return [String] The generated feed content
Returns an URI containing an unique ID for the given item. This will be used in the Atom feed to uniquely identify articles. These IDs are created using a procedure suggested by Mark Pilgrim and described in his ["How to make a good ID in Atom" blog post] (web.archive.org/web/20110915110202/http://diveintomark.org/archives/2004/05/28/howto-atom-id).
@param [Nanoc::Item] item The item for which to create an atom tag
@return [String] The atom tag for the given item
Returns the URL of the feed. It will return the custom feed URL if set, or otherwise the normal feed URL.
@return [String] The URL of the feed
Returns the URL for the given item. It will return the URL containing the custom path in the feed if possible, otherwise the normal path.
@param [Nanoc::Item] item The item for which to fetch the URL.
@return [String] The URL of the given item