nanoc 2.0.4 → 2.1

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

data/lib/nanoc/routers/no_dirs.rb

@@ -0,0 +1,66 @@
+module Nanoc::Routers
+
+  # The no-directories router organises pages very similarly to the default
+  # router, but does not create directories unless necessary. This router will
+  # therefore generate pages with less pretty URLs.
+  #
+  # For example, a page with path /about/ will be written to /about.html
+  # instead of /about/index.html.
+  class NoDirs < Nanoc::Router
+
+    identifier :no_dirs
+
+    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
+      if page_rep.page.path == '/'
+        path = '/' + filename
+      else
+        path = page_rep.page.path[0..-2]
+      end
+
+      # 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 version if necessary
+      unless version.nil?
+        path += '-v' + version.to_s
+      end
+
+      # Add rep name
+      unless asset_rep.name == :default
+        path += '-' + asset_rep.name.to_s
+      end
+
+      # Add extension
+      path += '.' + extension
+
+      # Done
+      path
+    end
+
+  end
+
+end

data/lib/nanoc/routers/versioned.rb

@@ -0,0 +1,79 @@
+module Nanoc::Routers
+
+  # The versioned router behaves pretty much like the default router, with the
+  # exception that asset representations (but not page representations) can
+  # have versions which will be added to generated URLs.
+  #
+  # This is very useful if you want to cache assets aggressively by sending an
+  # +Expires+ header to clients. An +Expires+ header usually has the issue
+  # that clients will not request the asset even if it has changed; giving the
+  # asset a different version will cause the URL to be changed, which in turn
+  # will cause the client to request the new asset.
+  #
+  # = Example
+  #
+  # For example, the URL of a textual asset containing the CSS stylesheet with
+  # its 'version' attribute set to 28 will become /assets/style-v28.css.
+  #
+  # To link to the stylesheet in a DRY way,
+  # give the asset a unique name (such as 'style') and then do something along
+  # this way:
+  #
+  #   <link rel="stylesheet"
+  #         type="text/css"
+  #         media="screen"
+  #         href="<%= @assets.find { |a| a.asset_id == 'style' }.path %>">
+  class Versioned < Nanoc::Router
+
+    identifier :versioned
+
+    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 version if necessary
+      unless version.nil?
+        path += '-v' + version.to_s
+      end
+
+      # Add rep name
+      unless asset_rep.name == :default
+        path += '-' + asset_rep.name.to_s
+      end
+
+      # Add extension
+      path += '.' + extension
+
+      # Done
+      path
+    end
+
+  end
+
+end