plate 0.5.0

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+## Plate 0.5.0
+
+* Initial build, basic site generation, asset compilation and template handling.
+* Command line interface
+* Rebuilding site with changes on demand with the `--watch` parameter
+* Basic callbacks for manipulating page and site content

data/LICENSE

@@ -0,0 +1,21 @@
+(The MIT License)
+
+Copyright (c) 2012 John D. Tornow
+
+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,92 @@
+# Plate
+
+Plate is a super simple static site generator and blog engine. It takes a folder full of Markdown files and turns it into a site that you can host anywhere. The output is a plain old static HTML site. In addition to basic formatting with Markdown, Plate also supports generating asset files with CoffeeScript, Sass and others.
+
+## Requirements
+
+* Ruby 1.8.7, 1.9.2 or 1.9.3
+* Bundler
+
+## Installation
+
+    gem install plate
+
+Or, create a `Gemfile` and add:
+
+    gem 'plate'
+
+## Set up
+
+To generate a new site with plate, run the following command:
+
+    plate new site-name/
+    
+## Building a site
+
+To build your site, run:
+
+    plate build
+    
+Or, just run:
+
+    plate
+
+## Directory Structure
+
+Plate observes the following folder structure in your site:
+
+* config/ - Put your global configuration settings here.
+* content/ - All custom content for the site, besides blog posts. Everything in this folder will be copied over to the published site.
+* layouts/ - Global layouts available for use on all content pages and posts.
+* lib/ - Extend the basic functionality of Plate with plugins in this directory. All `.rb` files will be loaded automatically.
+* posts/ - All blog post content for the site. Posts can be organized into sub-directories if you like.
+* public/ - This will be generated if it does not exist, contains the produced site. Set this as the web server root to your site for development mode.
+
+## Extending Plate
+
+Plate is meant to be extended easily. You might want to extend the basic functionality of Plate to add additional functionality for your site. To get started, create a directory named `lib` in the root of your site. Any Ruby files (ending in `.rb`) will be automatically loaded into the stack when Plate is run. 
+
+### Callbacks
+
+Callbacks are used to call certain blocks of code when an event happens in the lifecycle of building a site.
+
+The callbacks currently available are:
+
+* Site - `before_render`, `after_render`
+* Page/Post - `before_render`, `after_render`
+
+Example of a callback to be run when a site completes the build:
+
+    Plate::Site.register_callback :after_render do |site|
+       puts "the site finished rendering!"
+    end
+
+### Helpers
+
+Helpers are modules that are automatically loaded into views. Any methods in the module will be available when you render a page.
+
+An example of a helper file located in `lib/sample_helper.rb`
+
+    module SampleHelper
+      def sample_helper_method
+        "yes"
+      end
+    end
+    
+Then, in your `.erb` view you can call `sample_helper_method`.
+
+## Issues
+
+If you have any issues or find bugs running Plate, please [report them on Github](https://github.com/jdtornow/plate/issues). While most functions should be stable, Plate is still in its infancy and certain issues may be present.
+
+## Testing
+
+Plate is fully tested using Test Unit, Shoulda and Mocha. To run the test suite, `bundle install` then run:
+
+    rake test
+
+## License
+
+Challah is released under the [MIT license](http://www.opensource.org/licenses/MIT)
+
+Contributions and pull-requests are more than welcome.

data/Rakefile

@@ -0,0 +1,27 @@
+require 'rubygems'
+require 'rake'
+require 'yard'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), *%w(lib)))
+
+task :default => [ :test ]
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+namespace :test do
+  desc "Build the sample site and leave its contents in test/sample/public"
+  task :sample do
+    sh %q(ruby -I"lib:test" test/test_builder.rb -n /sample/)
+  end
+end
+
+YARD::Rake::YardocTask.new do |t|
+end
+
+task :doc => :yard

data/bin/plate

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+
+require 'plate'
+Plate::CLI.run!

data/lib/plate.rb

