slodown 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 49f19f4efa582699624089df1ceb43dcb0f095a9
-  data.tar.gz: 473dba59b4920bf8bd07bec99c5b5e3bdb01ef46
+  metadata.gz: 69786a2c6984b3113df329ee878d76eb4de88655
+  data.tar.gz: 9daa0d51fa74d936cf5441d0aafd7013f88b2643
 SHA512:
-  metadata.gz: 018e3cbab23eada8eae8f8fc3fa805cb9b5333fb2a50473a2e7330badf61af9bbce253573517a8db0e9993f9f3222c082dfe464bafe14ef265cc6178dd5ca77c
-  data.tar.gz: 7110e04ac94168c0d14230c812a46fa6f914a1194e6869485052ef1292f2af416e2eaa63b10c2c19f6ba55df40c7bda435d5f800eddb1d82973e9cb9f77cb05c
+  metadata.gz: 37af9f2cf9371fac48f05e3301d916b5bf057980ff78b20f3b06848d9c7fbef5494e6604f658c69f89f063cd4cff11af9af53b941f78439bb3c163c6798abfaf
+  data.tar.gz: 70e96284fdb75a2d9ffa4025b5550c8c0f2f1bc8cfd53aef622b4bd1c2b511801123a32a9ed5a9a4529c1bf64a39465e79a66de4f3f86f1958c6f1b98cd28b4e

data/.travis.yml

@@ -2,6 +2,10 @@ language: ruby
 rvm:
   - 1.9.2
   - 1.9.3
+  - 2.0.0
+  - 2.1.8
+  - 2.2.4
+  - 2.3.0
   # - jruby-19mode # JRuby in 1.9 mode
   # - rbx-19mode
 script: bundle exec rake

data/README.md

