nanoc3 3.0.0

data/lib/nanoc3/filters.rb

@@ -0,0 +1,37 @@
+# encoding: utf-8
+
+module Nanoc3::Filters
+
+  autoload 'BlueCloth',       'nanoc3/filters/bluecloth'
+  autoload 'CodeRay',         'nanoc3/filters/coderay'
+  autoload 'ERB',             'nanoc3/filters/erb'
+  autoload 'Erubis',          'nanoc3/filters/erubis'
+  autoload 'Haml',            'nanoc3/filters/haml'
+  autoload 'Less',            'nanoc3/filters/less'
+  autoload 'Markaby',         'nanoc3/filters/markaby'
+  autoload 'Maruku',          'nanoc3/filters/maruku'
+  autoload 'Rainpress',       'nanoc3/filters/rainpress'
+  autoload 'RDiscount',       'nanoc3/filters/rdiscount'
+  autoload 'RDoc',            'nanoc3/filters/rdoc'
+  autoload 'RedCloth',        'nanoc3/filters/redcloth'
+  autoload 'RelativizePaths', 'nanoc3/filters/relativize_paths'
+  autoload 'RubyPants',       'nanoc3/filters/rubypants'
+  autoload 'Sass',            'nanoc3/filters/sass'
+
+  Nanoc3::Filter.register '::Nanoc3::Filters::BlueCloth',       :bluecloth
+  Nanoc3::Filter.register '::Nanoc3::Filters::CodeRay',         :coderay
+  Nanoc3::Filter.register '::Nanoc3::Filters::ERB',             :erb
+  Nanoc3::Filter.register '::Nanoc3::Filters::Erubis',          :erubis
+  Nanoc3::Filter.register '::Nanoc3::Filters::Haml',            :haml
+  Nanoc3::Filter.register '::Nanoc3::Filters::Less',            :less
+  Nanoc3::Filter.register '::Nanoc3::Filters::Markaby',         :markaby
+  Nanoc3::Filter.register '::Nanoc3::Filters::Maruku',          :maruku
+  Nanoc3::Filter.register '::Nanoc3::Filters::Rainpress',       :rainpress
+  Nanoc3::Filter.register '::Nanoc3::Filters::RDiscount',       :rdiscount
+  Nanoc3::Filter.register '::Nanoc3::Filters::RDoc',            :rdoc
+  Nanoc3::Filter.register '::Nanoc3::Filters::RedCloth',        :redcloth
+  Nanoc3::Filter.register '::Nanoc3::Filters::RelativizePaths', :relativize_paths
+  Nanoc3::Filter.register '::Nanoc3::Filters::RubyPants',       :rubypants
+  Nanoc3::Filter.register '::Nanoc3::Filters::Sass',            :sass
+
+end

data/lib/nanoc3/helpers/blogging.rb

