slodown 0.1.3 → 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 49f19f4efa582699624089df1ceb43dcb0f095a9
+  data.tar.gz: 473dba59b4920bf8bd07bec99c5b5e3bdb01ef46
+SHA512:
+  metadata.gz: 018e3cbab23eada8eae8f8fc3fa805cb9b5333fb2a50473a2e7330badf61af9bbce253573517a8db0e9993f9f3222c082dfe464bafe14ef265cc6178dd5ca77c
+  data.tar.gz: 7110e04ac94168c0d14230c812a46fa6f914a1194e6869485052ef1292f2af416e2eaa63b10c2c19f6ba55df40c7bda435d5f800eddb1d82973e9cb9f77cb05c

data/README.md

@@ -9,14 +9,13 @@
 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!
-- **adds syntax highlighting to Markdown code blocks** through [CodeRay](http://coderay.rubychan.de/).
-- **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).
+- **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).
 - **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.
 
 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
 
 Add this line to your application's Gemfile:
@@ -33,7 +32,7 @@ Or install it yourself as:
 
 ## Usage
 
-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.
+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 some or all transformations on it. Finally, call `#to_s` to get the rendered output.
 
 ### Examples:
 
@@ -41,6 +40,9 @@ For every piece of user input that needs to be rendered, create an instance of `
 # let's create an instance to work with
 formatter = Slodown::Formatter.new(text)
 
+# just extract metadata
+formatter.extract_metadata.to_s
+
 # just render Markdown to HTML
 formatter.markdown.to_s
 
@@ -54,12 +56,47 @@ formatter.sanitize.to_s
 formatter.markdown.sanitize.to_s
 
 # this is the whole deal:
-formatter.markdown.autolink.sanitize.to_s
+formatter.extract_metadata.markdown.autolink.sanitize.to_s
 
 # which is the same as:
 formatter.complete.to_s
 ~~~
 
+### Metadata
+
+Slodown allows metadata, such as the creation date, to be defined in the text to be processed:
+
+~~~markdown
+#+title: Slodown
+#+created_at: 2014-03-01 13:51:12 CET
+# Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'slodown'
+
+...
+~~~
+
+Metadata can be accessed with `Slodown::Formatter#metadata`:
+
+~~~ruby
+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. :-)
@@ -73,8 +110,27 @@ formatter.complete.to_s
 
 ## Contributing
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+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.
+
+If you're still set on submitting a pull request, please consider the following:
+
+1. Create your pull request from a _feature branch_.
+2. The pull request must only contain changes _related to the feature_.
+3. Please include specs where it makes sense.
+4. Absolutely _no_ version bumps or similar.
+
+## Version History
+
+### 0.2.0
+
+- 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.)
+- Support for Twitter oEmbed (using an unfortunately deprecated API, nonetheless.)
+- Added `Slodown::Formatter#kramdown_options`, returning a hash of kramdown configuration options. Overload this in order to customize the formatter's behavior.
+
+### 0.1.3
+
+- first public release

data/lib/kramdown/converter/slodown_html.rb

@@ -9,7 +9,7 @@ class Kramdown::Converter::SlodownHtml < 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
+  rescue StandardError => e
     super
   end
 end

data/lib/slodown.rb

@@ -7,7 +7,6 @@ require 'sanitize'
 require "kramdown/converter/slodown_html"
 require "slodown/version"
 require "slodown/formatter"
-require "slodown/embed_transformer"
 
 # Register all known oEmbed providers.
 #

data/lib/slodown/formatter.rb

@@ -1,34 +1,61 @@
 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.
+  #
   class Formatter
     def initialize(source)
       @current = @source = source.to_s
     end
 
-    # Runs the entire pipeline.
+    # Run the entire pipeline in a sane order.
     #
     def complete
-      markdown.autolink.sanitize
+      extract_metadata.markdown.autolink.sanitize
     end
 
     # Convert the current document state from Markdown into HTML.
     #
     def markdown
-      @current = Kramdown::Document.new(@current).to_slodown_html
-      self
+      convert do |current|
+        Kramdown::Document.new(current, kramdown_options).to_slodown_html
+      end
     end
 
     # Auto-link URLs through Rinku.
     #
     def autolink
-      @current = Rinku.auto_link(@current)
-      self
+      convert do |current|
+        Rinku.auto_link(current)
+      end
     end
 
     # Sanitize HTML tags.
     #
     def sanitize
-      @current = Sanitize.clean(@current, sanitize_config)
-      self
+      convert do |current|
+        Sanitize.clean(current, sanitize_config)
+      end
+    end
+
+    def extract_metadata
+      @metadata = {}
+
+      convert do |current|
+        current.each_line.drop_while do |line|
+          next false if line !~ /^#\+([a-z_]+): (.*)/
+
+          key, value = $1, $2
+          @metadata[key.to_sym] = value
+        end.join('')
+      end
+    end
+
+    # Return a hash with the extracted metadata
+    #
+    def metadata
+      @metadata
     end
 
     def to_s
@@ -37,12 +64,27 @@ module Slodown
 
   private
 
+    # Applies a conversion of the current text state.
+    #
+    def convert(&blk)
+      @current = blk.call(@current)
+      self
+    end
+
+    def kramdown_options
+      {
+        syntax_highlighter: 'coderay',
+        syntax_highlighter_opts: {
+        }
+      }
+    end
+
     def sanitize_config
       {
         elements: %w(
-          p a span sub sup strong em div hr abbr
+          p br a span sub sup strong em div hr abbr s
           ul ol li
-          blockquote pre code
+          blockquote pre code kbd
           h1 h2 h3 h4 h5 h6
           img object param del
         ),
@@ -66,8 +108,43 @@ module Slodown
           'li' => {'id' => ['fn']},
           'sup' => {'id' => ['fnref']}
         },
