nanoc 2.0 → 2.1

data/lib/nanoc/filters/old.rb

@@ -0,0 +1,19 @@
+module Nanoc::Filters
+  class Old < Nanoc::Filter
+
+    identifiers :eruby, :markdown, :smartypants, :textile
+
+    def run(content)
+      raise Nanoc::Error.new(
+        "The 'eruby', markdown', 'smartypants' and 'textile' filters no " +
+        "longer exist. Instead, use the following filters:\n" +
+        "\n" +
+        "* for Markdown:      bluecloth, rdiscount, redcloth\n" +
+        "* for Textile:       redcloth\n" +
+        "* for embedded Ruby: erb, erubis\n" +
+        "* for Smartypants:   rubypants"
+      )
+    end
+
+  end
+end

data/lib/nanoc/filters/rdiscount.rb

@@ -0,0 +1,13 @@
+module Nanoc::Filters
+  class RDiscount < Nanoc::Filter
+
+    identifiers :rdiscount
+
+    def run(content)
+      require 'rdiscount'
+
+      ::RDiscount.new(content).to_html
+    end
+
+  end
+end

data/lib/nanoc/filters/rdoc.rb

@@ -1,12 +1,13 @@
-module Nanoc::Filter::RDoc
-  class RDocFilter < Nanoc::Filter
+module Nanoc::Filters
+  class RDoc < Nanoc::Filter
 
     identifiers :rdoc
 
     def run(content)
-      nanoc_require 'rdoc/markup/simple_markup'
-      nanoc_require 'rdoc/markup/simple_markup/to_html'
+      require 'rdoc/markup/simple_markup'
+      require 'rdoc/markup/simple_markup/to_html'
 
+      # Get result
       ::SM::SimpleMarkup.new.convert(content, SM::ToHtml.new)
     end
 

data/lib/nanoc/filters/redcloth.rb

@@ -0,0 +1,14 @@
+module Nanoc::Filters
+  class RedCloth < Nanoc::Filter
+
+    identifiers :redcloth
+
+    def run(content)
+      require 'redcloth'
+
+      # Get result
+      ::RedCloth.new(content).to_html
+    end
+
+  end
+end

data/lib/nanoc/filters/rubypants.rb

@@ -0,0 +1,14 @@
+module Nanoc::Filters
+  class SmartyPants < Nanoc::Filter
+
+    identifiers :rubypants
+
+    def run(content)
+      require 'rubypants'
+
+      # Get result
+      ::RubyPants.new(content).to_html
+    end
+
+  end
+end

data/lib/nanoc/filters/sass.rb

@@ -0,0 +1,13 @@
+module Nanoc::Filters
+  class Sass < Nanoc::Filter
+
+    identifiers :sass
+
+    def run(content)
+      require 'sass'
+
+      ::Sass::Engine.new(content).render
+    end
+
+  end
+end

data/lib/nanoc/helpers/blogging.rb

