octopress-popular-posts 0.1.0

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright (C) 2012 Wong Liang Zan<zan@liangzan.net>
+
+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,105 @@
+# Octopress Popular Posts Plugin
+
+Popular posts plugin adds a popular posts asides section to your [Octopress](http://octopress.org) blog. Popularity of the post is calculated by the [Google page rank](http://en.wikipedia.org/wiki/PageRank).
+
+## How it works
+
+The popular posts template is generated with the blog. It makes queries to check the page rank for each post. Once generated, the popular posts asides section is a static page. Which means popularity is updated only when the site is generated.
+
+Popular posts plugin caches the page rank results of each post. The results are stored in the __.page_ranks__ directory of your blog. When there is a cache, the plugin will read from it. When there is no cache, it will generate one. Caches expires in 1 month. This shortens the time needed to generate your blog.
+
+Google page rank is updated every 3 months. A static page is sufficient as page rank don't change every hour.
+
+## Installation
+
+The plugin is distributed by Ruby gems.
+
+Add this line to your __Gemfile__
+
+```
+gem 'octopress-popular-posts'
+```
+
+Install it using Bundler
+
+```
+bundle install
+```
+
+We have to run installation commands to copy the plugin to your source
+
+```
+bundle exec octopress-popular-posts install
+```
+
+## Usage
+
+Once installed, the popular posts asides section will be generated whenever you run
+
+```
+rake generate
+```
+
+No additional steps are necesary.
+
+## Post install configurations
+
+In your blog's __config.yml__, add this line.
+
+```
+popular_posts_count: 5      # Posts in the sidebar Popular Posts section
+```
+
+This sets the number of popular posts to show.
+
+Next, we need to add the popular post aside section.
+
+```
+default_asides: [custom/asides/about.html, custom/asides/subscribe.html, custom/asides/popular_posts.html, asides/recent_posts.html, asides/github.html, asides/twitter.html, asides/delicious.html, asides/pinboard.html, asides/googleplus.html]
+```
+
+Note the __custom/asides/popular_posts.html__ that is added on the third entry of the array.
+
+Once done, you need to generate the blog.
+
+```
+rake generate
+```
+
+The first run will take some time as the cache for popular plugins is created. You should see the popular posts aside section on your blog.
+
+I also suggest that you ignore the cached page rank files by adding this line to your __.gitignore__
+
+```
+.page_ranks
+```
+
+## Updating the plugin
+
+Upon new updates, run the following command
+
+```
+bundle exec octopress-popular-posts install
+```
+
+## Post remove configurations
+
+To remove the plugin, run the following command
+
+```
+bundle exec octopress-popular-posts remove
+```
+
+You will also need to remove the following configurations
+
+1. The octopress-popular-posts gem from your __Gemfile__
+2. The __popular_posts_count__ variable from your __config.yml__
+3. The popular posts asides under __defaults_asides__ from your __config.yml__
+
+## Other themes and plugins
+
+Shameless plug: more themes and plugins are available on [Octopress themes](http://octopressthemes.com). Feel free to take a look.
+
+## Copyright
+
+Copyright &copy 2012 [Wong Liang Zan](http://liangzan.net). MIT License

data/bin/octopress-popular-posts

@@ -0,0 +1,2 @@
+#!/usr/bin/env ruby
+require File.expand_path(File.dirname(__FILE__) + '/../lib/popular_posts')

data/lib/popular_posts.rb

@@ -0,0 +1,15 @@
+require 'fileutils'
+require File.join(File.dirname(__FILE__) + '/popular_posts/utilities')
+
+# Handles the command line options
+if ARGV.length == 1 && ARGV[0] == 'install'
+  OctopressThemes::PopularPost::Utilities.install
+  puts 'Octopress popular posts plugin: installed'
+  puts 'Please view the README on https://github.com/octopress-themes/popular-posts for post installation configurations.'
+elsif ARGV.length == 1 && ARGV[0] == 'remove'
+  OctopressThemes::PopularPost::Utilities.remove
+  puts 'Octopress popular posts plugin: removed'
+  puts 'Please view the README on https://github.com/octopress-themes/popular-posts for post removal configurations.'
+else
+  puts 'Usage: octopress-popular-posts [install|remove]'
+end

data/lib/popular_posts/utilities.rb

@@ -0,0 +1,86 @@
+# Public: Module for handling the installation and removal of the Octopress popular post
+#         plugin
+module OctopressThemes
+  module PopularPost
+    module Utilities
+      PLUGINS_DIR = File.expand_path(File.dirname(__FILE__) + '/../../templates/plugins')
+      ASIDES_DIR = File.expand_path(File.dirname(__FILE__) + '/../../templates/asides')
+
+      # Public: Installs the templates to the designated locations
+      #
+      # Examples
+      #
+      #   OctopressThemes::PopularPost.install
+      #   # => nil
+      #
+      # Returns nothing
+      def self.install
+        FileUtils.copy_file plugin_path, plugin_destination
+        FileUtils.copy_file aside_path, aside_destination
+      end
+
+      # Public: Removes plugin files
+      #
+      # Examples
+      #
+      #   OctopressThemes::PopularPost.remove
+      #   # => nil
+      #
+      # Returns nothing
+      def self.remove
+        FileUtils.rm plugin_destination
+        FileUtils.rm aside_destination
+      end
+
+      protected
+
+      # Private: Returns the file path to the plugin template
+      #
+      # Examples
+      #
+      #   plugin_path
+      #   # => /path/to/plugin.rb
+      #
+      # Returns a String
+      def self.plugin_path
+        File.join(PLUGINS_DIR, 'popular_post.rb')
+      end
+
+      # Private: Returns the file path to the plugin destination
+      #
+      # Examples
+      #
+      #   plugin_destination
+      #   # => /path/to/destination/plugin.rb
+      #
+      # Returns a String
+      def self.plugin_destination
+        File.join(Dir.pwd, 'plugins', 'popular_post.rb')
+      end
+
+      # Private: Returns the file path to the aside template
+      #
+      # Examples
+      #
+      #   aside_path
+      #   # => /path/to/aside.html
+      #
+      # Returns a String
+      def self.aside_path
+        File.join(ASIDES_DIR, 'popular_posts.html')
+      end
+
+      # Private: Returns the file path to the aside destination
+      #
+      # Examples
+      #
+      #   aside_destination
+      #   # => /path/to/destination/aside.html
+      #
+      # Returns a String
+      def self.aside_destination
+        File.join(Dir.pwd, 'source', '_includes', 'custom', 'asides', 'popular_posts.html')
+      end
+    end
+  end
+end

data/templates/asides/popular_posts.html

@@ -0,0 +1,10 @@
+<section>
+  <h1>Popular Posts</h1>
+  <ul id="recent_posts">
+    {% for post in site.popular_posts limit: site.popular_posts_count %}
+      <li class="post">
+        <a href="{{ root_url }}{{ post.url }}">{{ post.title }}</a>
+      </li>
+    {% endfor %}
+  </ul>
+</section>

data/templates/plugins/popular_post.rb

@@ -0,0 +1,194 @@
+require 'page_rankr'
+require 'yaml'
+
+# Public: Popular posts plugin for Octopress. This plugin
+#         opens up the Jekyll Post and Site classes to allow
+#         Jekyll to render the popular posts aside section
+module OctopressThemes
+  module PopularPost
+    module Post
+
+      def self.included(base)
+        if base.class.instance_methods.include?('page_rank') ||
+            base.class.protected_instance_methods.include?(%w(page_rank_expired? cache_page_rank read_page_rank_cache query_page_rank))
+          raise 'Octopress Popular Posts: Name clashes'
+        else
+          base.class_eval do
+            include PublicInstanceMethods
+            protected
+            include ProtectedInstanceMethods
+          end
+        end
+      end
+
+      module PublicInstanceMethods
+
+        PAGE_RANK_CACHE = '.page_ranks'
+
+        # Public: Returns the page rank of the post. It also caches the page rank.
+        #         If a cached page rank is found, it returns the cached version.
+        #         Caches expire in a month.
+        #
+        # host - The String which is the host name of the web site.
+        #        It is defined in _config.yml. It is needed to form the full url
+        #        of the post.
+        #
+        # Examples
+        #
+        #   page_rank('http://foo.com')
+        #   # => 3
+        #
+        # Returns the Integer page rank of the post
+        def page_rank(host)
+          post_name = self.url.split('/').last
+          cache_dir_path = File.join(Dir.pwd, PAGE_RANK_CACHE)
+          post_path = File.join(Dir.pwd, PAGE_RANK_CACHE, post_name)
+
+          if !File.directory?(cache_dir_path)
+            Dir.mkdir cache_dir_path
+          end
+
+          if File.exists?(post_path) && !page_rank_expired?(post_path)
+            read_page_rank_cache(post_path)[:rank]
+          else
+            post_page_rank = query_page_rank(host)
+            page_rank_content = { url: self.url, rank: post_page_rank }
+            cache_page_rank(page_rank_content, post_path)
+            post_page_rank
+          end
+        end
+      end
+
+      module ProtectedInstanceMethods
+
+        DAY_IN_SECS = 86400
+
+        # Private: Checks if the cached page rank has expired. It is set
+        #         to expire in 1 month. It assumes the presence of a
+        #         cached page rank.
+        #
+        # cache_path - The String which is the file path to the cached
+        #              page rank.
+        #
+        # Examples
+        #
+        #   page_rank_expired?('/path/to/cached/page_rank')
+        #   # => true
+        #
+        # Returns a Boolean.
+        def page_rank_expired?(cache_path)
+          file_modified_time = File.mtime(cache_path)
+          time_past = Time.now - file_modified_time
+
+          # if file has not been modified for over a month
+          time_past > (30 * DAY_IN_SECS)
+        end
+
+        # Private: Caches the page rank of the post.
+        #
+        # page_rank_content - The Hash which is contains rank and
+        #                     the full url of the post.
+        # cache_path        - The String which is the file path
+        #                     to the cache
+        #
+        # Examples
+        #
+        #   cache_page_rank({url: 'http://foo/blog/bar', rank: 2}, '/path/to/cache')
+        #   # => nil
+        #
+        # Returns nothing.
+        def cache_page_rank(page_rank_content, cache_path)
+          File.open(cache_path, 'w') do |file|
+            file.puts YAML.dump(page_rank_content)
+          end
+        end
+
+        # Private: Reads the cached page rank
+        #
+        # cache_path - The String which is the file path to the cache
+        #
+        # Examples
+        #
+        #   read_page_rank('/path/to/cache')
+        #   # => {url: 'http://foo', rank: 2}
+        #
+        # Returns a Hash
+        def read_page_rank_cache(cache_path)
+          YAML.load_file(cache_path)
+        end
+
+        # Private: Queries Google for the page rank of the post
+        #
+        # host - The String which is the host name of the web site.
+        #        It is defined in _config.yml. It is needed to form the full url
+        #        of the post.
+        #
+        # Examples
+        #
+        #   query_page_rank('http://foo.com')
+        #   # => {:google => 3}
+        #
+        # Returns a Hash
+        def query_page_rank(host)
+          PageRankr.ranks("#{host}#{self.url}", :google)[:google] || 0
+        end
+      end
+    end # Post
+
+    module Site
+      def self.included(base)
+        base.class_eval do
+          attr_accessor :popular_posts
+          alias_method :old_read, :read
+          alias_method :old_site_payload, :site_payload
+
+          # Public: Making use of the read method to define popular
+          #         posts. Popular posts are sorted by page rank
+          #
+          # Examples
+          #
+          #   read
+          #   # => nil
+          #
+          # Returns nothing
+          def read
+            old_read
+            host = self.config['url']
+            self.popular_posts = self.posts.sort do |post_x, post_y|
+              if post_y.page_rank(host) > post_x.page_rank(host) then 1
+              elsif post_y.page_rank(host) == post_x.page_rank(host) then 0
+              else -1
+              end
+            end
+          end
+
+          # Public: We need to add popular_posts to site_payload, so that
+          #         it gets passed to Liquid to be rendered.
+          #
+          # Examples
+          #
+          #   site_payload
+          #   # => nil
+          #
+          # Returns nothing
+          def site_payload
+            old_site_hash = old_site_payload
+            old_site_hash["site"].merge!({"popular_posts" => self.popular_posts})
+            old_site_hash
+          end
+        end
+      end # included
+    end # Site
+
+  end # PopularPost
+end # OctopressThemes
+
+module Jekyll
+  class Post
+    include OctopressThemes::PopularPost::Post
+  end
+
+  class Site
+    include OctopressThemes::PopularPost::Site
+  end
+end

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: octopress-popular-posts
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Wong Liang Zan
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-10-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: PageRankr
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.2.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.2.1
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.11.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.11.0
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.11.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.11.2
+description: Octopress popular posts adds a popular posts asides section to your Octopress
+  blog. It makes use of Google page rank to determine the popularity of the posts.
+email:
+- zan@liangzan.net
+executables:
+- octopress-popular-posts
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/popular_posts/utilities.rb
+- lib/popular_posts.rb
+- bin/octopress-popular-posts
+- templates/asides/popular_posts.html
+- templates/plugins/popular_post.rb
+- LICENSE
+- README.md
+homepage: https://github.com/octopress-themes/popular-posts
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Adds a popular posts asides section to your Octopress blog.
+test_files: []