-        transformers: EmbedTransformer
+        transformers: transformers
       }
     end
+
+    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
+
+    def transformers
+      [embed_transformer]
+    end
+
+    def embed_transformer
+      lambda do |env|
+        node      = env[:node]
+        node_name = env[:node_name]
+
+        # We're fine with a bunch of stuff -- but not <iframe> and <embed> tags.
+        return if env[:is_whitelisted] || !env[:node].element?
+        return unless %w[iframe embed].include? env[:node_name]
+
+        # We're dealing with an <iframe> or <embed> tag! Let's check its src attribute.
+        # If its host name matches our regular expression, we can whitelist it.
+        uri = URI(env[:node]['src'])
+        return unless uri.host =~ allowed_iframe_hosts
+
+        Sanitize.clean_node!(node, {
+          elements: %w[iframe embed],
+          attributes: {
+            all: %w[allowfullscreen frameborder height src width]
+          }
+        })
+
+        { node_whitelist: [node] }
+      end
+    end
   end
 end

data/lib/slodown/version.rb

@@ -1,3 +1,3 @@
 module Slodown
-  VERSION = "0.1.3"
+  VERSION = "0.2.0"
 end

data/slodown.gemspec

@@ -10,18 +10,18 @@ Gem::Specification.new do |gem|
   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.homepage      = "http://github.com/hmans/slodown"
+  gem.homepage      = "https://github.com/hmans/slodown"
 
   gem.files         = `git ls-files`.split($/)
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ["lib"]
 
-  gem.add_dependency  'kramdown', '>= 0.14.0'
+  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.8.8'
 
   gem.add_development_dependency 'rspec', '>= 2.12.0'
   gem.add_development_dependency 'rspec-html-matchers'

data/spec/basic_formatting_spec.rb

@@ -9,6 +9,6 @@ describe 'basic formatting syntax' do
   # to test the whole of kramdown here. :)~
   #
   it "renders **this** as bold text" do
-    expect(render "**foo**").to eq "<p><strong>foo</strong></p>"
+    expect(render "**foo**").to eq "<p><strong>foo</strong></p>\n"
   end
 end

data/spec/metadata_extraction_spec.rb

@@ -0,0 +1,46 @@
+require 'spec_helper'
+
+describe '#metadata' do
+  let(:text) do
+    <<-EOF.gsub(/^\t/, '')
+	#+title: A document with metadata
+	#+created_at: 2014-03-01 12:56:31 CET
+	# The first headline
+
+	A paragraph.
+        #+with: no metadata
+    EOF
+  end
+
+  let(:formatter) { Slodown::Formatter.new(text).complete }
+
+  it 'returns metadata as a hash' do
+    expect(formatter.metadata).to be_a(Hash)
+  end
+
+  it 'contains every listed key' do
+    expect(formatter.metadata.keys).to match_array([:title, :created_at])
+  end
+
+  it 'contains every listed value' do
+    expect(formatter.metadata.values).to match_array(['A document with metadata',
+                                                      '2014-03-01 12:56:31 CET'])
+  end
+
+  it 'removes metadata from the source' do
+    expect(formatter.to_s).to_not match(/created_at/)
+  end
+
+  describe 'keys occuring more than once' do
+    let(:text) do
+      <<-EOF.gsub(/^\t/, '')
+	#+title: ignored
+	#+title: foo
+      EOF
+    end
+
+    it 'uses the last definition' do
+      expect(formatter.metadata.fetch(:title)).to eql 'foo'
+    end
+  end
+end

metadata

@@ -1,142 +1,125 @@
 --- !ruby/object:Gem::Specification
 name: slodown
 version: !ruby/object:Gem::Version
-  version: 0.1.3
-  prerelease: 
+  version: 0.2.0
 platform: ruby
 authors:
 - Hendrik Mans
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-19 00:00:00.000000000 Z
+date: 2016-02-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: kramdown
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.14.0
+        version: 1.5.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.14.0
+        version: 1.5.0
 - !ruby/object:Gem::Dependency
   name: coderay
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 1.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 1.0.0
 - !ruby/object:Gem::Dependency
   name: sanitize
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 2.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 2.0.0
 - !ruby/object:Gem::Dependency
   name: rinku
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 1.7.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 1.7.0
 - !ruby/object:Gem::Dependency
   name: ruby-oembed
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.8.8
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.8.8
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 2.12.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 2.12.0
 - !ruby/object:Gem::Dependency
   name: rspec-html-matchers
   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'
 - !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
@@ -147,46 +130,46 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
-- .rspec
-- .travis.yml
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
 - Gemfile
 - 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
+- spec/metadata_extraction_spec.rb
 - spec/spec_helper.rb
-homepage: http://github.com/hmans/slodown
+homepage: https://github.com/hmans/slodown
 licenses: []
+metadata: {}
 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.23
+rubygems_version: 2.5.1
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: Markdown + oEmbed + Sanitize + CodeRay = the ultimate user input rendering
   pipeline.
 test_files:
 - spec/basic_formatting_spec.rb
+- spec/metadata_extraction_spec.rb
 - spec/spec_helper.rb

data/lib/slodown/embed_transformer.rb

@@ -1,26 +0,0 @@
-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