@@ -0,0 +1,170 @@
+module Nanoc::Helpers
+
+  # Nanoc::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.
+  module Blogging
+
+    # Returns the list of articles, sorted by descending creation date (so
+    # newer articles appear first).
+    def sorted_articles
+      @pages.select do |page|
+        page.kind == 'article'
+      end.sort do |x,y|
+        y.created_at <=> x.created_at
+      end
+    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.
+    #
+    # 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 pages in a feed; such pages 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 feed page 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". It is probably a good idea to define
+    #   this in the page defaults, i.e. the 'meta.yaml' file (at least if the
+    #   filesystem data source is being used, which is probably the case).
+    #
+    # * 'title', containing the title of the feed, which is usually also the
+    #   title of the blog.
+    #
+    # * 'author_name', containing the name of the page's author. This will
+    #   likely be a global attribute, unless the site is managed by several
+    #   people/
+    #
+    # * 'author_uri', containing the URI for the page's author, such as the
+    #   author's web site URL. This will also likely be a global attribute.
+    #
+    # The feed page 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 page 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 page. The content of the feed page should be:
+    #
+    #   <%= atom_feed %>
+    def atom_feed(params={})
+      require 'builder'
+
+      # Extract parameters
+      limit = params[:limit] || 5
+
+      # Get most recent article
+      last_article = sorted_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      @page.base_url + '/'
+        xml.title   @page.title
+
+        # Add date
+        xml.updated last_article.created_at.to_iso8601_time
+
+        # Add links
+        xml.link(:rel => 'alternate', :href => @page.base_url)
+        xml.link(:rel => 'self',      :href => feed_url)
+
+        # Add author information
+        xml.author do
+          xml.name  @page.author_name
+          xml.uri   @page.author_uri
+        end
+
+        # Add articles
+        sorted_articles.first(limit).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 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
+            xml.content   a.content, :type => 'html'
+            xml.summary   a.excerpt, :type => 'html' unless a.excerpt.nil?
+          end
+        end
+      end
+
+      buffer
+    end
+
+    # Returns the URL for the given page. It will return the URL containing
+    # the custom path in the feed if possible, otherwise the normal path.
+    def url_for(page)
+      @page.base_url + (page.custom_path_in_feed || page.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
+      @page[:feed_url] || @page.base_url + @page.path
+    end
+
+    # Returns an URI containing an unique ID for the given page. 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(page)
+      hostname        = @page.base_url.sub(/.*:\/\/(.+?)\/?$/, '\1')
+      formatted_date  = page.created_at.to_iso8601_date
+
+      'tag:' + hostname + ',' + formatted_date + ':' + page.path
+    end
+
+  end
+
+end

data/lib/nanoc/helpers/capturing.rb

@@ -0,0 +1,59 @@
+module Nanoc::Helpers
+
+  # Nanoc::Helpers::Capturing provides a content_for method, which allows
+  # content to be "captured" on one page and reused elsewhere.
+  #
+  # = Example
+  #
+  # For example, suppose you want the sidebar of your site to contain a short
+  # summary of the page. 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 page, but that’s not very pretty. Instead,
+  # you write the summary on the page itself, but capture it, and print it in
+  # the sidebar layout.
+  #
+  # Captured content becomes part of the page. For example, a sidebar layout
+  # could look like this:
+  #
+  #   <div id="sidebar">
+  #     <h3>Summary</h3>
+  #     <%= @page.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 page, for example:
+  #
+  #   <% content_for :summary do %>
+  #     <p>On this page, nanoc is introduced, blah blah.</p>
+  #   <% end %>
+  #
+  # When the site is compiled, the sidebar of the about page will say “On
+  # this page, the purpose of nanoc is described, blah blah blah,” as
+  # expected.
+  module Capturing
+
+    # Captures the content inside the block into a page 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("@page[:content_for_#{name.to_s}] = capture(&block)")
+    end
+
+  private
+
+    def capture(*args, &block)
+      buffer = eval('_erbout', block.binding)
+
+      pos = buffer.length
+      block.call(*args)
+
+      data = buffer[pos..-1]
+
+      buffer[pos..-1] = ''
+
+      data
+    end
+
+  end
+
+end

data/lib/nanoc/helpers/html_escape.rb

@@ -0,0 +1,23 @@
+module Nanoc::Helpers
+
+  # Nanoc::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
+
+# Include by default
+include Nanoc::Helpers::HTMLEscape

data/lib/nanoc/helpers/link_to.rb

@@ -0,0 +1,69 @@
+module Nanoc::Helpers
+
+  # Nanoc::Helpers::LinkTo contains functions for linking to pages.
+  module LinkTo
+
+    include Nanoc::Helpers::HTMLEscape
+
+    # Creates a HTML link to the given path or page/asset representation, and
+    # with the given text.
+    #
+    # +path_or_rep+:: the URL or path (a String) that should be linked to, or
+    #                 the page or asset 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>'
+    #
+    #   page_rep = @pages.find { |p| p.page_id == 'special' }.reps(:default)
+    #   link_to('Special Page', page_rep)
+    #   # => '<a href="/special_page/">Special Page</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 page is the
+    # current one. In this case, a span element with class "active" and with
+    # the given text will be returned.
+    #
+    # Examples:
+    #
+    #   link_to('Blog', '/blog/')
+    #   # => '<a href="/blog/">Blog</a>'
+    #
+    #   link_to('This Page', @page_rep)
+    #   # => '<span class="active">This Page</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 @page_rep and @page_rep.path == path
+        # Create message
+        "<span class=\"active\" title=\"You're here.\">#{text}</span>"
+      else
+        link_to(text, path_or_rep, attributes)
+      end
+    end
+
+  end
+
+end

data/lib/nanoc/helpers/render.rb

@@ -0,0 +1,47 @@
+module Nanoc::Helpers
+
+  # Nanoc::Helpers::Render provides functionality for rendering layouts as
+  # partials.
+  module Render
+
+    # Returns a string containing the rendered given layout.
+    #
+    # +name_or_path+:: the name or the path 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(name_or_path, other_assigns={})
+      # Find layout
+      layout = @_obj.site.layouts.find { |l| l.path == name_or_path.cleaned_path }
+      raise Nanoc::Errors::UnknownLayoutError.new(name_or_path.cleaned_path) if layout.nil?
+
+      # Find filter
+      klass = layout.filter_class
+      raise Nanoc::Errors::CannotDetermineFilterError.new(layout.path) if klass.nil?
+      filter = klass.new(@_obj_rep, other_assigns)
+
+      # Layout
+      @_obj.site.compiler.stack.push(layout)
+      result = filter.run(layout.content)
+      @_obj.site.compiler.stack.pop
+      result
+    end
+
+  end
+
+end
+
+# Include by default
+include Nanoc::Helpers::Render

data/lib/nanoc/helpers/tagging.rb

@@ -0,0 +1,52 @@
+module Nanoc::Helpers
+
+  # Nanoc::Helpers::Tagging provides some support for managing tags added to
+  # pages. To add tags to pages, set the +tags+ page attribute to an array of
+  # tags that should be applied to the page. For example:
+  #
+  #   tags: [ 'foo', 'bar', 'baz' ]
+  module Tagging
+
+    # Returns a formatted list of tags for the given page 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 page has no tags. Defaults to
+    #              "(none)".
+    #
+    # :separator:: The separator to put between tags. Defaults to ", ".
+    def tags_for(page, params={})
+      base_url  = params[:base_url]  || 'http://technorati.com/tag/'
+      none_text = params[:none_text] || '(none)'
+      separator = params[:separator] || ', '
+
+      if page.tags.nil? or page.tags.empty?
+        none_text
+      else
+        page.tags.collect { |tag| link_for_tag(tag, base_url) }.join(separator)
+      end
+    end
+
+    # Returns all pages with the given tag.
+    def pages_with_tag(tag)
+      @pages.select { |p| (p.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

data/lib/nanoc/helpers/xml_sitemap.rb

@@ -0,0 +1,58 @@
+module Nanoc::Helpers
+
+  # Nanoc::Helpers::XMLSitemap contains functionality for building XML
+  # sitemaps that will be crawled by search engines. See the Sitemaps protocol
+  # web site, http://www.sitemaps.org, for details.
+  module XMLSitemap
+
+    # Returns the XML sitemap as a string.
+    #
+    # The following attributes can optionally be set on pages to change the
+    # behaviour of the sitemap:
+    #
+    # * 'changefreq', containing the estimated change frequency as defined by
+    #   the Sitemaps protocol.
+    #
+    # * 'priority', containing the page's priority, ranging from 0.0 to 1.0,
+    #   as defined by the Sitemaps protocol.
+    #
+    # The sitemap will also include dates on which the pages 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 sitemap page 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". It is probably a good idea to define
+    #   this in the page defaults, i.e. the 'meta.yaml' file (at least if the
+    #   filesystem data source is being used, which is probably the case).
+    def xml_sitemap
+      require 'builder'
+
+      # Create builder
+      buffer = ''
+      xml = Builder::XmlMarkup.new(:target => buffer, :indent => 2)
+
+      # Build sitemap
+      xml.instruct!
+      xml.urlset(:xmlns => 'http://www.google.com/schemas/sitemap/0.84') do
+        # Add page
+        @pages.reject { |p| p.is_hidden }.each do |page|
+          xml.url do
+            xml.loc         @page.base_url + page.path
+            xml.lastmod     page.mtime.to_iso8601_date unless page.mtime.nil?
+            xml.changefreq  page.changefreq unless page.changefreq.nil?
+            xml.priority    page.priority unless page.priority.nil?
+          end
+        end
+      end
+
+      # Return sitemap
+      buffer
+    end
+
+  end
+
+end

data/lib/nanoc/routers/default.rb

@@ -0,0 +1,54 @@
+module Nanoc::Routers
+
+  # The default router organises pages in the most obvious, but sometimes
+  # slightly restrictive, way: the hierarchy of compiled pages and assets is
+  # the same as the hierarchy of uncompiled pages and assets.
+  class Default < Nanoc::Router
+
+    identifier :default
+
+    def path_for_page_rep(page_rep)
+      # Get data we need
+      filename   = page_rep.attribute_named(:filename)
+      extension  = page_rep.attribute_named(:extension)
+
+      # Initialize path
+      path = page_rep.page.path + filename
+
+      # Add rep name if necessary
+      unless page_rep.name == :default
+        path += '-' + page_rep.name.to_s
+      end
+
+      # Add extension
+      path += '.' + extension
+
+      # Done
+      path
+    end
+
+    def path_for_asset_rep(asset_rep)
+      # Get data we need
+      extension     = asset_rep.attribute_named(:extension)
+      modified_path = asset_rep.asset.path[0..-2]
+      version       = asset_rep.attribute_named(:version)
+
+      # Initialize path
+      assets_prefix = @site.config[:assets_prefix] || '/assets'
+      path = assets_prefix + modified_path
+
+      # Add rep name if necessary
+      unless asset_rep.name == :default
+        path += '-' + asset_rep.name.to_s
+      end
+
+      # Add extension
+      path += '.' + extension
+
+      # Done
+      path
+    end
+
+  end
+
+end