nanoc 3.2.4 → 3.3.0

data/lib/nanoc/helpers/tagging.rb

@@ -0,0 +1,71 @@
+# encoding: utf-8
+
+module Nanoc::Helpers
+
+  # Provides 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.
+  #
+  # @example Adding tags to an item
+  #
+  #   tags: [ 'foo', 'bar', 'baz' ]
+  module Tagging
+
+    require 'nanoc/helpers/html_escape'
+    include Nanoc::Helpers::HTMLEscape
+
+    # Returns a formatted list of tags for the given item as a string. The
+    # tags will be linked using the {#link_for_tag} function; the
+    # HTML-escaping rules for {#link_for_tag} apply here as well.
+    #
+    # @option params [String] base_url ("http://technorati.com/tag/") The URL
+    #   to which the tag will be appended to construct the link URL. This URL
+    #   must have a trailing slash.
+    #
+    # @option params [String] none_text ("(none)") The text to display when
+    #   the item has no tags
+    #
+    # @option params [String] separator (", ") The separator to put between
+    #   tags
+    #
+    # @return [String] A hyperlinked list of tags for the given item
+    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
+
+    # Find all items with the given tag.
+    #
+    # @param [String] tag The tag for which to find all items
+    #
+    # @return [Array] 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. The `href` attribute of the link will be HTML-
+    # escaped, as will the content of the `a` element.
+    #
+    # @param [String] tag The name of the tag, which should consist of letters
+    #   and numbers (no spaces, slashes, or other special characters).
+    #
+    # @param [String] base_url The URL to which the tag will be appended to
+    #   construct the link URL. This URL must have a trailing slash.
+    #
+    # @return [String] A link for the given tag and the given base URL
+    def link_for_tag(tag, base_url)
+      %[<a href="#{h base_url}#{h tag}" rel="tag">#{h tag}</a>]
+    end
+
+  end
+
+end

data/lib/nanoc/helpers/text.rb

@@ -0,0 +1,44 @@
+# encoding: utf-8
+
+module Nanoc::Helpers
+
+  # Contains several useful text-related helper functions.
+  module Text
+
+    # Returns an excerpt for the given string. HTML tags are ignored, so if
+    # you don't want them to turn up, they should be stripped from the string
+    # before passing it to the excerpt function.
+    #
+    # @param [String] string The string for which to build an excerpt
+    #
+    # @option params [Number] length (25) The maximum number of characters
+    #   this excerpt can contain, including the omission.
+    #
+    # @option params [String] omission ("...") The string to append to the
+    #   excerpt when the excerpt is shorter than the original string
+    #
+    # @return [String] The excerpt of the given string
+    def excerptize(string, params={})
+      # Initialize params
+      params[:length]   ||= 25
+      params[:omission] ||= '...'
+
+      # Get excerpt
+      length = params[:length] - params[:omission].length
+      length = 0 if length < 0
+      (string.length > params[:length] ? string[0...length] + params[:omission] : string)
+    end
+
+    # Strips all HTML tags out of the given string.
+    #
+    # @param [String] string The string from which to strip all HTML
+    #
+    # @return [String] The given string with all HTML stripped
+    def strip_html(string)
+      # FIXME will need something more sophisticated than this, because it sucks
+      string.gsub(/<[^>]*(>+|\s*\z)/m, '').strip
+    end
+
+  end
+
+end

data/lib/nanoc/helpers/xml_sitemap.rb

@@ -0,0 +1,76 @@
+# encoding: utf-8
+
+module Nanoc::Helpers
+
+  # Contains functionality for building XML sitemaps that will be crawled by
+  # search engines. See the [Sitemaps protocol site](http://www.sitemaps.org)
+  # for details.
+  module XMLSitemap
+
+    # Builds an XML sitemap and returns it.
+    #
+    # The following attributes can optionally be set on items to change the
+    # behaviour of the sitemap:
+    #
+    # * `changefreq` — The estimated change frequency as defined by the
+    #   Sitemaps protocol
+    #
+    # * `priority` — The item's priority, ranging from 0.0 to 1.0, as defined
+    #   by the Sitemaps protocol
+    #
+    # The sitemap will also include dates on which the items 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` — 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".
+    #
+    # @example Excluding binary items from the sitemap
+    #
+    #   <%= xml_sitemap :items => @items.reject{ |i| i[:is_hidden] || i[:binary] } %>
+    #
+    # @option params [Array] :items A list of items to include in the sitemap
+    #
+    # @return [String] The XML sitemap
+    def xml_sitemap(params={})
+      require 'builder'
+
+      # Extract parameters
+      items = params[:items] || @items.reject { |i| i[:is_hidden] }
+
+      # Create builder
+      buffer = ''
+      xml = Builder::XmlMarkup.new(:target => buffer, :indent => 2)
+
+      # Check for required attributes
+      if @site.config[:base_url].nil?
+        raise RuntimeError.new("The Nanoc::Helpers::XMLSitemap helper requires the site configuration to specify the base URL for the site.")
+      end
+
+      # Build sitemap
+      xml.instruct!
+      xml.urlset(:xmlns => 'http://www.sitemaps.org/schemas/sitemap/0.9') do
+        # Add item
+        items.each do |item|
+          item.reps.reject { |r| r.raw_path.nil? }.each do |rep|
+            xml.url do
+              xml.loc         @site.config[:base_url] + rep.path
+              xml.lastmod     item.mtime.to_iso8601_date unless item.mtime.nil?
+              xml.changefreq  item[:changefreq] unless item[:changefreq].nil?
+              xml.priority    item[:priority] unless item[:priority].nil?
+            end
+          end
+        end
+      end
+
+      # Return sitemap
+      buffer
+    end
+
+  end
+
+end

data/lib/nanoc/tasks.rb

@@ -0,0 +1,10 @@
+# encoding: utf-8
+
+require 'nanoc'
+require 'rake'
+
+module Nanoc::Tasks
+end
+
+Dir[File.dirname(__FILE__) + '/tasks/**/*.rb'].each   { |f| load f }
+Dir[File.dirname(__FILE__) + '/tasks/**/*.rake'].each { |f| Rake.application.add_import(f) }

data/lib/nanoc/tasks/clean.rake

@@ -0,0 +1,16 @@
+# encoding: utf-8
+
+desc 'Remove output files generated by nanoc'
+task :clean do
+  # Load site
+  site = Nanoc::Site.new('.')
+  if site.nil?
+    $stderr.puts 'The current working directory does not seem to be a ' +
+                 'valid/complete nanoc site directory; aborting.'
+    exit 1
+  end
+
+  # Clean
+  clean = ::Nanoc::Tasks::Clean.new(site)
+  clean.run
+end

data/lib/nanoc/tasks/clean.rb

@@ -0,0 +1,29 @@
+# encoding: utf-8
+
+module Nanoc::Tasks
+
+  class Clean
+
+    def initialize(site)
+      @site = site
+    end
+
+    def run
+      filenames.each do |filename|
+        FileUtils.rm_f filename unless filename.nil?
+      end
+    end
+
+  private
+
+    def filenames
+      @site.items.map do |item|
+        item.reps.map do |rep|
+          rep.raw_path
+        end
+      end.flatten
+    end
+
+  end
+
+end

data/lib/nanoc/tasks/deploy/rsync.rake

@@ -0,0 +1,16 @@
+# encoding: utf-8
+
+namespace :deploy do
+
+  desc 'Upload the compiled site using rsync'
+  task :rsync do
+    dry_run     = !!ENV['dry_run']
+    config_name = ENV['config'] || :default
+
+    cmd = [ 'deploy', '-t', config_name ]
+    cmd << '-n' if dry_run
+
+    Nanoc::CLI.run cmd
+  end
+
+end

data/lib/nanoc/tasks/validate.rake

@@ -0,0 +1,92 @@
+# encoding: utf-8
+
+namespace :validate do
+
+  desc 'Validate the site’s HTML files'.make_compatible_with_env
+  task :html do
+    # Get output directory
+    site = Nanoc::Site.new('.')
+    if site.nil?
+      $stderr.puts 'The current working directory does not seem to be a ' +
+                   'valid/complete nanoc site directory; aborting.'
+      exit 1
+    end
+    dir = site.config[:output_dir]
+
+    # Validate
+    validator = ::Nanoc::Extra::Validators::W3C.new(dir, [ :html ])
+    validator.run
+  end
+
+  desc 'Validate the site’s CSS files'.make_compatible_with_env
+  task :css do
+    # Get output directory
+    site = Nanoc::Site.new('.')
+    if site.nil?
+      $stderr.puts 'The current working directory does not seem to be a ' +
+                   'valid/complete nanoc site directory; aborting.'
+      exit 1
+    end
+    dir = site.config[:output_dir]
+
+    # Validate
+    validator = ::Nanoc::Extra::Validators::W3C.new(dir, [ :css ])
+    validator.run
+  end
+
+  namespace :links do
+
+    desc 'Validate the site’s internal links'.make_compatible_with_env
+    task :internal do
+      # Get output directory
+      site = Nanoc::Site.new('.')
+      if site.nil?
+        $stderr.puts 'The current working directory does not seem to be a ' +
+                     'valid/complete nanoc site directory; aborting.'
+        exit 1
+      end
+      dir             = site.config[:output_dir]
+      index_filenames = site.config[:index_filenames]
+
+      # Validate
+      validator = ::Nanoc::Extra::Validators::Links.new(dir, index_filenames, :internal => true)
+      validator.run
+    end
+
+    desc 'Validate the site’s internal links'.make_compatible_with_env
+    task :external do
+      # Get output directory
+      site = Nanoc::Site.new('.')
+      if site.nil?
+        $stderr.puts 'The current working directory does not seem to be a ' +
+                     'valid/complete nanoc site directory; aborting.'
+        exit 1
+      end
+      dir             = site.config[:output_dir]
+      index_filenames = site.config[:index_filenames]
+
+      # Validate
+      validator = ::Nanoc::Extra::Validators::Links.new(dir, index_filenames, :external => true)
+      validator.run
+    end
+
+  end
+
+  desc 'Validate the site’s internal and external links'.make_compatible_with_env
+  task :links do
+    # Get output directory
+    site = Nanoc::Site.new('.')
+    if site.nil?
+      $stderr.puts 'The current working directory does not seem to be a ' +
+                   'valid/complete nanoc site directory; aborting.'
+      exit 1
+    end
+    dir             = site.config[:output_dir]
+    index_filenames = site.config[:index_filenames]
+
+    # Validate
+    validator = ::Nanoc::Extra::Validators::Links.new(dir, index_filenames, :internal => true, :external => true)
+    validator.run
+  end
+
+end

data/nanoc.gemspec

@@ -0,0 +1,49 @@
+# encoding: utf-8
+
+$LOAD_PATH.unshift(File.expand_path('../lib/', __FILE__))
+require 'nanoc'
+
+Gem::Specification.new do |s|
+  s.name        = 'nanoc'
+  s.version     = Nanoc::VERSION
+  s.homepage    = 'http://nanoc.stoneship.org/'
+  s.summary     = 'a web publishing system written in Ruby for building small to medium-sized websites.'
+  s.description = 'nanoc is a simple but very flexible static site generator written in Ruby. It operates on local files, and therefore does not run on the server. nanoc “compiles” the local source files into HTML (usually), by evaluating eRuby, Markdown, etc.'
+
+  s.author = 'Denis Defreyne'
+  s.email  = 'denis.defreyne@stoneship.org'
+
+  s.files              = Dir['[A-Z]*'] +
+                         Dir['doc/yardoc_templates/**/*'] +
+                         Dir['{bin,lib,tasks,test}/**/*'] +
+                         [ 'nanoc.gemspec', '.gemtest' ]
+  s.executables        = [ 'nanoc', 'nanoc3' ]
+  s.require_paths      = [ 'lib' ]
+
+  s.rdoc_options     = [ '--main', 'README.md' ]
+  s.extra_rdoc_files = [ 'ChangeLog', 'LICENSE', 'README.md', 'NEWS.md' ]
+
+  s.add_runtime_dependency('cri', '~> 2.1')
+
+  s.add_development_dependency('minitest')
+  s.add_development_dependency('mocha')
+  s.add_development_dependency('rake')
+  s.add_development_dependency('rdiscount')
+  s.add_development_dependency('yard')
+
+  s.post_install_message = %q{------------------------------------------------------------------------------
+Thanks for installing nanoc 3.3! Here are some resources to help you get
+started:
+
+* The web site at <http://nanoc.stoneship.org/>
+* The tutorial at <http://nanoc.stoneship.org/docs/3-getting-started/>
+* The manual at <http://nanoc.stoneship.org/docs/4-basic-concepts/>
+
+If you have questions, issues or simply want to share ideas, join the
+discussion at <http://groups.google.com/group/nanoc> or stop by in the IRC
+channel on irc.freenode.net, channel #nanoc. See you there!
+
+Enjoy!
+------------------------------------------------------------------------------
+}
+end

data/tasks/doc.rake

@@ -0,0 +1,16 @@
+# encoding: utf-8
+
+require 'yard'
+
+YARD::Rake::YardocTask.new(:doc) do |yard|
+  yard.files   = Dir['lib/**/*.rb']
+  yard.options = [
+    '--markup',          'markdown',
+    '--markup-provider', 'kramdown',
+    '--charset',         'utf-8',
+    '--readme',          'README.md',
+    '--files',           'NEWS.md,LICENSE',
+    '--output-dir',      'doc/yardoc',
+    '--template-path',   'doc/yardoc_templates'
+  ]
+end

data/tasks/test.rake

@@ -0,0 +1,46 @@
+# encoding: utf-8
+
+require 'minitest/unit'
+
+test = namespace :test do
+
+  # test:all
+  desc 'Run all tests'
+  task :all do
+    ENV['QUIET'] ||= 'true'
+    $VERBOSE = (ENV['VERBOSE'] == 'true')
+
+    $LOAD_PATH.unshift(File.expand_path(File.dirname(__FILE__) + '/..'))
+
+    # require our test helper so we don't have to in each individual test
+    require 'test/helper'
+
+    test_files = Dir['test/**/*_spec.rb'] + Dir['test/**/test_*.rb']
+    test_files.each { |f| require f }
+
+    MiniTest::Unit.new.run($VERBOSE ? %w( --verbose ) : %w())
+  end
+
+  # test:...
+  %w( base cli data_sources extra filters helpers tasks ).each do |dir|
+    desc "Run all #{dir} tests"
+    task dir.to_sym do |task|
+      ENV['QUIET'] ||= 'true'
+      $VERBOSE = (ENV['VERBOSE'] == 'true')
+
+      $LOAD_PATH.unshift(File.expand_path(File.dirname(__FILE__) + '/..'))
+
+      # require our test helper so we don't have to in each individual test
+      require 'test/helper'
+
+      test_files = Dir["test/#{dir}/**/*_spec.rb"] + Dir["test/#{dir}/**/test_*.rb"]
+      test_files.each { |f| require f }
+
+      MiniTest::Unit.new.run($VERBOSE ? %w( --verbose ) : %w())
+    end
+  end
+
+end
+
+desc 'Alias for test:all'
+task :test => [ :'test:all' ]