potion 0.0.2

data/.gitignore

@@ -0,0 +1,3 @@
+example_site/_site
+.DS_Store
+*.gem

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,105 @@
+PATH
+  remote: .
+  specs:
+    potion (0.0.2)
+      RedCloth
+      asciidoctor (>= 0.1.0)
+      bluecloth
+      builder
+      bundler (>= 1.0.0)
+      coffee-script
+      commander (>= 4.1.3)
+      contest
+      creole
+      directory_watcher
+      erubis
+      haml (>= 2.2.11)
+      kramdown
+      less
+      liquid
+      markaby
+      maruku
+      mini_magick
+      nokogiri
+      radius
+      rdiscount
+      rdoc
+      rdoc
+      redcarpet
+      require_all
+      sass
+      tilt (>= 1.3.4)
+      wikicloth
+      yajl-ruby
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    RedCloth (4.2.9)
+    asciidoctor (0.1.3)
+    bluecloth (2.2.0)
+    builder (3.2.2)
+    coffee-script (2.2.0)
+      coffee-script-source
+      execjs
+    coffee-script-source (1.6.3)
+    commander (4.1.4)
+      highline (~> 1.6.11)
+    commonjs (0.2.6)
+    contest (0.1.3)
+    creole (0.5.0)
+    diff-lcs (1.2.1)
+    directory_watcher (1.5.1)
+    erubis (2.7.0)
+    execjs (1.4.0)
+      multi_json (~> 1.0)
+    expression_parser (0.9.0)
+    haml (4.0.3)
+      tilt
+    highline (1.6.19)
+    json (1.8.0)
+    kramdown (1.1.0)
+    less (2.3.2)
+      commonjs (~> 0.2.6)
+    liquid (2.5.1)
+    markaby (0.7.2)
+      builder (>= 2.0.0)
+    maruku (0.6.1)
+      syntax (>= 1.0.0)
+    mini_magick (3.6.0)
+      subexec (~> 0.2.1)
+    mini_portile (0.5.1)
+    multi_json (1.7.7)
+    nokogiri (1.6.0)
+      mini_portile (~> 0.5.0)
+    radius (0.7.3)
+    rake (10.0.3)
+    rdiscount (2.1.6)
+    rdoc (4.0.1)
+      json (~> 1.4)
+    redcarpet (3.0.0)
+    require_all (1.2.1)
+    rspec (2.13.0)
+      rspec-core (~> 2.13.0)
+      rspec-expectations (~> 2.13.0)
+      rspec-mocks (~> 2.13.0)
+    rspec-core (2.13.0)
+    rspec-expectations (2.13.0)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.13.0)
+    sass (3.2.10)
+    subexec (0.2.3)
+    syntax (1.0.0)
+    tilt (1.4.1)
+    wikicloth (0.8.0)
+      builder
+      expression_parser
+    yajl-ruby (1.1.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  potion!
+  rake
+  rspec (~> 2)

data/README.md

@@ -0,0 +1,187 @@
+What is Potion?
+===============
+
+Potion is a simple, clean, and easily extensible static site generator. Potion is designed from the ground up to be friendly to any tech-savvy person running a blog or website of almost any kind. 
+
+Running a website via a static site generator is great because all your assets and files are able to be easily version-controlled and backed-up. Hosting for static sites is inexpensive, and a server that's only serving static files can handle a lot more load given the same resources as compared to a server that is serving a site made in a dynamic CMS.
+
+Potion was inspired by Jekyll, however Jekyll was designed to be run as a service that does not allow arbitrary Ruby code to be run (hence it's use of Liquid and Markdown, as opposed to things like Haml). This suits it's purpose perfectly for GitHub, but imposes unnecessary restrictions for other users.
+
+Additionally Jekyll has no concept of files being associated with Posts, which makes writing plugins to handle things like images on a per-post basis very difficult.
+
+Potion was designed to address these issues.
+
+Why would I use Potion?
+-----------------------
+
+* Potion provides support for nearly every major template and markup language including HTML, HAML, Markdown, Liquid, SASS and many more (thanks to Tilt!)
+* Potion is extremely extensible: want to make every photo on your site black-and-white without using Photoshop? No problems. And this is only the beginning!
+
+
+Who should use Potion?
+----------------------
+
+* Anyone who is comfortable programming, and wants to build a website or blog.
+* Anyone who likes Jekyll, but needs 'more'.
+
+Who should avoid Potion?
+------------------------
+
+* People that want a WYSIWYG editor.
+* Anyone who just wants a template website.
+
+Installing Potion
+=================
+
+Assuming that you already have Ruby and Rubygems installed, installing Potion is a snap!
+
+    gem install potion
+  
+Directory Structure
+===================
+
+Much like Jekyll, Potion uses the directory structure of your site to determine the relationships of files to one another. A notable difference is that in Potion each 'Post' is a folder rather than a single file. This allows you to associate files like photos and downloads with a post in a simple fashion.
+
+A typical file structure for a Potion site would look like:
+
+    /
+    |- _config.yml
+    |- _extensions
+    |     |- photo_resizer.rb
+    |     |- more_cowbell_helper.rb
+    |
+    |- _layouts
+    |     |- main.haml
+    |     |- blog.haml
+    |
+    |- assets
+    |     |- main.js
+    |     |- main.sass
+    |
+    |- blog
+    |     |-_posts
+    |           |- 2013-04-03-post-1
+    |           |     |- post-1.html.haml <- Post
+    |           |     |- kittens.jpg 
+    |           |
+    |           |- 2013-04-05-post-2
+    |                 |- post-2.html.haml <- Post
+    |                 |- not-a-virus.exe    
+    |
+    |- index.html.haml <- Page
+  
+  
+Types of content
+================
+
+Potion supports 3 distinct types of content: Pages, Posts and Static File.
+
+Pages
+-----
+
+A 'Page' is any page on your website that will not be a part of a series. A contact page or about page for instance. For a file to be classified as a Page it must have a YAML header, but must not reside in a path that contains the '_posts' qualifier.
+
+Posts
+-----
+
+A 'Post' is any page that will be part of a series. For instance a blog post, or one of the pages in a catalogue. A post can have multiple static files associated with it. For a file to be classified as a Post it must have a YAML header and have a '_posts' folder upstream in it's path.
+
+Static Files
+------------
+
+A static file is any file that does not have a YAML header. Static Files are still processed by Potion to allow extensions the opportunity to perform operations like image resizing etc.
+
+Built-in extensions and helpers
+===============================
+
+SOMETHING ABOUT EXTENSIONS AND HELPERS
+  
+Customizing Potion
+==================
+
+There are two main ways of customizing how Potion functions: Helpers and Extensions.
+
+Helpers
+-------
+
+Helpers are analagous to Rails Helpers, they are methods that you call from a page or post that provide some functionality. Potion ships with a number of built-in helpers, eg:
+
+    = # Find the first photo associated with the current Post that 
+    = # has the work 'kitten' in the filename and insert it here.
+    
+    = photo("kitten") 
+  
+Writing a helper is simple, just add a Ruby file to the `_extensions` directory in the root of your site:
+
+    # /_extensions/christmas_annoyance_helper.rb
+    module Potion::Helpers
+      def christmas_annoyance(repeat = 0)
+        output = ""
+        repeat.times do
+          output << "<p>Jingle, Jingle, Jingle bell rock<br />"
+          output << "What a bright time<br />"
+          output << "Jingle, Jingle, Jingle bell rock<br />"
+          output << "It's the right time</p>"
+        end
+    
+        output
+      end
+    end
+
+Whatever the helper returns will be inserted into the calling layout, page or post at the position the helper was called. Helpers have full access to all the information that Potion gathers about your site. Some useful examples include:
+
+    @metadata               # a hash of the data loaded from the YAML header of the page or post
+    @output_path            # the path that the current file will be output to
+    @relative_output_path   # the path that the current will be output to relative to the root of the site
+    @static_files           # the list of static files associated with a Post, not available for pages
+    @site                   # a reference to the Site object that is associated with the page or post
+    @layout                 # a reference to the Layout object that is associated with the page or post
+    
+    @site.config            # a hash of the data loaded from the _config.yml file in the site's root
+    @site.metadata          # a hash that extensions and helpers can use to store data they generate
+    @site.base_path         # the absolute path of the source site
+    @site.destination_path  # the absolute path of the destination for the site
+    @site.posts             # an array of all the posts in the site
+    @site.pages             # an array of all the pages in the site
+    @site.static_files      # an array of all the static files in the site
+    @site.layouts           # an array of all the layouts in the site
+    @site.extensions        # an array of all the extensions currently loaded for the site
+  
+For more information on available attributes it's probably best just to refer to the code (there's not much of it, and it's clean!)
+
+Extensions
+----------
+
+Writing an extension gives you the ability to 'filter' each file before it is written to the generated site. This is a good way to resize photos or perform some transformation on all the posts in your site.
+
+An extension is simply a Ruby class that responds to the `process` instance method and takes a single argument. Each extension also needs to register itself after it loads by calling the `Potion::Site.register_extension` method.
+
+For instance if you wanted to apply some 'artsy' filters to all the photos in your website or blog you could write an extension like this:
+
+    #/_extensions/too_cheap_for_instagram.rb
+    require 'mini_magick'
+    
+    class TooCheapForInstagram
+      def process(item)
+        return unless item.is_a?(Potion::StaticFile)
+        extensions = [".jpg", ".jpeg", ".gif", ".png"]    
+        return unless extensions.include?(File.extname(item.output_path).downcase)
+    
+        image = MiniMagick::Image.read(item.content)
+        image.sepia_tone("80%")
+        image.vignette("10")
+        item.content = image.to_blob
+      end
+    end
+    
+    Potion::Site.register_extension(TooCheapForInstagram)
+
+Extensions alter the site by writing data back to the posts, pages and static files using their accessor methods. Some of the most useful accessor methods are:
+
+    item.content                # the content of the post, page, or static file
+    item.metadata               # a hash of the data loaded from the YAML header of the page or post
+    item.output_path            # the path where the item will be written when the site is generated
+    item.relative_output_path   # the output path of the item relative to the destination root
+  
+All of these are getters AND setters. Strange things may happen if you set anything other than the metadata and content though, so beware! To get information on all the getters and setters available it is best to look at the source for the relevant objects (/lib/potion/*.rb).
+  

data/Rakefile

@@ -0,0 +1,9 @@
+require 'rubygems'
+require 'rspec/core/rake_task'
+
+desc "Run the specs for potion"
+RSpec::Core::RakeTask.new do |t|
+  t.rspec_opts = "-c"
+  t.fail_on_error = false
+  t.verbose = false
+end

data/bin/potion

@@ -0,0 +1,94 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'bundler/setup'
+require 'potion'
+require 'fileutils'
+require 'webrick'
+require 'commander/import'
+require 'directory_watcher'
+
+include WEBrick
+
+program :version, "0.0.1"
+program :description, 'A simple, extensible, static site generator that supports code, photos and files'
+ 
+command :preview do |c|
+  c.syntax = 'potion preview [options]'
+  c.summary = ''
+  c.description = ''
+  c.example 'description', 'command example'
+  c.option '--no-auto', 'Turn off automatic regeneration, only do this if you are having performance issues'
+  c.action do |args, options|
+    site_root = `pwd`.strip
+    destination = File.join(site_root, "_site")
+    FileUtils.rm_rf(destination)
+    if !options.no_auto.nil?
+      site = Potion::Site.new(site_root, destination)
+      site.write
+    else
+      site = Potion::Site.new(site_root, destination, true)
+      site.write
+      
+      puts "Starting with automatic site regeneration..."
+      dw = DirectoryWatcher.new(site_root, :glob => '**/*', :pre_load => true)
+      dw.interval = 1
+      dw.add_observer do |*args|
+        unless args.first.path.include?("_site")
+          puts "File changes detected, regenerating site..."
+          FileUtils.rm_rf(destination)
+          site = Potion::Site.new(site_root, destination, true)
+          site.write
+        end
+      end
+      
+      dw.start
+    end
+    
+    server = HTTPServer.new(:Port => 4000, :BindAddress => "localhost")
+    server.mount("/", HTTPServlet::FileHandler, destination)
+    
+    thread = Thread.new { server.start }
+    trap("INT") { 
+      server.shutdown
+      exit 0 
+    }
+    
+    thread.run
+    loop { sleep 1000 }
+  end
+end
+
+command :deploy do |c|
+  c.syntax = 'potion deploy TARGET'
+  c.summary = ''
+  c.description = ''
+  c.example 'description', 'command example'
+  c.action do |args, options|
+    unless `git status`.include?("working directory clean")
+      puts "\nERROR: You should commit all your local changes before deploying.\n\n"
+      exit
+    end
+    
+    site_root = `pwd`.strip
+    destination = File.join(site_root, "_site")
+    FileUtils.rm_rf(destination)
+    site = Potion::Site.new(site_root, destination)
+    site.write
+    
+    server = HTTPServer.new(:Port => 4000, :BindAddress => "localhost")
+    server.mount("/", HTTPServlet::FileHandler, destination)
+    
+    thread = Thread.new { server.start }    
+    thread.run
+    
+    puts "\n\n*** The site has been built, please check it at localhost:4000 and then hit enter to continue with the deploy..."
+    puts "*** Press CTRL+C if the site is not as expected and you with to abort the deploy.\n\n"
+    $stdin.gets
+    
+    deploy_target = args.first
+    site.deploy_to(deploy_target)
+  end
+end
+
+

data/example_site/_config.yaml

@@ -0,0 +1,2 @@
+photo_resize:
+  size: "100x100"

data/example_site/_extensions/example_extension.rb

@@ -0,0 +1,42 @@
+require 'mini_magick'
+
+module Potion::Helpers
+  def gallery(*args)
+    "GALLERY!! #{args.inspect}"
+  end
+  
+  def christmas_annoyance(repeat = 0)
+    output = ""
+    repeat.times do
+      output << "<p>Jingle, Jingle, Jingle bell rock<br />"
+      output << "What a bright time<br />"
+      output << "Jingle, Jingle, Jingle bell rock<br />"
+      output << "It's the right time</p>"
+    end
+    
+    output
+  end
+end
+
+class TooCheapForInstagram
+  def process(item)
+    return unless item.is_a?(Potion::StaticFile)
+    extensions = [".jpg", ".jpeg", ".gif", ".png"]    
+    return unless extensions.include?(File.extname(item.output_path).downcase)
+    
+    image = MiniMagick::Image.read(item.content)
+    image.sepia_tone("80%")
+    image.vignette("10")
+    item.content = image.to_blob
+  end
+end
+
+class MoreCowbell
+  def process(item)
+    item.content = item.content + "\nMORE COWBELL"
+  end
+end
+
+
+Potion::Site.register_extension(TooCheapForInstagram)
+Potion::Site.register_extension(MoreCowbell)