@@ -0,0 +1,226 @@
+# encoding: utf-8
+
+module Nanoc3::Helpers
+
+  # Nanoc3::Helpers::Blogging provides some 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:
+  #
+  # * 'kind', set to 'article'.
+  #
+  # * 'created_at', set to the creation timestamp.
+  #
+  # 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.
+  #
+  # The two main functions are sorted_articles and atom_feed.
+  #
+  # To activate this helper, +include+ it, like this:
+  #
+  #   include Nanoc3::Helpers::Blogging
+  module Blogging
+
+    # Returns an unsorted list of articles.
+    def articles
+      @items.select { |item| item[:kind] == 'article' }
+    end
+
+    # Returns a list of articles, sorted by descending creation date (so newer
+    # articles appear first).
+    def sorted_articles
+      require 'time'
+      articles.sort_by { |a| Time.parse(a[:created_at]) }.reverse
+    end
+
+    # Returns a string representing the atom feed containing recent articles,
+    # sorted by descending creation date. +params+ is a hash where the
+    # following keys can be set:
+    #
+    # +limit+:: The maximum number of articles to show. Defaults to 5.
+    #
+    # +articles+:: A list of articles to include in the feed. Defaults to the
+    #              list of articles returned by the articles function.
+    #
+    # +content_proc+:: A proc that returns the content of the given article,
+    #                  passed as a parameter. By default, given the argument
+    #                  +article+, this proc will return
+    #                  +article.reps[0].content+. This function may not return
+    #                  nil.
+    #
+    # +excerpt_proc+:: A proc that returns the excerpt of the given article,
+    #                  passed as a parameter. By default, given the argument
+    #                  +article+, this proc will return +article.excerpt+.
+    #                  This function may return nil.
+    #
+    # The following attributes must be set on blog articles:
+    #
+    # * 'title', containing the title of the blog post.
+    #
+    # * all other attributes mentioned above.
+    #
+    # The following attributes can optionally be set on blog articles to
+    # change the behaviour of the Atom feed:
+    #
+    # * 'excerpt', containing an excerpt of the article, usually only a few
+    #   lines long.
+    #
+    # * 'custom_path_in_feed', containing the path that will be used instead
+    #   of the normal path in the feed. This can be useful when including
+    #   non-outputted items in a feed; such items could have their custom feed
+    #   path set to the blog path instead, for example.
+    #
+    # The feed will also include dates on which the articles were updated.
+    # These are generated automatically; the way this happens depends on the
+    # used data source (the filesystem data source checks the file mtimes, for
+    # instance).
+    #
+    # The site configuration will need to have the following attributes:
+    #
+    # * 'base_url', containing the URL to the site, without trailing slash.
+    #   For example, if the site is at "http://example.com/", the base_url
+    #   would be "http://example.com".
+    #
+    # The feed item will need to have the following attributes:
+    #
+    # * 'title', containing the title of the feed, which is usually also the
+    #   title of the blog.
+    #
+    # * 'author_name', containing the name of the item's author. This will
+    #   likely be a global attribute, unless the site is managed by several
+    #   people/
+    #
+    # * 'author_uri', containing the URI for the item's author, such as the
+    #   author's web site URL. This will also likely be a global attribute.
+    #
+    # The feed item can have the following optional attributes:
+    #
+    # * 'feed_url', containing the custom URL of the feed. This can be useful
+    #   when the private feed URL shouldn't be exposed; for example, when
+    #   using FeedBurner this would be set to the public FeedBurner URL.
+    #
+    # To construct a feed, create a blank item with no layout, only the 'erb'
+    # (or 'erubis') filter, and an 'xml' extension. It may also be useful to
+    # set 'is_hidden' to true, so that helpers such as the sitemap helper will
+    # ignore the item. The content of the feed item should be:
+    #
+    #   <%= atom_feed %>
+    def atom_feed(params={})
+      require 'builder'
+      require 'time'
+
+      # Extract parameters
+      limit             = params[:limit] || 5
+      relevant_articles = params[:articles] || articles || []
+      content_proc      = params[:content_proc] || lambda { |a| a.reps[0].content_at_snapshot(:pre) }
+      excerpt_proc      = params[:excerpt_proc] || lambda { |a| a[:excerpt] }
+
+      # Check config attributes
+      if @site.config[:base_url].nil?
+        raise RuntimeError.new('Cannot build Atom feed: site configuration has no base_url')
+      end
+
+      # Check feed item attributes
+      if @item[:title].nil?
+        raise RuntimeError.new('Cannot build Atom feed: feed item has no title')
+      end
+      if @item[:author_name].nil?
+        raise RuntimeError.new('Cannot build Atom feed: feed item has no author_name')
+      end
+      if @item[:author_uri].nil?
+        raise RuntimeError.new('Cannot build Atom feed: feed item has no author_uri')
+      end
+
+      # Check article attributes
+      if relevant_articles.empty?
+        raise RuntimeError.new('Cannot build Atom feed: no articles')
+      end
+      if relevant_articles.any? { |a| a[:created_at].nil? }
+        raise RuntimeError.new('Cannot build Atom feed: one or more articles lack created_at')
+      end
+
+      # Get sorted relevant articles
+      sorted_relevant_articles = relevant_articles.sort_by { |a| Time.parse(a[:created_at]) }.reverse.first(limit)
+
+      # Get most recent article
+      last_article = sorted_relevant_articles.first
+
+      # Create builder
+      buffer = ''
+      xml = Builder::XmlMarkup.new(:target => buffer, :indent => 2)
+
+      # Build feed
+      xml.instruct!
+      xml.feed(:xmlns => 'http://www.w3.org/2005/Atom') do
+        # Add primary attributes
+        xml.id      @site.config[:base_url] + '/'
+        xml.title   @item[:title]
+
+        # Add date
+        xml.updated Time.parse(last_article[:created_at]).to_iso8601_time
+
+        # Add links
+        xml.link(:rel => 'alternate', :href => @site.config[:base_url])
+        xml.link(:rel => 'self',      :href => feed_url)
+
+        # Add author information
+        xml.author do
+          xml.name  @item[:author_name]
+          xml.uri   @item[:author_uri]
+        end
+
+        # Add articles
+        sorted_relevant_articles.each do |a|
+          xml.entry do
+            # Add primary attributes
+            xml.id        atom_tag_for(a)
+            xml.title     a[:title], :type => 'html'
+
+            # Add dates
+            xml.published Time.parse(a[:created_at]).to_iso8601_time
+            xml.updated   a.mtime.to_iso8601_time
+
+            # Add link
+            xml.link(:rel => 'alternate', :href => url_for(a))
+
+            # Add content
+            summary = excerpt_proc.call(a)
+            xml.content   content_proc.call(a), :type => 'html'
+            xml.summary   summary, :type => 'html' unless summary.nil?
+          end
+        end
+      end
+
+      buffer
+    end
+
+    # 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.
+    def url_for(item)
+      @site.config[:base_url] + (item[:custom_path_in_feed] || item.reps[0].path)
+    end
+
+    # Returns the URL of the feed. It will return the custom feed URL if set,
+    # or otherwise the normal feed URL.
+    def feed_url
+      @item[:feed_url] || @site.config[:base_url] + @item.reps[0].path
+    end
+
+    # 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 in this blog post:
+    # http://diveintomark.org/archives/2004/05/28/howto-atom-id.
+    def atom_tag_for(item)
+      require 'time'
+
+      hostname        = @site.config[:base_url].sub(/.*:\/\/(.+?)\/?$/, '\1')
+      formatted_date  = Time.parse(item[:created_at]).to_iso8601_date
+
+      'tag:' + hostname + ',' + formatted_date + ':' + (item.reps[0].path || item.identifier)
+    end
+
+  end
+
+end