@@ -0,0 +1,56 @@
+require 'yaml'
+require 'fileutils'
+require 'pathname'
+require 'active_support/core_ext/hash'
+require 'directory_watcher'
+require 'tilt'
+
+require 'plate/version'
+require 'plate/errors'
+
+module Plate
+  autoload :CLI,                            'plate/cli'
+  
+  autoload :Builder,                        'plate/builder'
+  autoload :Callbacks,                      'plate/callbacks'
+  autoload :Layout,                         'plate/layout'
+  autoload :Site,                           'plate/site'
+  
+  autoload :BloggingHelper,                 'plate/helpers/blogging_helper'
+  autoload :MetaHelper,                     'plate/helpers/meta_helper'
+  autoload :URLHelper,                      'plate/helpers/url_helper'
+  
+  autoload :View,                           'plate/view'
+  
+  autoload :PostCollection,                 'plate/post_collection'
+  
+  autoload :Asset,                          'plate/asset'
+  autoload :DynamicPage,                    'plate/dynamic_page'
+  autoload :Page,                           'plate/page'
+  autoload :Post,                           'plate/post'
+  autoload :StaticPage,                     'plate/static_page'
+  
+  autoload :Engine,                         'plate/engine'  
+  autoload :HamlTemplate,                   'plate/haml_template'
+  autoload :MarkdownTemplate,               'plate/markdown_template'
+  autoload :SassTemplate,                   'plate/sass_template'
+  autoload :ScssTemplate,                   'plate/scss_template'
+  
+  extend Engine
+  @engines ||= {}
+  
+  # Set up the basic engines that are supported by Plate. Add your own this same way.
+  # Thanks to sprockets for the inspiration.
+  # https://github.com/sstephenson/sprockets
+  
+  # Assets
+  register_asset_engine :coffee,          Tilt::CoffeeScriptTemplate
+  register_asset_engine :sass,            SassTemplate
+  register_asset_engine :scss,            ScssTemplate
+  
+  # Layouts & Markup
+  register_template_engine :erb,          Tilt::ERBTemplate
+  register_template_engine :haml,         HamlTemplate
+  register_template_engine :md,           MarkdownTemplate
+  register_template_engine :markdown,     MarkdownTemplate
+end

data/lib/plate/asset.rb

@@ -0,0 +1,47 @@
+module Plate
+  # An asset is a CoffeeScript or Sass file that needs to be compiled before writing
+  # to the destination.
+  class Asset < Page
+    def engines
+      @engines ||= self.extensions.reverse.collect { |e| self.site.registered_asset_engines[e.gsub(/\./, '').to_sym] }.reject { |e| !e }
+    end
+    
+    def extensions
+      @extensions ||= self.basename.scan(/\.[^.]+/)
+    end
+    
+    def format_extension
+      self.extensions.reverse.detect { |e| !self.site.asset_engine_extensions.include?(e) }
+    end
+    
+    def file_path      
+      "#{directory}/#{file_name}"
+    end
+    
+    # Same as page, but no layout applied
+    def rendered_content
+      return @rendered_content if @rendered_content
+      
+      result = File.read(file)
+      
+      self.engines.each do |engine|        
+        template = engine.new() { result }
+        result = template.render(self, :site => self.site)
+      end
+      
+      @rendered_content = result
+    end
+    
+    # Write this page to the destination. For static files this just results
+    # in copying the file over to the destination
+    def write!
+      path = File.join(site.build_destination, file_path)
+      
+      FileUtils.mkdir_p(File.dirname(path))
+      
+      File.open(path, 'w') do |f|
+        f.write(self.rendered_content)
+      end
+    end
+  end
+end

data/lib/plate/builder.rb

