slodown 0.1.1 → 0.1.2

data/README.md

@@ -1,6 +1,13 @@
-# Slodown
+# Slodown: the ultimate user input rendering pipeline.
 
-TODO: Write a gem description
+I love Markdown. I love syntax highlighting. I love oEmbed. And last but not least, I love whitelist-based HTML sanitizing. **Slodown** rolls all of these into one, and then some.
+
+Here's what Slodown does by default:
+
+- **render extended Markdown into HTML**. It uses the [kramdown](http://kramdown.rubyforge.org/) library, so yes, footnotes are supported!
+- **supports super-easy rich media embeds**, [sloblog.io-style](http://sloblog.io/~hmans/qhdsk2SMoAU). Just point the Markdown image syntax at, say, a Youtube video, and Slodown will fetch the complete embed code through the magic of [ruby-oembed](https://github.com/judofyr/ruby-oembed).
+- **auto-link contained URLs** using [Rinku](https://github.com/vmg/rinku), which is smart enough to not auto-link URLs contained in, say, code blocks.
+- **sanitize the generated HTML** using the white-list based [sanitize](https://github.com/rgrove/sanitize) gem.
 
 ## Installation
 
@@ -18,7 +25,36 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+For every piece of user input that needs to be rendered, create an instance of `Slodown::Formatter` with the source text and use it to perform somre or all transformations on it. Finally, call `#to_s` to get the rendered output.
+
+### Examples:
+
+~~~ruby
+# let's create an instance to work with
+formatter = Slodown::Formatter.new(text)
+
+# just markdown
+@formatter.markdown.to_s
+
+# just HTML tag sanitizing
+@formatter.sanitize.to_s
+
+# you can chain multiple operations
+@formatter.markdown.sanitize.to_s
+
+# this is the whole deal:
+@formatter.markdown.autolink.sanitize.to_s
+
+# which is the same as:
+@formatter.complete.to_s
+~~~
+
+## Hints
+
+* If you want to add more transformations or change the behavior of the `#complete` method, just subclass `Slodown::Formatter` and go wild. :-)
+* Markdown transformations, HTML sanitizing, oEmbed handshakes and other operations are pretty expensive operations. For sake of performance (and stability), it is recommended that you cache the generated output in some manner.
+* Eat more Schnitzel.
+
 
 ## Contributing
 

data/lib/kramdown/converter/slodown_html.rb

@@ -0,0 +1,15 @@
+# This is the custom kramdown converter class we will be using to render
+# HTML from Markdown. It's essentially a handy way to hook into various
+# elements and add our own logic (like supporting oEmbed embeds in
+# Markdown image elements.)
+#
+class Kramdown::Converter::SlodownHtml < Kramdown::Converter::Html
+  # Hook into image tags to allow oEmbed embeds.
+  #
+  def convert_img(el, indent)
+    oembed = OEmbed::Providers.get(el.attr['src'])
+    %q(<div class="embedded %s %s">%s</div>) % [oembed.type, oembed.provider_name.parameterize, oembed.html]
+  rescue OEmbed::NotFound
+    super
+  end
+end

data/lib/slodown.rb

@@ -4,105 +4,15 @@ require 'kramdown'
 require 'coderay'
 require 'sanitize'
 
+require "kramdown/converter/slodown_html"
 require "slodown/version"
+require "slodown/formatter"
+require "slodown/embed_transformer"
 
+# Register all known oEmbed providers.
+#
 OEmbed::Providers.register_all
 
-class Kramdown::Converter::SloblogHtml < Kramdown::Converter::Html
-  def convert_img(el, indent)
-    oembed = OEmbed::Providers.get(el.attr['src'])
-    %q(<div class="embedded %s %s">%s</div>) % [oembed.type, oembed.provider_name.parameterize, oembed.html]
-  rescue OEmbed::NotFound
-    super
-  end
-end
-
 module Slodown
-  class EmbedTransformer
-    ALLOWED_DOMAINS = %w[youtube.com soundcloud.com vimeo.com]
-
-    def self.call(env)
-      node      = env[:node]
-      node_name = env[:node_name]
-
-      return if env[:is_whitelisted] || !env[:node].element?
-      return unless %w[iframe embed].include? env[:node_name]
-
-      uri = URI(env[:node]['src'])
-      domains = ALLOWED_DOMAINS.map { |d| Regexp.escape(d) }.join("|")
-      return unless uri.host =~ /^(.+\.)?(#{domains})/
-
-      Sanitize.clean_node!(node, {
-        elements: %w[iframe embed],
-        attributes: {
-          all: %w[allowfullscreen frameborder height src width]
-        }
-      })
-
-      { node_whitelist: [node] }
-    end
-  end
-
-  class Formatter
-    def initialize(source)
-      @current = @source = source.to_s
-    end
-
-    def complete
-      markdown.autolink.sanitize
-    end
-
-    def markdown
-      @current = Kramdown::Document.new(@current).to_sloblog_html
-      self
-    end
-
-    def autolink
-      @current = Rinku.auto_link(@current)
-      self
-    end
-
-    def sanitize(mode = :normal)
-      @current = case mode
-      when :normal
-        Sanitize.clean(@current,
-          elements: %w(
-            p a span sub sup strong em div hr abbr
-            ul ol li
-            blockquote pre code
-            h1 h2 h3 h4 h5 h6
-            img object param del
-          ),
-          attributes: {
-            :all     => ['class', 'style', 'title'],
-            'a'      => ['href', 'rel', 'name'],
-            'li'     => ['id'],
-            'sup'    => ['id'],
-            'img'    => ['src', 'title', 'alt', 'width', 'height'],
-            'object' => ['width', 'height'],
-            'param'  => ['name', 'value'],
-            'embed'  => ['allowscriptaccess', 'width', 'height', 'src'],
-            'iframe' => ['width', 'height', 'src']
-          },
-          protocols: {
-            'a' => { 'href' => ['ftp', 'http', 'https', 'mailto', '#fn', '#fnref', :relative] },
-            'img' => {'src'  => ['http', 'https', :relative]},
-            'iframe' => {'src'  => ['http', 'https']},
-            'embed' => {'src'  => ['http', 'https']},
-            'object' => {'src'  => ['http', 'https']},
-            'li' => {'id' => ['fn']},
-            'sup' => {'id' => ['fnref']}
-          },
-          transformers: EmbedTransformer)
-      else
-        Sanitize.clean(@current)
-      end
-
-      self
-    end
-
-    def to_s
-      @current
-    end
-  end
+  # Our main module. Not much happening here. I like huskies.
 end

data/lib/slodown/embed_transformer.rb

@@ -0,0 +1,26 @@
+module Slodown
+  class EmbedTransformer
+    ALLOWED_DOMAINS = %w[youtube.com soundcloud.com vimeo.com]
+
+    def self.call(env)
+      node      = env[:node]
+      node_name = env[:node_name]
+
+      return if env[:is_whitelisted] || !env[:node].element?
+      return unless %w[iframe embed].include? env[:node_name]
+
+      uri = URI(env[:node]['src'])
+      domains = ALLOWED_DOMAINS.map { |d| Regexp.escape(d) }.join("|")
+      return unless uri.host =~ /^(.+\.)?(#{domains})/
+
+      Sanitize.clean_node!(node, {
+        elements: %w[iframe embed],
+        attributes: {
+          all: %w[allowfullscreen frameborder height src width]
+        }
+      })
+
+      { node_whitelist: [node] }
+    end
+  end
+end

data/lib/slodown/formatter.rb

@@ -0,0 +1,72 @@
+module Slodown
+  class Formatter
+    def initialize(source)
+      @current = @source = source.to_s
+    end
+
+    # Runs the entire pipeline.
+    #
+    def complete
+      markdown.autolink.sanitize
+    end
+
+    # Convert the current document state from Markdown into HTML.
+    #
+    def markdown
+      @current = Kramdown::Document.new(@current).to_slodown_html
+      self
+    end
+
+    # Auto-link URLs through Rinku.
+    #
+    def autolink
+      @current = Rinku.auto_link(@current)
+      self
+    end
+
+    # Sanitize HTML tags.
+    #
+    def sanitize(mode = :normal)
+      @current = case mode
+      when :normal
+        Sanitize.clean(@current,
+          elements: %w(
+            p a span sub sup strong em div hr abbr
+            ul ol li
+            blockquote pre code
+            h1 h2 h3 h4 h5 h6
+            img object param del
+          ),
+          attributes: {
+            :all     => ['class', 'style', 'title'],
+            'a'      => ['href', 'rel', 'name'],
+            'li'     => ['id'],
+            'sup'    => ['id'],
+            'img'    => ['src', 'title', 'alt', 'width', 'height'],
+            'object' => ['width', 'height'],
+            'param'  => ['name', 'value'],
+            'embed'  => ['allowscriptaccess', 'width', 'height', 'src'],
+            'iframe' => ['width', 'height', 'src']
+          },
+          protocols: {
+            'a' => { 'href' => ['ftp', 'http', 'https', 'mailto', '#fn', '#fnref', :relative] },
+            'img' => {'src'  => ['http', 'https', :relative]},
+            'iframe' => {'src'  => ['http', 'https']},
+            'embed' => {'src'  => ['http', 'https']},
+            'object' => {'src'  => ['http', 'https']},
+            'li' => {'id' => ['fn']},
+            'sup' => {'id' => ['fnref']}
+          },
+          transformers: EmbedTransformer)
+      else
+        Sanitize.clean(@current)
+      end
+
+      self
+    end
+
+    def to_s
+      @current
+    end
+  end
+end

data/lib/slodown/version.rb

@@ -1,3 +1,3 @@
 module Slodown
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/slodown.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |gem|
   gem.version       = Slodown::VERSION
   gem.authors       = ["Hendrik Mans"]
   gem.email         = ["hendrik@mans.de"]
-  gem.description   = %q{Markdown formatting code, extracted from sloblog.io.}
-  gem.summary       = %q{Markdown formatting code, extracted from sloblog.io.}
+  gem.description   = %q{Markdown + oEmbed + Sanitize + CodeRay = the ultimate user input rendering pipeline.}
+  gem.summary       = %q{Markdown + oEmbed + Sanitize + CodeRay = the ultimate user input rendering pipeline.}
   gem.homepage      = "http://github.com/hmans/slodown"
 
   gem.files         = `git ls-files`.split($/)
@@ -25,4 +25,5 @@ Gem::Specification.new do |gem|
 
   gem.add_development_dependency 'rspec', '>= 2.12.0'
   gem.add_development_dependency 'rspec-html-matchers'
+  gem.add_development_dependency 'rake'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: slodown
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
   prerelease: 
 platform: ruby
 authors:
@@ -123,7 +123,24 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: Markdown formatting code, extracted from sloblog.io.
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Markdown + oEmbed + Sanitize + CodeRay = the ultimate user input rendering
+  pipeline.
 email:
 - hendrik@mans.de
 executables: []
@@ -134,10 +151,13 @@ files:
 - .rspec
 - .travis.yml
 - Gemfile
-- LICENSE.txt
+- LICENSE
 - README.md
 - Rakefile
+- lib/kramdown/converter/slodown_html.rb
 - lib/slodown.rb
+- lib/slodown/embed_transformer.rb
+- lib/slodown/formatter.rb
 - lib/slodown/version.rb
 - slodown.gemspec
 - spec/basic_formatting_spec.rb
@@ -165,7 +185,8 @@ rubyforge_project:
 rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
-summary: Markdown formatting code, extracted from sloblog.io.
+summary: Markdown + oEmbed + Sanitize + CodeRay = the ultimate user input rendering
+  pipeline.
 test_files:
 - spec/basic_formatting_spec.rb
 - spec/spec_helper.rb