data/lib/nanoc3/helpers/breadcrumbs.rb

@@ -0,0 +1,25 @@
+# encoding: utf-8
+
+module Nanoc3::Helpers
+
+  # Nanoc3::Helpers::Breadcrumbs provides support for breadcrumbs, which allow
+  # the user to go up in the page hierarchy.
+  module Breadcrumbs
+
+    # Returns the breadcrumbs trail as an array. Higher items (items that are
+    # closer to the root) come before lower items.
+    def breadcrumbs_trail
+      trail = [] 
+      item = @item 
+
+      begin
+        trail.unshift(item) 
+        item = item.parent 
+      end until item.nil?
+
+      trail
+    end
+
+  end
+
+end

data/lib/nanoc3/helpers/capturing.rb

@@ -0,0 +1,71 @@
+# encoding: utf-8
+
+module Nanoc3::Helpers
+
+  # Nanoc3::Helpers::Capturing provides a content_for method, which allows
+  # content to be "captured" on one item and reused elsewhere.
+  #
+  # = Example
+  #
+  # For example, suppose you want the sidebar of your site to contain a short
+  # summary of the item. You could put the summary in the meta file, but
+  # that’s not possible when the summary contains eRuby. You could also put
+  # the sidebar inside the actual item, but that’s not very pretty. Instead,
+  # you write the summary on the item itself, but capture it, and print it in
+  # the sidebar layout.
+  #
+  # Captured content becomes part of the item. For example, a sidebar layout
+  # could look like this:
+  #
+  #   <div id="sidebar">
+  #     <h3>Summary</h3>
+  #     <%= @item[:content_for_summary] || '(no summary)' %>
+  #   </div>
+  #
+  # To put something inside that content_for_summary variable, capture it
+  # using the content_for function. In the about item, for example:
+  #
+  #   <% content_for :summary do %>
+  #     <p>On this item, nanoc is introduced, blah blah.</p>
+  #   <% end %>
+  #
+  # When the site is compiled, the sidebar of the about item will say “On
+  # this item, the purpose of nanoc is described, blah blah blah,” as
+  # expected.
+  #
+  # This helper likely only works with ERB (and perhaps Erubis).
+  #
+  # To activate this helper, +include+ it, like this:
+  #
+  #   include Nanoc3::Helpers::Capturing
+  module Capturing
+
+    # Captures the content inside the block into a item attribute named
+    # "content_for_" followed by the given name. The content of the block
+    # itself will not be outputted.
+    def content_for(name, &block)
+      eval("@item[:content_for_#{name.to_s}] = capture(&block)")
+    end
+
+    # Evaluates the given block and returns the result. The block is not outputted.
+    def capture(*args, &block)
+      # Get erbout so far
+      erbout = eval('_erbout', block.binding)
+      erbout_length = erbout.length
+
+      # Execute block
+      block.call(*args)
+
+      # Get new piece of erbout
+      erbout_addition = erbout[erbout_length..-1]
+
+      # Remove addition
+      erbout[erbout_length..-1] = ''
+
+      # Done
+      erbout_addition
+    end
+
+  end
+
+end