@@ -0,0 +1,375 @@
+require 'yaml'
+require 'digest'
+
+module Plate  
+  # Used by the command line tool to generate a site in the given directory.
+  class Builder
+    attr_accessor :source, :destination, :options, :site, :enable_logging, :helpers
+    
+    def initialize(source, destination, options = {})
+      @source = source
+      @destination = destination
+      @options = Hash === options ? options.clone : {}      
+      @options.symbolize_keys!
+    end
+    
+    def cache_location
+      return @cache_location if @cache_location
+      
+      if self.options.has_key?(:cache_location)
+        @cache_location ||= File.expand_path(self.options[:cache_location])
+      else
+        @cache_location ||= File.expand_path("~/.plate/#{self.id}")
+      end     
+    end
+    
+    # Remove any caches from this site build, also resets any variables for the caching and 
+    # temporary build folders so they can be reset
+    def clear_cache!
+      FileUtils.rm_rf(cache_location)
+      
+      @cache_location = nil
+      @tmp_destination = nil
+      @loaded = false
+    end
+    
+    # A unique id for this site, based off of the source directory
+    def id
+      check_source!
+      
+      @id ||= [ File.basename(source), Digest::MD5.hexdigest(source) ].collect { |s| s.to_s.downcase.parameterize }.join('-')
+    end
+    
+    def items?
+      self.total_items > 0
+    end
+    
+    def load!
+      unless @loaded
+        log('Site builder initialized.')
+        
+        self.require_plugins!
+        self.load_config_file!
+        self.setup_site!
+        self.setup_tmp_directory!
+        
+        @loaded = true
+      end
+      
+      @loaded
+    end
+    
+    def relative_path(file_or_directory)
+      file_or_directory.gsub(/^#{Regexp.quote(source)}(.*)$/, '\1')
+    end
+    
+    def rebuild!
+      log('Re-rendering site...')
+      
+      clear_cache!
+      
+      self.site.reload!
+      self.render_site!
+      self.copy_to_destination!
+      
+      true
+    end
+    
+    # When watching a directory for changes, allow reloading of site content based on modifications
+    # only in the content, layouts and posts folder. Changes to config or lib files will need to
+    # be reloaded manually.
+    def reloadable?(relative_file)
+      relative_file =~ /^\/?(content|layouts|posts)\/(.*?)/
+    end
+    
+    # Called to start the rendering of the site based on the provided, source, destination and config options.
+    def render!
+      @start_time = Time.now
+      
+      log("Building full site...")
+      
+      self.load!
+      self.render_site!
+      self.copy_to_destination!
+      
+      @end_time = Time.now
+      
+      log("Site build completed in #{timer} seconds")      
+      
+      true
+    end
+    
+    def render_file!(relative_file_path)
+      self.load!
+      
+      page = self.site.find(relative_file_path)
+      
+      if page and page.file?
+        # if the file is a layout, rebuild all pages using it
+        if Layout === page
+          page.reload!
+          
+          log("Building layout [#{page.relative_file}]")
+          
+          self.site.find_by_layout(page.relative_file).each do |layout_page|
+            self.render_file!(layout_page.relative_file)
+          end
+        else
+          log("Building file [#{page.relative_file}]")
+          
+          # Remove tmp file
+          existing_tmp = File.join(tmp_destination, page.file_path)
+          
+          if File.exists?(existing_tmp)
+            FileUtils.rm_rf(existing_tmp)
+          end
+          
+          page.reload!
+          page.write!
+          
+          # File should exist again, even though we just removed it since we re-wrote it.
+          if File.exists?(existing_tmp)
+            existing = File.join(destination, page.file_path)
+
+            if File.exists?(existing)          
+              log("Removing existing file [#{existing}]", :indent)
+              FileUtils.rm_rf(existing)
+            end
+
+            FileUtils.mkdir_p(File.dirname(existing))
+            FileUtils.cp(existing_tmp, existing)
+            
+            log("File build complete.", :indent)
+          end
+        end
+      else
+        log("Cannot render file, it doesn't exist. [#{relative_file_path}]")
+      end
+      
+      true
+    end
+    
+    # Total number of all assets, posts and pages. 
+    def total_items
+      return 0 unless self.site
+      @total_items ||= self.site.all_files.size
+    end
+    
+    # Returns the time it took to run render! (in milliseconds)
+    def timer
+      return 0 unless @end_time and @start_time      
+      ((@end_time - @start_time)).round(2)
+    end
+    
+    # The directory path of where to put the files while the site is being built.
+    #
+    # If this value is nil, no temporary directory is used and files are built
+    # directly in the normal destination folder.
+    def tmp_destination
+      return @tmp_destination if @tmp_destination
+        
+      result = ""
+        
+      if self.options.has_key?(:tmp_destination)
+        if self.options[:tmp_destination]
+          result = File.expand_path(self.options[:tmp_destination])
+        end
+      else
+        result = File.join(cache_location, 'build-cache')
+      end
+      
+      @tmp_destination = result
+    end
+    
+    def tmp_destination?
+      self.tmp_destination.to_s.size > 0
+    end
+    
+    protected
+      # Allows process to continue if the source directory exists. If the source directory does not
+      # exist, raise a source does not exist error.
+      def check_source!
+        raise SourceNotFound unless directory_exists?(source)
+      end
+      
+      # Copy all files from within the tmp/ build directory into the actual destination.
+      #
+      # Warning: This will overwrite any files already in the destination.
+      def copy_to_destination!
+        if items?
+          self.setup_destination!
+          
+          if tmp_destination?
+            log("Copying content to destination directory")        
+            FileUtils.cp_r(Dir.glob("#{tmp_destination}**/*"), destination)
+          end          
+        end
+      end
+      
+      # Utility method for switching between ruby 1.8* and 1.9+
+      def directory_exists?(dir)
+        Dir.respond_to?(:exists?) ? Dir.exists?(dir) : File.directory?(dir)
+      end
+    
+      # Loads the configuration options to use for rendering this site. By default, this information
+      # is loaded from a file located in config/plate.yml. If this file does not exist, no config
+      # data is loaded by default.
+      # 
+      # You can specific additional options by passing them into the options block of this class:
+      #
+      # ## Custom Config File
+      # 
+      # To load a different file, pass in the relative path of that file to the source root into the :config 
+      # option:
+      #
+      #     Builder.new(source, destination, :config => 'config/other-file.yml')
+      def load_config_file!
+        config_file = 'config/plate.yml'
+        
+        # Check for provided config options
+        if options.has_key?(:config)
+          # If config is false, just return without loading anything.
+          if options[:config] == false
+            log("Skipping config file load.")            
+            config_file = false            
+          # If something is provided for config set the config_file
+          else
+            config_file = options[:config]
+          end
+        end
+        
+        if config_file
+          config_file_path = File.join(self.source, config_file)
+
+          log("Checking for config file... [#{config_file_path}]")
+
+          # If the file doesn't exist, just ignore it. If the file exists, load and parse it.
+          if File.exists?(config_file_path)
+            yml = YAML.load_file(config_file_path)
+
+            if yml
+              yml.symbolize_keys!
+              @options = @options.reverse_merge(yml)
+              log("Options loaded from file", :indent)
+            end
+          end
+        end
+        
+        # Make sure that the defaults are available.
+        @options.reverse_merge!({
+          :permalink => '/:category/:year/:month/:slug'
+        })
+      end
+      
+      # Write to the log if enable_logging is enabled
+      def log(message, style = :arrow)
+        prefix = { 
+          :arrow => '  -> ',
+          :indent => '       '
+        }[style] || style
+        
+        puts "#{prefix}#{message}" if !!enable_logging
+      end
+      
+      # Build out the site and store it in the destination directory
+      def render_site!
+        if items?
+          log("Rendering site...")
+          
+          paths = []
+          
+          self.site.run_callback(:before_render)
+          
+          paths += self.site.assets.collect(&:write!)
+          paths += self.site.pages.collect(&:write!)
+          paths += self.site.posts.collect(&:write!)
+          
+          @build_paths = paths
+          
+          self.site.run_callback(:after_render)
+          
+          log("Site rendered!", :indent)
+        else
+          log("No assets, posts or pages found. :(")
+        end
+      end
+      
+      # Load any plugins and helpers in the ./lib folder. Any modules named with the 
+      # format SomethingHelper will automatically be loaded into all views.
+      def require_plugins!
+        self.helpers = []
+        
+        matcher = /^#{Regexp.quote(File.join(source, 'lib'))}\/?(.*).rb$/
+        
+        plugins = Dir.glob(File.join(source, "lib/**/*.rb"))
+        
+        if plugins.length > 0
+          log("Loading plugins...")
+          
+          plugins.each do |file|
+            require file
+
+            underscore_name = file.sub(matcher, '\1')
+
+            # For helpers, make sure the module is defined, and add it to the helpers list
+            if underscore_name =~ /(.*?)_helper$/
+              class_name = underscore_name.classify
+
+              if defined? class_name
+                log("Loaded helper [#{class_name}]", :indent)
+
+                klass = class_name.constantize              
+                self.helpers << klass
+
+                View.send(:include, klass)
+              end
+            end
+          end
+        end
+      end
+      
+      # Clear out the destination directory, if it exists. Leave the root of the 
+      # destination itself, but clear any files within it.
+      def setup_destination!
+        if directory_exists?(destination)
+          log("Clearing destination directory [#{destination}]")
+          
+          FileUtils.rm_r(Dir.glob("#{destination}**/*"), :force => true)
+        elsif items?
+          log("Creating destination directory [#{destination}]")
+          
+          FileUtils.mkdir_p(destination) 
+        end
+      end
+      
+      # Setup the Site instance and prepare it for loading
+      def setup_site!
+        log("Setting up site instance")
+        
+        self.site = Site.new(source, destination, options)        
+        self.site.logger = self
+        self.site.cache_location = self.cache_location
+        
+        log("Site data loaded from source")
+      end
+      
+      # Create a temporary folder to build everything in. Once the build was successful, 
+      # all files will then be placed into the actual destination.
+      def setup_tmp_directory!
+        return unless tmp_destination?
+        
+        log("Setting up tmp build directory [#{tmp_destination}]")
+        
+        # Clear out any existing tmp folder contents
+        if directory_exists?(tmp_destination)
+          log("Clearing existing tmp directory content")
+          
+          FileUtils.rm_rf(tmp_destination)
+        end
+        
+        FileUtils.mkdir_p(tmp_destination)
+        
+        self.site.build_destination = tmp_destination
+      end
+  end
+end