@@ -1,34 +1,34 @@
-![slodown](https://dl.dropbox.com/u/7288/hendrik.mans.de/slodown.png)
+![Slodown](https://dl.dropbox.com/u/7288/hendrik.mans.de/slodown.png)
 
-# slodown is the ultimate user input rendering pipeline.
+# Slodown is the ultimate user input rendering pipeline.
 
 [![Build Status](https://travis-ci.org/hmans/slodown.png?branch=master)](https://travis-ci.org/hmans/slodown) [![Gem Version](https://badge.fury.io/rb/slodown.png)](http://badge.fury.io/rb/slodown)
 
-**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.**
+**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:
+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!
-- **add syntax highlighting to Markdown code blocks** through [CodeRay](http://coderay.rubychan.de/).
-- **support 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).
+- **add syntax highlighting to Markdown code blocks** through [CodeRay](http://coderay.rubychan.de/), [Rouge](http://rouge.jneen.net/), or any other highlighter supported by kramdown.
+- **support super-easy rich media embeds**. 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.
+- **sanitize the generated HTML** using the white-list based [sanitize](https://github.com/rgrove/sanitize) gem, with some really good default configuration.
 
-slodown is an extraction from [sloblog.io](http://sloblog.io). It is very easy to extend or modify, as it's just a plain old Ruby class you can inherit from.
+Slodown is an extraction from [sloblog.io](http://sloblog.io). It is very easy to extend or modify, as it's just a plain old Ruby class you can inherit from.
 
-## Installation
+## General Approach
 
-Add this line to your application's Gemfile:
-
-    gem 'slodown'
+Slodown, out of the box, implements my preferred way of handling user input, which looks like this:
 
-And then execute:
+- Convert all Markdown to HTML.
+- Don't strip HTML the user added themselves.
+- Auto-link contained URLs and email addresses.
+- Finally, and most importantly, run the entire HTML through a really, really good whitelist-based sanitizer.
 
-    $ bundle
+This allows users to still add their own HTML, if required. In fact, I typically encourage users to make use of [kramdown's inline attributes], leaving it up the sanitizer to make sure they don't go crazy.
 
-Or install it yourself as:
+If this is not what you want, you will most likely be able to bend Slodown to your will -- it's pretty flexible.
 
-    $ gem install slodown
 
 ## Usage
 
@@ -62,6 +62,43 @@ formatter.extract_metadata.markdown.autolink.sanitize.to_s
 formatter.complete.to_s
 ~~~
 
+If you want to customize Slodown's default behavior, simply create a new class that inherits from `Slodown::Formatter` and override methods like `#kramdown_options`, or add your own behaviors.
+
+
+## Syntax Highlighting
+
+Just add [CodeRay](http://coderay.rubychan.de/) or [Rouge](http://rouge.jneen.net/) to your project to have code blocks in your Markdown syntax-highlighted. Slodown will try to detect which library you're using, but to be sure, change your `kramdown_options` accordingly. For example:
+
+~~~ ruby
+class Formatter < Slodown::Formatter
+  def kramdown_options
+    {
+      syntax_highlighter: 'coderay',
+      syntax_highlighter_opts: { css: :class }
+    }
+  end
+end
+~~~
+
+
+## oEmbed support
+
+> oEmbed is a format for allowing an embedded representation of a URL on third party sites. The simple API allows a website to display embedded content (such as photos or videos) when a user posts a link to that resource, without having to parse the resource directly.
+
+Slodown extends the Markdown image syntax to support oEmbed-based embeds.
+Anything supported by the great [oEmbed gem](https://github.com/judofyr/ruby-oembed) will work. Just supply the URL:
+
+~~~markdown
+![youtube video](https://www.youtube.com/watch?v=oHg5SJYRHA0)
+~~~
+
+**Note on IFRAMEs:** Some oEmbed providers will return IFRAME-based embeds. If you want to control
+which hosts are allowed to have IFRAMEs on your site, override the `Formatter#allowed_iframe_hosts` method to return a regular expression that will be matched against the IFRAME source URL's host. Please note that this will also apply to
+IFRAME HTML tags added by the user directly.
+
+**Note on Twitter:** Twitter's oEmbed endpoint will return a simple bit of markup that works okay out of the box, but can be expanded into a full tweet view client-side. For this to work, you'll want to add Twitter's [widget.js](http://platform.twitter.com/widgets.js) to your application. Please refer to the [Twitter documentation](https://dev.twitter.com/web/javascript) for full instructions.
+
+
 ### Metadata
 
 Slodown allows metadata, such as the creation date, to be defined in the text to be processed:
@@ -84,33 +121,21 @@ Metadata can be accessed with `Slodown::Formatter#metadata`:
 formatter.metadata[:title] # => "Slodown"
 ~~~
 
-## OEmbed support
-
-Slodown extends the Markdown image syntax to support OEmbed-based embeds.
-Anything supported by the great [OEmbed gem](https://github.com/judofyr/ruby-oembed) will work. Just supply the URL:
-
-~~~markdown
-![youtube video](https://www.youtube.com/watch?v=oHg5SJYRHA0)
-~~~
-
-Some OEmbed providers will return IFRAME-based embeds. If you want to control
-which hosts are allowed to have IFRAMEs on your site, override the `Formatter#allowed_iframe_hosts` method to return a regular expression that will be matched against the IFRAME source URL's host. Please note that this will also apply to
-IFRAME HTML tags added by the user directly.
 
 ## 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.
+* Eat more Schnitzel. It's good for you.
 
 ## TODOs
 
-- More/better specs. slodown doesn't have a lot of functionality of its own, passing most of its duties over to the beautiful rendering gems it uses, but I'm sure there's still an opportunity or two for it to break, so, yeah, I should be adding _some_ specs.
+- More/better specs. Slodown doesn't have a lot of functionality of its own, passing most of its duties over to the beautiful rendering gems it uses, but I'm sure there's still an opportunity or two for it to break, so, yeah, I should be adding _some_ specs.
 - Better configuration for the HTML sanitizer. Right now, in order to change the sanitizing behavior, you'll need to inherit a new class from `Slodown::Formatter` and override its `#sanitize_config` method. Regarding the contents of the hash this method returns, please refer to the [sanitize documentation](https://github.com/rgrove/sanitize#custom-configuration).
 
 ## Contributing
 
-Just like with my other gems, I am trying to keep slodown as sane (and small) as possible. If you
+Just like with my other gems, I am trying to keep Slodown as sane (and small) as possible. If you
 want to contribute code, **please talk to me before writing a patch or submitting
 a pull request**! I'm serious about keeping things focused and would hate to cause
 unnecessary disappointment. Thank you.
@@ -124,7 +149,11 @@ If you're still set on submitting a pull request, please consider the following:
 
 ## Version History
 
-### 0.2.0
+### 0.3.0 (2016-02-22)
+
+- Removed the dependency on CodeRay. If you want syntax highlighting in your Markdown parsing, simply add CodeRay (or Rouge, or any other highlighter supported by kramdown) to your project.
+
+### 0.2.0 (2016-02-22)
 
 - Slodown is now whitelisting all domains for possible iframe/embed-based media embeds by default. If you don't want this, you can override `Formatter#allowed_iframe_hosts` to return a regular expression that will match against the embed URL's host.
 - Bumped minimum required version of kramdown to 1.5.0 for all the nice new syntax highlighter integrations it offers (and changes required due to deprecated/changed options.)

data/lib/slodown.rb

@@ -1,7 +1,6 @@
 require 'oembed'
 require 'rinku'
 require 'kramdown'
-require 'coderay'
 require 'sanitize'
 
 require "kramdown/converter/slodown_html"

data/lib/slodown/formatter.rb

@@ -2,11 +2,15 @@ module Slodown
   # This is the base Formatter class provided by Slodown. It works right
   # out of the box if you want to use exactly the functionality provided by
   # it, but in most projects, you'll probably want to create a new class
-  # inheriting from this one.
+  # inheriting from this one, selectively overriding methods like
+  # +kramdown_options+ or adding your own.
   #
   class Formatter
+    attr_reader :metadata
+
     def initialize(source)
       @current = @source = source.to_s
+      @metadata = {}
     end
 
     # Run the entire pipeline in a sane order.
@@ -39,6 +43,8 @@ module Slodown
       end
     end
 
+    # Extract metadata from the document.
+    #
     def extract_metadata
       @metadata = {}
 
@@ -52,33 +58,27 @@ module Slodown
       end
     end
 
-    # Return a hash with the extracted metadata
-    #
-    def metadata
-      @metadata
-    end
-
     def to_s
       @current
     end
 
-  private
-
-    # Applies a conversion of the current text state.
+    # Return a hash of configuration values for kramdown. Please refer to
+    # the documentation of kramdown for details:
+    #
+    # http://kramdown.gettalong.org/options.html
     #
-    def convert(&blk)
-      @current = blk.call(@current)
-      self
-    end
-
     def kramdown_options
       {
-        syntax_highlighter: 'coderay',
-        syntax_highlighter_opts: {
-        }
+        syntax_highlighter: defined?(Rouge) ? 'rouge' : 'coderay',
+        syntax_highlighter_opts: { }
       }
     end
 
+    # Return a hash of configuration values for the sanitize gem. Please refer
+    # to the documentation for sanitize for details:
+    #
+    # https://github.com/rgrove/sanitize#custom-configuration
+    #
     def sanitize_config
       {
         elements: %w(
@@ -112,16 +112,27 @@ module Slodown
       }
     end
 
+    # Return a regular expression that will be matched against an embedded IFRAME's
+    # source URL's host. If the expression matches, the IFRAME tag will be whitelisted
+    # in its entirety; otherwise, it will be sanitized.
+    #
+    # By default, all hosts are allowed. Override this method if this is not what
+    # you want.
+    #
     def allowed_iframe_hosts
-      # By default, allow everything. Override this to return a regular expression
-      # that will be matched against the iframe/embed's src URL's host.
       /.*/
     end
 
+    # A list of sanitize transformers to be applied to the markup that is to be
+    # sanitized. By default, we're only using +embed_transformer+.
+    #
     def transformers
       [embed_transformer]
     end
 
+    # A sanitize transformer that will check the document for IFRAME tags and
+    # validate them against +allowed_iframe_hosts+.
+    #
     def embed_transformer
       lambda do |env|
         node      = env[:node]
@@ -146,5 +157,14 @@ module Slodown
         { node_whitelist: [node] }
       end
     end
+
+  private
+
+    # Applies a conversion of the current text state.
+    #
+    def convert(&blk)
+      @current = blk.call(@current)
+      self
+    end
   end
 end

data/lib/slodown/version.rb

@@ -1,3 +1,3 @@
 module Slodown
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 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 + oEmbed + Sanitize + CodeRay = the ultimate user input rendering pipeline.}
-  gem.summary       = %q{Markdown + oEmbed + Sanitize + CodeRay = the ultimate user input rendering pipeline.}
+  gem.description   = %q{Markdown + oEmbed + Sanitize + Syntax Highlighting = the ultimate user input rendering pipeline.}
+  gem.summary       = %q{Markdown + oEmbed + Sanitize + Syntax Highlighting = the ultimate user input rendering pipeline.}
   gem.homepage      = "https://github.com/hmans/slodown"
 
   gem.files         = `git ls-files`.split($/)
@@ -18,10 +18,9 @@ Gem::Specification.new do |gem|
   gem.require_paths = ["lib"]
 
   gem.add_dependency  'kramdown', '>= 1.5.0'
-  gem.add_dependency  'coderay', '>= 1.0.0'
   gem.add_dependency  'sanitize', '>= 2.0.0'
   gem.add_dependency  'rinku', '>= 1.7.0'
-  gem.add_dependency  'ruby-oembed', '>= 0.8.8'
+  gem.add_dependency  'ruby-oembed', '>= 0.9.0'
 
   gem.add_development_dependency 'rspec', '>= 2.12.0'
   gem.add_development_dependency 'rspec-html-matchers'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: slodown
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Hendrik Mans
@@ -24,20 +24,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.5.0
-- !ruby/object:Gem::Dependency
-  name: coderay
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.0.0
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.0.0
 - !ruby/object:Gem::Dependency
   name: sanitize
   requirement: !ruby/object:Gem::Requirement
@@ -72,14 +58,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.8.8
+        version: 0.9.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.8.8
+        version: 0.9.0
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -122,8 +108,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Markdown + oEmbed + Sanitize + CodeRay = the ultimate user input rendering
-  pipeline.
+description: Markdown + oEmbed + Sanitize + Syntax Highlighting = the ultimate user
+  input rendering pipeline.
 email:
 - hendrik@mans.de
 executables: []
@@ -167,8 +153,8 @@ rubyforge_project:
 rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
-summary: Markdown + oEmbed + Sanitize + CodeRay = the ultimate user input rendering
-  pipeline.
+summary: Markdown + oEmbed + Sanitize + Syntax Highlighting = the ultimate user input
+  rendering pipeline.
 test_files:
 - spec/basic_formatting_spec.rb
 - spec/metadata_extraction_spec.rb