data/lib/nanoc3/helpers/filtering.rb

@@ -0,0 +1,46 @@
+# encoding: utf-8
+
+module Nanoc3::Helpers
+
+  # Nanoc3::Helpers::Filtering provides a filter method, which allows parts of
+  # an item to be filtered.
+  #
+  # For example, the following piece of code only runs the "rubypants" filter
+  # on the second paragraph:
+  #
+  #   <p>Lorem ipsum dolor sit amet...</p>
+  #   <% filter :rubypants do %>
+  #     <p>Consectetur adipisicing elit...</p>
+  #   <% end %>
+  #
+  # This helper likely only works with ERB (and perhaps Erubis).
+  #
+  # To activate this helper, +include+ it, like this:
+  #
+  #   include Nanoc3::Helpers::Filtering
+  module Filtering
+
+    require 'nanoc3/helpers/capturing'
+    include Nanoc3::Helpers::Capturing
+
+    # Filters the content in the given block and outputs it.
+    def filter(filter_name, arguments={}, &block)
+      # Capture block
+      data = capture(&block)
+
+      # Find filter
+      klass = Nanoc3::Filter.named(filter_name)
+      raise Nanoc3::Errors::UnknownFilter.new(filter_name) if klass.nil?
+      filter = klass.new(@item_rep.assigns)
+
+      # Filter captured data
+      filtered_data = filter.run(data, arguments)
+
+      # Append filtered data to buffer
+      buffer = eval('_erbout', block.binding)
+      buffer << filtered_data
+    end
+
+  end
+
+end

data/lib/nanoc3/helpers/html_escape.rb

@@ -0,0 +1,22 @@
+# encoding: utf-8
+
+module Nanoc3::Helpers
+
+  # Nanoc3::Helpers::HTMLEscape contains functionality for HTML-escaping
+  # strings.
+  module HTMLEscape
+
+    # Returns the HTML-escaped representation of the given string. Only &, <,
+    # > and " are escaped.
+    def html_escape(string)
+      string.gsub('&', '&amp;').
+             gsub('<', '&lt;').
+             gsub('>', '&gt;').
+             gsub('"', '&quot;')
+    end
+
+    alias h html_escape
+
+  end
+
+end

data/lib/nanoc3/helpers/link_to.rb

