yuzu 0.2.1.pre

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.yardopts

@@ -0,0 +1,7 @@
+-
+docs/About.md
+docs/GettingStarted.md
+docs/Reference.md
+ChangeLog.md
+README.md
+LICENSE.txt

data/ChangeLog.md

@@ -0,0 +1,8 @@
+# ChangeLog
+
+2013-02-09     William Martin <william.martin@anomalus.com>
+
+Major refactoring work to update the project. It's a shame that I didn't keep this change under more fine-grained source control, but it was such a drastic re-architecting that it seemed ok to get the infrastructure in place then add features and bugfixes later.
+
+* Version bump to 0.2.0.
+* Renamed project to 'yuzu'

data/Gemfile

@@ -0,0 +1,26 @@
+source "http://rubygems.org"
+
+gem 'haml', ">= 3.1.7"
+gem 'kramdown', ">= 0.13.7"
+
+# AWS S3 gem not included by default.
+#gem 'aws-s3', ">= 0.6.2"
+
+# fssm is deprecated. Keep until picking an alternate event handler.
+#gem 'fssm', ">= 0.2.5"
+
+# PDF generation soon to come...
+#gem 'hpricot', ">= 0.8.3"
+#gem 'prawn', ">= 0.8.4"
+
+# Textile rendering not available yet.
+#gem 'RedCloth', ">= 4.2.3"
+
+group :development do
+  gem "shoulda", ">= 0"
+  gem "bundler", "~> 1.2.3"
+  gem "jeweler", "~> 1.8.4"
+  gem "rcov", ">= 0"
+  gem "yard", ">= 0.8.3"
+end
+

data/Gemfile.lock