@@ -0,0 +1,120 @@
+# encoding: utf-8
+
+module Nanoc3::Helpers
+
+  # Nanoc3::Helpers::LinkTo contains functions for linking to items.
+  #
+  # To activate this helper, +include+ it, like this:
+  #
+  #   include Nanoc3::Helpers::LinkTo
+  module LinkTo
+
+    require 'nanoc3/helpers/html_escape'
+    include Nanoc3::Helpers::HTMLEscape
+
+    # Creates a HTML link to the given path or item representation, and with
+    # the given text.
+    #
+    # +path_or_rep+:: the URL or path (a String) that should be linked to, or
+    #                 the item representation that should be linked to.
+    #
+    # +text+:: the visible link text.
+    #
+    # +attributes+:: a hash containing HTML attributes that will be added to
+    #                the link.
+    #
+    # Examples:
+    #
+    #   link_to('Blog', '/blog/')
+    #   # => '<a href="/blog/">Blog</a>'
+    #
+    #   item_rep = @items.find { |i| i.item_id == 'special' }.reps[0]
+    #   link_to('Special Item', item_rep)
+    #   # => '<a href="/special_item/">Special Item</a>'
+    #
+    #   link_to('Blog', '/blog/', :title => 'My super cool blog')
+    #   # => '<a href="/blog/" title="My super cool blog">Blog</a>
+    def link_to(text, path_or_rep, attributes={})
+      # Find path
+      path = path_or_rep.is_a?(String) ? path_or_rep : path_or_rep.path
+
+      # Join attributes
+      attributes = attributes.inject('') do |memo, (key, value)|
+        memo + key.to_s + '="' + h(value) + '" '
+      end
+
+      # Create link
+      "<a #{attributes}href=\"#{path}\">#{text}</a>"
+    end
+
+    # Creates a HTML link using link_to, except when the linked item is the
+    # current one. In this case, a span element with class "active" and with
+    # the given text will be returned.
+    #
+    # Examples:
+    #
+    #   link_to_unless_current('Blog', '/blog/')
+    #   # => '<a href="/blog/">Blog</a>'
+    #
+    #   link_to_unless_current('This Item', @item_rep)
+    #   # => '<span class="active">This Item</span>'
+    def link_to_unless_current(text, path_or_rep, attributes={})
+      # Find path
+      path = path_or_rep.is_a?(String) ? path_or_rep : path_or_rep.path
+
+      if @item_rep and @item_rep.path == path
+        # Create message
+        "<span class=\"active\" title=\"You're here.\">#{text}</span>"
+      else
+        link_to(text, path_or_rep, attributes)
+      end
+    end
+
+    # Returns the relative path from the current item to the given path or
+    # item representation.
+    #
+    # +path_or_rep+:: the URL or path (a String) to where the relative should
+    #                 point, or the item representation to which the relative
+    #                 should point.
+    #
+    # Example:
+    #
+    #   # if the current item's path is /foo/bar/
+    #   relative_path('/foo/qux/')
+    #   # => '../qux/'
+    def relative_path_to(target)
+      require 'pathname'
+
+      # Find path
+      if target.is_a?(String)
+        path = target
+      elsif target.respond_to?(:reps)
+        path = target.reps.find { |r| r.name == :default }.path
+      else
+        path = target.path
+      end
+
+      # Get source and destination paths
+      dst_path   = Pathname.new(path)
+      src_path   = Pathname.new(@item_rep.path)
+
+      # Calculate elative path (method depends on whether destination is a
+      # directory or not).
+      if src_path.to_s[-1,1] != '/'
+        relative_path = dst_path.relative_path_from(src_path.dirname).to_s
+      else
+        relative_path = dst_path.relative_path_from(src_path).to_s
+      end
+
+      # Add trailing slash if necessary
+      if dst_path.to_s[-1,1] == '/'
+        relative_path += '/'
+      end
+
+      # Done
+      relative_path
+    end
+
+  end
+
+end

data/lib/nanoc3/helpers/rendering.rb

@@ -0,0 +1,76 @@
+# encoding: utf-8
+
+module Nanoc3::Helpers
+
+  # Nanoc3::Helpers::Rendering provides functionality for rendering layouts as
+  # partials.
+  module Rendering
+
+    include Nanoc3::Helpers::Capturing
+
+    # Returns a string containing the rendered given layout.
+    #
+    # +identifier+:: the identifier of the layout that should be rendered.
+    #
+    # +other_assigns+:: a hash containing assigns that will be made available
+    #                   as instance variables.
+    #
+    # Example 1: a layout 'head' with content "HEAD" and a layout 'foot' with
+    # content "FOOT":
+    #
+    #   <%= render 'head' %> - MIDDLE - <%= render 'foot' %>
+    #   # => "HEAD - MIDDLE - FOOT" 
+    #
+    # Example 2: a layout named 'head' with content "<h1><%= @title %></h1>":
+    #
+    #   <%= render 'head', :title => 'Foo' %>
+    #   # => "<h1>Foo</h1>"
+    def render(identifier, other_assigns={}, &block)
+      # Find layout
+      layout = @site.layouts.find { |l| l.identifier == identifier.cleaned_identifier }
+      raise Nanoc3::Errors::UnknownLayout.new(identifier.cleaned_identifier) if layout.nil?
+
+      # Capture content, if any
+      captured_content = block_given? ? capture(&block) : nil
+
+      # Get assigns
+      assigns = {
+        :content    => captured_content,
+        :item       => @item,
+        :item_rep   => @item_rep,
+        :items      => @items,
+        :layout     => layout,
+        :layouts    => @layouts,
+        :config     => @config,
+        :site       => @site
+      }.merge(other_assigns)
+
+      # Get filter name
+      filter_name, filter_args = @site.compiler.filter_for_layout(layout)
+      raise Nanoc3::Errors::CannotDetermineFilter.new(layout.identifier) if filter_name.nil?
+
+      # Get filter class
+      filter_class = Nanoc3::Filter.named(filter_name)
+      raise Nanoc3::Errors::UnknownFilter.new(filter_name) if filter_class.nil?
+
+      # Create filter
+      filter = filter_class.new(assigns)
+
+      # Layout
+      @site.compiler.stack.push(layout)
+      result = filter.run(layout.raw_content, filter_args)
+      @site.compiler.stack.pop
+
+      # Append to erbout if we have a block
+      if block_given?
+        erbout = eval('_erbout', block.binding)
+        erbout << result
+      end
+
+      # Done
+      result
+    end
+
+  end
+
+end

data/lib/nanoc3/helpers/tagging.rb

@@ -0,0 +1,58 @@
+# encoding: utf-8
+
+module Nanoc3::Helpers
+
+  # Nanoc3::Helpers::Tagging provides some support for managing tags added to
+  # items. To add tags to items, set the +tags+ attribute to an array of
+  # tags that should be applied to the item. For example:
+  #
+  #   tags: [ 'foo', 'bar', 'baz' ]
+  #
+  # To activate this helper, +include+ it, like this:
+  #
+  #   include Nanoc3::Helpers::Tagging
+  module Tagging
+
+    # Returns a formatted list of tags for the given item as a string. Several
+    # parameters allow customization:
+    #
+    # :base_url:: The URL to which the tag will be appended to construct the
+    #             link URL. This URL must have a trailing slash. Defaults to
+    #             "http://technorati.com/tag/".
+    #
+    # :none_text:: The text to display when the item has no tags. Defaults to
+    #              "(none)".
+    #
+    # :separator:: The separator to put between tags. Defaults to ", ".
+    def tags_for(item, params={})
+      base_url  = params[:base_url]  || 'http://technorati.com/tag/'
+      none_text = params[:none_text] || '(none)'
+      separator = params[:separator] || ', '
+
+      if item[:tags].nil? or item[:tags].empty?
+        none_text
+      else
+        item[:tags].map { |tag| link_for_tag(tag, base_url) }.join(separator)
+      end
+    end
+
+    # Returns all items with the given tag.
+    def items_with_tag(tag)
+      @items.select { |i| (i[:tags] || []).include?(tag) }
+    end
+
+    # Returns a link to to the specified tag. The link is marked up using the
+    # rel-tag microformat.
+    #
+    # +tag+:: The name of the tag, which should consist of letters and numbers
+    #         (no spaces, slashes, or other special characters).
+    #
+    # +base_url+:: The URL to which the tag will be appended to construct the
+    #              link URL. This URL must have a trailing slash.
+    def link_for_tag(tag, base_url)
+      %[<a href="#{base_url}#{tag}" rel="tag">#{tag}</a>]
+    end
+
+  end
+
+end