@@ -0,0 +1,30 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    git (1.2.5)
+    haml (3.1.7)
+    jeweler (1.8.4)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+      rdoc
+    json (1.5.1)
+    kramdown (0.13.7)
+    rake (0.8.7)
+    rcov (0.9.9)
+    rdoc (3.12)
+      json (~> 1.4)
+    shoulda (2.11.3)
+    yard (0.8.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.2.3)
+  haml (>= 3.1.7)
+  jeweler (~> 1.8.4)
+  kramdown (>= 0.13.7)
+  rcov
+  shoulda
+  yard (>= 0.8.3)

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011-13 William Martin
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,52 @@
+Yuzu is a blog-aware, static-website generator and publisher that builds an HTML5 website from a folder of text files and images.
+
+For an example of a site rendered with Yuzu, see [Spatial Pixel](http://spatialpixel.com).
+
+## Current Features
+
+* Website generation from a folder of text files (Markdown, plain text, HAML, and more) with minimal additional configuration.
+* Embedded support for multiple publication destinations: FTP, S3, local filesystem (can be used for Dropbox's public folder or a local webserver installation).
+* Content mixing: Any file can be inserted and rendered into other files (barring circular references).
+* Templating: Use HAML to make resuable templates, partials, and layout.
+* Catalogs: A list of files can be gathered, rendered, and paginated on any page.
+* Widget-like components like photo galleries and breadcrumbs.
+* Uses Compass and Less for SASS (or SCSS) to CSS.
+* A blog folder for more blog-like content, supporting categories, recent posts, RSS feeds.
+* Automatic index.html file generation for folders.
+* On Mac: image thumbnail generation.
+
+
+## Features Coming Soon
+
+* Extensibility: The current implementation supports registering new functionality relatively easily. Soon to be refined.
+* Multiple publication formats (HTML, jQuery slideshow, PDF, etc.)
+* Integration with website tools like Bootstrap and HTML5 Boilerplate
+* git hooks for version control and publication management
+* Site themes for quick website creation
+* Watcher script for efficient workflow.
+
+Yuzu supports many features of CMS systems but without having to install resource-intensive publishing software like Wordpress, Drupal, Mephisto, Typo, or Expression Engine, but yuzu is best for small sites that need fast deployment.
+
+Yuzu first came about from the need to publish lecture material for online course material in multiple formats, specifically a single webpage, javascript-enabled slideshow, and PDF. The content-mixing functionality was critical. It is intended to support these multiple rendering points easily so the content only has to be written once. Then the need expanded into building small project-specific websites quickly.
+
+
+## Sample Workflow (Mac)
+
+1. Edit your Markdown content files
+2. Open a terminal
+3. `cd ~/Documents/yuzu-projects/project-folder`
+4. `yuzu preview`
+5. View in a web browser: `http://localhost/~username/project-folder`
+6. Publish to the web: `yuzu publish`
+
+
+## Contributing to yuzu
+ 
+* Check out the latest master branch to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
+* Fork the repo.
+* Run the tests to make sure all is well.
+* Create a new branch.
+* Commit and push.
+* Make sure to add tests for your change.
+* Send me a pull request.
+

data/Rakefile

@@ -0,0 +1,62 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+require './lib/yuzu/version.rb'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "yuzu"
+  gem.homepage = "http://github.com/awmartin/yuzu"
+  gem.license = "MIT"
+  gem.summary = %Q{A blog-aware, static-website generator that converts a folder of text files and images into an HTML5 website.}
+  gem.description = %Q{Yuzu is a blog-aware, static-website (and PDF) generator that converts a folder of text files and images into multiple forms and publishes them to an FTP server, file system, or Amazon Simple Storage Service (S3). It is extensible and designed to function with minimal setup.}
+  gem.email = "william.martin@anomalus.com"
+  gem.authors = ["William Martin"]
+  gem.executables = ['yuzu']
+  gem.version = Yuzu::Version::STRING
+
+  gem.add_dependency 'kramdown', '>= 0.13.7'
+  gem.add_dependency 'haml', '>= 3.1.1'
+  #  gem.add_development_dependency 'rspec', '> 1.2.3'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'yard'
+YARD::Rake::YardocTask.new do |t|
+  #t.files   = ['lib/**/*.rb', OTHER_PATHS]
+  t.options = ['t', 'default', '-p', 'resources/yard', "--markup", "markdown"]
+end
+
+# require 'rake/testtask'
+# Rake::TestTask.new(:test) do |test|
+#   test.libs << 'lib' << 'test'
+#   test.pattern = 'test/**/test_*.rb'
+#   test.verbose = true
+# end
+# 
+# require 'rcov/rcovtask'
+# Rcov::RcovTask.new do |test|
+#   test.libs << 'test'
+#   test.pattern = 'test/**/test_*.rb'
+#   test.verbose = true
+# end
+# 
+# task :default => :test
+# 
+# require 'rake/rdoctask'
+# Rake::RDocTask.new do |rdoc|
+#   version = File.exist?('VERSION') ? File.read('VERSION') : ""
+# 
+#   rdoc.rdoc_dir = 'rdoc'
+#   rdoc.title = "yuzu #{version}"
+#   rdoc.rdoc_files.include('README*')
+#   rdoc.rdoc_files.include('lib/**/*.rb')
+# end

data/bin/yuzu

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+
+$LOAD_PATH.unshift(File.dirname(__FILE__) + '/../lib')
+
+require 'yuzu'
+require 'yuzu/command'
+
+args = ARGV.dup
+ARGV.clear
+
+command_str = args[0].strip rescue 'help'
+command_str = command_str.start_with?("-") ? nil : command_str
+
+Yuzu::Command.run(command_str, args)
+

data/docs/About.md

@@ -0,0 +1,19 @@
+# About
+
+The primary design objective for Yuzu was to build a publication tool that supports:
+
+1. multiple media endpoints (website, javascript slideshow, PDF),
+2. content mixing, to support separate organizations for content in its raw form versus its published form (depending on the endpoint medium), and
+3. embedded publication capabilities (FTP, S3, filesystem).
+
+A major design goal was to require users to get started with as little setup and metadata overhead as possible. Other website generators require you to specify metadata for every page, such a YAML header. Yuzu derives some properties without having to explicitly specify them. For example, page and post titles are extracted from the file name, unless explicitly declared with a tag. This enables you to make a complete website without typing any metadata at all if you need to work quickly. Just author the content and publish.
+
+For example, if you have a folder structure of text files before using Yuzu, you can generate a website from them without creating any new files yourself. Yuzu generates index.html files for every folder and inserts a "catalog" of those files' contents. You can customize this of course, but this is designed to enable the easiest route from a set of text files to a website.
+
+Yuzu distinguishes between local preview and remote publication. Previews allow you to use a local Apache instance (like Web Sharing on a Mac) or Dropbox Public folder to view the polished, rendered website before publishing it on the web.
+
+For local previews, instead of stashing the rendered website into a "site" folder inside the project, you can specify any folder on your harddrive. For example, on a Mac, you can specify your Sites folder (~/Sites/my-site) and on a Mac, view it with Web Sharing (http://localhost/~username/my-site) or another Apache instance.
+
+For remote publication, Yuzu provides interfaces for Amazon Simple Storage Service (S3) and FTP for regular web servers. Specifying a local shared folder, like Dropbox's Public folder, can also be a way to publish the site.
+
+Also, with content mixing, a user can structure raw content irrespective of the website structure. If you're writing about a topic organized in a deep, hierarchical content tree, you can remix and publish the same content in the website structure without having to copy files or copy/paste text. Just use INSERTCONTENTS to insert the contents of another file into this one. In this way, you can author with one folder structure and publish with another, or support two means of browsing and navigating the same content.

data/docs/GettingStarted.md

@@ -0,0 +1,48 @@
+# Getting Started with Yuzu
+
+Using yuzu requires some familiarity with using a terminal application. On a Mac, this is Terminal.app or iTerm2.app.
+
+
+## Creating a New Project
+
+1. Create a folder for your project.
+2. Open your terminal.
+3. Change the directory into your project folder, e.g.
+
+    cd ~/Documents/Projects/my-yuzu-project
+
+4. Create the yuzu project. This command will copy a series of files into the directory, including setting up a Compass project for SASS/SCSS.
+
+    yuzu create
+
+
+## Edit yuzu.yml
+
+This is a YAML file that contains all the necessary configuration to make Yuzu run properly, such as the public name of the site, configuration settings for the preview, remote FTP server, and so on. 
+
+Read through the comments in this file to get a more complete sense of what the options mean. For now, to get started, all we need is to set the site's name and to put in the preview settings.
+
+    site_name: My First Yuzu Project
+    
+    connections:
+      preview:
+        domain: localhost/~username/my-yuzu-project
+        destination: /Users/username/Sites/my-yuzu-project
+        link_root: /~username/my-yuzu-project
+
+The trickiest setting is `link_root`. This is prepended to every URL to get the relative links right. This is a convenience setting, so you can enter LINKROOT/images/grid.png to get /~username/my-yuzu-project/images/grid.png.
+
+This is useful because our site doesn't live at the root server folder, and yuzu uses relative links by default. You can make all links absolute by changing `link_root` to a fully qualified domain name. You can also forget this entirely and specify the complete URLs yourself.
+
+
+## Preview the Sample Site
+
+In Terminal, type `yuzu preview:all`
+
+This will generate your website and produce the rendered version in the folder you specified under `destination` above. Yuzu will automatically create this folder for you.
+
+In a web browser, go to http://localhost/~username/my-yuzu-project.
+
+
+
+

data/docs/Reference.md

@@ -0,0 +1,97 @@
+# Yuzu Tag Reference
+
+## Post Titles
+
+Specify the title of a post, available with `post.post_title`, with the following placed in your file:
+
+    TITLE(Post Title)
+
+If the `TITLE(...)` tag is not present, yuzu will attempt to use rules from the translators. For Markdown, it grabs "# ...". If not present, yuzu will extrapolate the title from the filename. Files should be named in one of two ways:
+
+    a-post-title.md
+    2011-10-10-a-post-title.md
+
+## Catalogs
+
+A catalog is a listing of posts and pages rendered in a partial form. An example would be an index page of blog posts. This allows you to insert several sets of posts from different parts of a website.
+
+    INSERTCATALOG(path:folder-name)
+    INSERTCATALOG(path:folder-name, per_page:10, per_col:1, template:_block.haml)
+
+* `path`  
+The folder containing the posts to be placed into the catalog.
+* `total`
+The number of posts to be shown in this catalog.
+* `per_col`  
+Catalogs are grids of posts rendered with the _template_ specified. This field specifies how many columns there are in the grid. Use 1 (default) for a straight run of typical blog posts.
+* `template`  
+The name of the template file in the `_templates` folder to apply to each item in the catalog (e.g. _block.haml)
+* `category`  
+A category filter, showing pages that only have this category.
+* `page`  
+To control which page to render, such as only the first page, use this field. If not present, yuzu will attempt to paginate the _first_ catalog found in a page without this flag.
+
+## Images
+
+Adding an images tag provides a mechanism for galleries and other renderers to reference those images in a structured way.
+
+    IMAGES(
+        LINKROOT/img/image01.png,
+        LINKROOT/img/image02.png
+    )
+
+## Categories
+
+Categories for blog posts (files only showing up in the `blog_dir` folder) can be specified by setting them explicitly in the content of a post:
+
+    CATEGORIES(Architecture, Design)
+
+The list of categories is available in the `post.categories` variable in all HAML templates. For all the categories in a site, use `post.all_categories`.
+
+## Sidebar Content
+
+Contents of sidebars can be separated by using the tag below. This supports the ability to lay out the sidebar in the templates, instead of putting layout and HTML structure the posts themselves.
+
+    SIDEBAR{
+      This will show up in the "post.sidebar" variable inside templates.
+    }
+
+The format of all contents between the braces must match the contents of the file itself (e.g. Markdown).
+
+## Templates
+
+All HAML files in the template_dir folder, specified in yuzu.yml, are considered templates, where several default variables are available to access and insert content.
+
+Specifying which template to use for a particular file can be achieved with the TEMPLATE tag:
+
+    TEMPLATE(_default.haml)
+
+yuzu automatically looks in the `_templates` folder for the HAML files to use. The default templates required by yuzu are:
+
+* `index.haml`  
+    The template for index.html pages.
+* `generic.haml`  
+    The overall template for all other generic pages and posts (default).
+
+## Templates and Partials
+
+"Partials" are templates that are rendered as part of other templates. They typically contain repeated contents and information that are context-dependent, but cannot be rendered on their own. 
+
+The default templates and partials that must be specified are as follows:
+
+* `_header.haml`  
+    A partial that contains any header content for a typical page.
+* `_footer.haml`  
+    Partial that contains any footer for a typical page.
+* `_menu.haml`  
+    Partial with the global navigation menu.
+* `_head.haml`  
+    Partial containing the HTML `<head></head>` tag for all typical pages.
+* `_gallery.haml`  
+    Partial that renders a gallery of images. Optional.
+
+These are automatically generated with the `create` command when creating a new yuzu project from scratch. Partials and auto-generated templates have a leading underscore as part of their name. Your custom templates don't have to have this.
+
+
+
+

data/lib/helpers/object.rb

@@ -0,0 +1,19 @@
+unless Object.method_defined?(:blank?)
+
+  class Object
+    def blank?
+      case
+      when self.nil?
+        true
+      when is_a?(String)
+        self.empty?
+      when is_a?(Array)
+        self.empty?
+      else
+        false
+      end
+    end
+  end
+
+end
+

data/lib/helpers/path.rb

@@ -0,0 +1,296 @@
+require 'pathname'
+
+module Helpers
+
+  # Path enables more intelligent handling of disk paths. Using Pathname as a foundation, Path
+  # instances can detect parent/child relationships, handle extension and name manipulations natively,
+  # and automate absolute/relative path distinctions.
+  class Path
+    attr_reader :pathname
+
+    def self.join(path1, path2)
+      # TODO This is rather expensive. Make the join more efficient.
+      Path.new(path1).join(Path.new(path2))
+      #Pathname.new(path1).join(Pathname.new(path2)).to_s
+    end
+
+    def initialize(*args)
+      if args.length > 1
+        path = File.join(*args)
+      else
+        path = args[0]
+      end
+
+      if path.nil?
+        @pathname = pwd
+
+      elsif path.is_a?(Pathname)
+        @pathname = path
+
+      elsif path.is_a?(String)
+        @pathname = Pathname.new(path)
+
+      elsif path.is_a?(Path)
+        @pathname = path.pathname
+
+      else
+        raise "Path#initialize didn't get a recognizable argument. Must be String, Pathname, or another Path."
+
+      end
+      raise "@pathname was nil" if @pathname.nil?
+
+      if not @pathname.absolute?
+        @pathname = @pathname.expand_path.relative_path_from(pwd)
+      end
+      @force_is_file = false
+      @force_is_folder = false
+    end
+
+    def dup
+      Path.new(@pathname.dup)
+    end
+
+    def make_file!
+      @force_is_file = true
+      @force_is_folder = false
+    end
+
+    def make_folder!
+      @force_is_file = false
+      @force_is_folder = true
+    end
+
+    def parent
+      Path.new(@pathname.parent)
+    end
+
+    def markdown?
+      [".md", ".mdown", ".mkd", ".markdown", ".markd"].include?(extension)
+    end
+
+    def plaintext?
+      [".txt", ".text"].include?(extension)
+    end
+
+    def == (other)
+      return false if not other.is_a?(Path)
+      @pathname.expand_path == other.pathname.expand_path
+    end
+
+    def stringify
+      "Path(#{absolute})"
+    end
+
+    def + (other)
+      join(other)
+    end
+
+    def join(other)
+      if other.is_a?(Path)
+        Path.new(@pathname + other.pathname)
+      else
+        Path.new(@pathname + other)
+      end
+    end
+
+    def get_child_by_pathname(pathname)
+      return nil if children.nil?
+      children.each do |c|
+        return c if c.pathname == pathname
+      end
+      nil
+    end
+
+    def get_child_by_rootname(rootname)
+      return nil if children.nil?
+      children.each do |c|
+        return c if c.rootname == rootname
+      end
+      nil
+    end
+
+    def get_child_by_basename(basename)
+      return nil if children.nil?
+      children.each do |c|
+        return c if c.basename == basename
+      end
+      nil
+    end
+
+    def get_child_by_filename(filename)
+      return nil if children.nil?
+      children.each do |c|
+        return c if c.filename == filename
+      end
+      nil
+    end
+
+    # Returns the name of the path
+    #
+    #     /path/to/file.md -- file.md
+    #     /path/to/folder  -- folder
+    #
+    # @return [String]
+    def name
+      folder? ? @pathname.basename.to_s : filename.to_s
+    end
+
+    # Returns the base of the filename
+    #
+    #     /path/to/file.md -- file
+    #     /path/to/folder  -- nil
+    #
+    # @return [String, nil]
+    def basename
+      folder? ? nil : @pathname.basename(extension).to_s
+    end
+
+    # Returns the actual filename
+    #
+    #     /path/to/file.md -- file.md
+    #     /path/to/folder  -- nil
+    #
+    # @return [String, nil]
+    def filename
+      folder? ? nil : @pathname.basename.to_s
+    end
+
+    # Returns the directory of this Path
+    #
+    #     /path/to/file.md -- /path/to
+    #     /path/to/folder  -- /path/to/folder
+    #
+    # @return [String]
+    def dirname
+      tr = folder? ? @pathname.to_s : @pathname.dirname.to_s
+      tr == "." ? "" : tr
+    end
+
+    # Return the name of the last element of the Path
+    #
+    #     /path/to/file.md -- file.md
+    #     /path/to/folder  -- folder
+    #
+    # @return [String]
+    def rootname
+      @pathname.basename.to_s
+    end
+
+    def extension
+      @pathname.extname
+    end
+
+    # Return another Path but with the file's extension changed to the one passed in.
+    def with_extension(new_extension)
+      # This method should not return the same value, ever.
+      if exists?
+        file? ? Path.new(relative_path.dirname + (basename + new_extension)) : nil
+      else
+        Path.new(relative_path.dirname + (basename + new_extension))
+      end
+    end
+
+    def add_suffix(suffix)
+      file? ? Path.new(@pathname.parent + (basename + "_#{suffix}" + extension)) : nil
+    end
+
+    # Return whether this Path contains the given Path, Pathname, or String representing a file
+    # path.
+    #
+    # @param [Path, Pathname, String] other The file or folder to be checked.
+    # @return [TrueClass, FalseClass] Whether the given file or folder is contained in this Path.
+    def contains?(other)
+      if other.is_a?(String)
+        path = Path.new(Pathname.new(other))
+
+      elsif other.is_a?(Pathname)
+        path = Path.new(other)
+
+      elsif other.is_a?(Path)
+        path = other
+
+      else
+        raise "Pathname#contains got an argument it didn't recognize."
+      end
+
+      other.absolute.start_with?(absolute)
+    end
+
+    def pwd
+      Pathname.pwd
+    end
+
+    def to_s
+      @pathname.to_s
+    end
+
+    # Return the absolute path of this Path object as a String.
+    def absolute
+      absolute_path.to_s
+    end
+
+    def absolute_path
+      @pathname.expand_path
+    end
+
+    # Return the relative path of this Path object as a String.
+    def relative
+      tr = relative_path.to_s
+      return "" if tr == "."
+      tr
+    end
+
+    def relative_path
+      @pathname.expand_path.relative_path_from(pwd.expand_path)
+    end
+
+    def descend(&block)
+      @pathname.descend(&block)
+    end
+
+    def ascend(&block)
+      @pathname.descend(&block)
+    end
+
+    def exists?
+      @pathname.exist?
+    end
+
+    def folder?
+      @force_is_folder ? true : @pathname.directory?
+    end
+
+    def file?
+      @force_is_file ? true : @pathname.file?
+    end
+
+    # Return the contained children of this Path as an array of Path objects.
+    #
+    # @return [Array] An array of Path objects.
+    def children
+      @children ||= get_children
+    end
+
+    def get_children
+      # Run these checks first. If the pathname doesn't exist, we can't check for its children. If
+      # the folder has no children, it's nil.
+      return nil if not exists?
+      return nil if @pathname.children.nil?
+      folder? ? @pathname.children.collect {|c| Path.new(c)} : nil
+    end
+
+    def files
+      children.select {|path| path.file?}
+    end
+
+    def folders
+      children.select {|path| path.folder?}
+    end
+
+    def url_for(prefix=nil)
+      Url.new(self, prefix=prefix)
+    end
+  end
+
+end
+