html-pipeline-plus 2.10.1

data/README.md

@@ -0,0 +1,370 @@
+# HTML::Pipeline [![Build Status](https://travis-ci.org/jch/html-pipeline.svg?branch=master)](https://travis-ci.org/jch/html-pipeline)
+
+GitHub HTML processing filters and utilities. This module includes a small
+framework for defining DOM based content filters and applying them to user
+provided content. Read an introduction about this project in
+[this blog post](https://github.com/blog/1311-html-pipeline-chainable-content-filters).
+
+`Note`: This plugin is fork and modify base `html-pipeline v2.10.0`: [https://github.com/jch/html-pipeline](https://github.com/jch/html-pipeline) .
+
+- [HTML::Pipeline](./)
+  - [Installation](#installation)
+  - [Usage](#usage)
+    - [Examples](#examples)
+  - [Filters](#filters)
+  - [Dependencies](#dependencies)
+  - [Documentation](#documentation)
+  - [Extending](#extending)
+    - [3rd Party Extensions](#3rd-party-extensions)
+  - [Instrumenting](#instrumenting)
+  - [FAQ](#faq)
+    - [1. Why doesn't my pipeline work when there's no root element in the document?](#1-why-doesnt-my-pipeline-work-when-theres-no-root-element-in-the-document)
+    - [2. How do I customize a whitelist for `SanitizationFilter`s?](#2-how-do-i-customize-a-whitelist-for-sanitizationfilters)
+  - [Contributing](#contributing)
+    - [Contributors](#contributors)
+    - [Releasing A New Version](#releasing-a-new-version)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'html-pipeline-plus'
+```
+
+And then execute:
+
+```sh
+$ bundle
+```
+
+Or install it yourself as:
+
+```sh
+$ gem install html-pipeline-plus
+```
+
+## Usage
+
+This library provides a handful of chainable HTML filters to transform user
+content into markup. A filter takes an HTML string or
+`Nokogiri::HTML::DocumentFragment`, optionally manipulates it, and then
+outputs the result.
+
+For example, to transform Markdown source into Markdown HTML:
+
+```ruby
+require 'html/pipeline'
+
+filter = HTML::Pipeline::MarkdownFilter.new("Hi **world**!")
+filter.call
+```
+
+Filters can be combined into a pipeline which causes each filter to hand its
+output to the next filter's input. So if you wanted to have content be
+filtered through Markdown and be syntax highlighted, you can create the
+following pipeline:
+
+```ruby
+pipeline = HTML::Pipeline.new [
+  HTML::Pipeline::MarkdownFilter,
+  HTML::Pipeline::SyntaxHighlightFilter
+]
+result = pipeline.call <<-CODE
+This is *great*:
+
+    some_code(:first)
+
+CODE
+result[:output].to_s
+```
+
+Prints:
+
+```html
+<p>This is <em>great</em>:</p>
+
+<pre><code>some_code(:first)
+</code></pre>
+```
+
+To generate CSS for HTML formatted code, use the [Rouge CSS Theme](https://github.com/jneen/rouge#css-theme-options) `#css` method. `rouge` is a dependency of the `SyntaxHighlightFilter`.
+
+Some filters take an optional **context** and/or **result** hash. These are
+used to pass around arguments and metadata between filters in a pipeline. For
+example, if you don't want to use GitHub formatted Markdown, you can pass an
+option in the context hash:
+
+```ruby
+filter = HTML::Pipeline::MarkdownFilter.new("Hi **world**!", :gfm => false)
+filter.call
+```
+
+### Examples
+
+We define different pipelines for different parts of our app. Here are a few
+paraphrased snippets to get you started:
+
+```ruby
+# The context hash is how you pass options between different filters.
+# See individual filter source for explanation of options.
+context = {
+  :asset_root => "http://your-domain.com/where/your/images/live/icons",
+  :base_url   => "http://your-domain.com"
+}
+
+# Pipeline providing sanitization and image hijacking but no mention
+# related features.
+SimplePipeline = Pipeline.new [
+  SanitizationFilter,
+  TableOfContentsFilter, # add 'name' anchors to all headers and generate toc list
+  CamoFilter,
+  ImageMaxWidthFilter,
+  SyntaxHighlightFilter,
+  EmojiFilter,
+  AutolinkFilter
+], context
+
+# Pipeline used for user provided content on the web
+MarkdownPipeline = Pipeline.new [
+  MarkdownFilter,
+  SanitizationFilter,
+  CamoFilter,
+  ImageMaxWidthFilter,
+  HttpsFilter,
+  MentionFilter,
+  EmojiFilter,
+  SyntaxHighlightFilter
+], context.merge(:gfm => true) # enable github formatted markdown
+
+
+# Define a pipeline based on another pipeline's filters
+NonGFMMarkdownPipeline = Pipeline.new(MarkdownPipeline.filters,
+  context.merge(:gfm => false))
+
+# Pipelines aren't limited to the web. You can use them for email
+# processing also.
+HtmlEmailPipeline = Pipeline.new [
+  PlainTextInputFilter,
+  ImageMaxWidthFilter
+], {}
+
+# Just emoji.
+EmojiPipeline = Pipeline.new [
+  PlainTextInputFilter,
+  EmojiFilter
+], context
+```
+
+## Filters
+
+* `MentionFilter` - replace `@user` mentions with links
+* `AbsoluteSourceFilter` - replace relative image urls with fully qualified versions
+* `AutolinkFilter` - auto_linking urls in HTML
+* `CamoFilter` - replace http image urls with [camo-fied](https://github.com/atmos/camo) https versions
+* `EmailReplyFilter` - util filter for working with emails
+* `EmojiFilter` - everyone loves [emoji](http://www.emoji-cheat-sheet.com/)!
+* `HttpsFilter` - HTML Filter for replacing http github urls with https versions.
+* `ImageMaxWidthFilter` - link to full size image for large images
+* `MarkdownFilter` - convert markdown to html
+* `PlainTextInputFilter` - html escape text and wrap the result in a div
+* `SanitizationFilter` - whitelist sanitize user markup
+* `SyntaxHighlightFilter` - code syntax highlighter
+* `TextileFilter` - convert textile to html
+* `TableOfContentsFilter` - anchor headings with name attributes and generate Table of Contents html unordered list linking headings
+
+## Dependencies
+
+Filter gem dependencies are not bundled; you must bundle the filter's gem
+dependencies. The below list details filters with dependencies. For example,
+`SyntaxHighlightFilter` uses [rouge](https://github.com/jneen/rouge)
+to detect and highlight languages. For example, to use the `SyntaxHighlightFilter`,
+add the following to your Gemfile:
+
+```ruby
+gem 'rouge'
+```
+
+* `AutolinkFilter` - `rinku`
+* `EmailReplyFilter` - `escape_utils`, `email_reply_parser`
+* `EmojiFilter` - `gemoji`
+* `MarkdownFilter` - `commonmarker`
+* `PlainTextInputFilter` - `escape_utils`
+* `SanitizationFilter` - `sanitize`
+* `SyntaxHighlightFilter` - `rouge`
+* `TableOfContentsFilter` - `escape_utils`
+* `TextileFilter` - `RedCloth`
+
+_Note:_ See [Gemfile](/Gemfile) `:test` block for version requirements.
+
+## Documentation
+
+Full reference documentation can be [found here](http://rubydoc.info/gems/html-pipeline/frames).
+
+## Extending
+To write a custom filter, you need a class with a `call` method that inherits
+from `HTML::Pipeline::Filter`.
+
+For example this filter adds a base url to images that are root relative:
+
+```ruby
+require 'uri'
+
+class RootRelativeFilter < HTML::Pipeline::Filter
+
+  def call
+    doc.search("img").each do |img|
+      next if img['src'].nil?
+      src = img['src'].strip
+      if src.start_with? '/'
+        img["src"] = URI.join(context[:base_url], src).to_s
+      end
+    end
+    doc
+  end
+
+end
+```
+
+Now this filter can be used in a pipeline:
+
+```ruby
+Pipeline.new [ RootRelativeFilter ], { :base_url => 'http://somehost.com' }
+```
+
+### 3rd Party Extensions
+
+If you have an idea for a filter, propose it as
+[an issue](https://github.com/shines77/html-pipeline-plus/issues) first. This allows us discuss
+whether the filter is a common enough use case to belong in this gem, or should be
+built as an external gem.
+
+Here are some extensions people have built:
+
+* [html-pipeline-asciidoc_filter](https://github.com/asciidoctor/html-pipeline-asciidoc_filter)
+* [jekyll-html-pipeline](https://github.com/gjtorikian/jekyll-html-pipeline)
+* [nanoc-html-pipeline](https://github.com/burnto/nanoc-html-pipeline)
+* [html-pipeline-bitly](https://github.com/dewski/html-pipeline-bitly)
+* [html-pipeline-cite](https://github.com/lifted-studios/html-pipeline-cite)
+* [tilt-html-pipeline](https://github.com/bradgessler/tilt-html-pipeline)
+* [html-pipeline-wiki-link'](https://github.com/lifted-studios/html-pipeline-wiki-link) - WikiMedia-style wiki links
+* [task_list](https://github.com/github/task_list) - GitHub flavor Markdown Task List
+* [html-pipeline-nico_link](https://github.com/rutan/html-pipeline-nico_link) - An HTML::Pipeline filter for [niconico](http://www.nicovideo.jp) description links
+* [html-pipeline-gitlab](https://gitlab.com/gitlab-org/html-pipeline-gitlab) - This gem implements various filters for html-pipeline-plus used by GitLab
+* [html-pipeline-youtube](https://github.com/st0012/html-pipeline-youtube) - An HTML::Pipeline filter for YouTube links
+* [html-pipeline-flickr](https://github.com/st0012/html-pipeline-flickr) - An HTML::Pipeline filter for Flickr links
+* [html-pipeline-vimeo](https://github.com/dlackty/html-pipeline-vimeo) - An HTML::Pipeline filter for Vimeo links
+* [html-pipeline-hashtag](https://github.com/mr-dxdy/html-pipeline-hashtag) - An HTML::Pipeline filter for hashtags
+* [html-pipeline-linkify_github](https://github.com/jollygoodcode/html-pipeline-linkify_github) - An HTML::Pipeline filter to autolink GitHub urls
+* [html-pipeline-redcarpet_filter](https://github.com/bmikol/html-pipeline-redcarpet_filter) - Render Markdown source text into Markdown HTML using Redcarpet
+* [html-pipeline-typogruby_filter](https://github.com/bmikol/html-pipeline-typogruby_filter) - Add Typogruby text filters to your HTML::Pipeline
+* [korgi](https://github.com/jodeci/korgi) - HTML::Pipeline filters for links to Rails resources
+
+
+## Instrumenting
+
+Filters and Pipelines can be set up to be instrumented when called. The pipeline must be setup with an
+[ActiveSupport::Notifications](http://api.rubyonrails.org/classes/ActiveSupport/Notifications.html)
+compatible service object and a name. New pipeline objects will default to the
+`HTML::Pipeline.default_instrumentation_service` object.
+
+``` ruby
+# the AS::Notifications-compatible service object
+service = ActiveSupport::Notifications
+
+# instrument a specific pipeline
+pipeline = HTML::Pipeline.new [MarkdownFilter], context
+pipeline.setup_instrumentation "MarkdownPipeline", service
+
+# or set default instrumentation service for all new pipelines
+HTML::Pipeline.default_instrumentation_service = service
+pipeline = HTML::Pipeline.new [MarkdownFilter], context
+pipeline.setup_instrumentation "MarkdownPipeline"
+```
+
+Filters are instrumented when they are run through the pipeline. A
+`call_filter.html_pipeline` event is published once the filter finishes. The
+`payload` should include the `filter` name. Each filter will trigger its own
+instrumentation call.
+
+``` ruby
+service.subscribe "call_filter.html_pipeline" do |event, start, ending, transaction_id, payload|
+  payload[:pipeline] #=> "MarkdownPipeline", set with `setup_instrumentation`
+  payload[:filter] #=> "MarkdownFilter"
+  payload[:context] #=> context Hash
+  payload[:result] #=> instance of result class
+  payload[:result][:output] #=> output HTML String or Nokogiri::DocumentFragment
+end
+```
+
+The full pipeline is also instrumented:
+
+``` ruby
+service.subscribe "call_pipeline.html_pipeline" do |event, start, ending, transaction_id, payload|
+  payload[:pipeline] #=> "MarkdownPipeline", set with `setup_instrumentation`
+  payload[:filters] #=> ["MarkdownFilter"]
+  payload[:doc] #=> HTML String or Nokogiri::DocumentFragment
+  payload[:context] #=> context Hash
+  payload[:result] #=> instance of result class
+  payload[:result][:output] #=> output HTML String or Nokogiri::DocumentFragment
+end
+```
+
+## FAQ
+
+### 1. Why doesn't my pipeline work when there's no root element in the document?
+
+To make a pipeline work on a plain text document, put the `PlainTextInputFilter`
+at the beginning of your pipeline. This will wrap the content in a `div` so the
+filters have a root element to work with. If you're passing in an HTML fragment,
+but it doesn't have a root element, you can wrap the content in a `div`
+yourself. For example:
+
+```ruby
+EmojiPipeline = Pipeline.new [
+  PlainTextInputFilter,  # <- Wraps input in a div and escapes html tags
+  EmojiFilter
+], context
+
+plain_text = "Gutentag! :wave:"
+EmojiPipeline.call(plain_text)
+
+html_fragment = "This is outside of an html element, but <strong>this isn't. :+1:</strong>"
+EmojiPipeline.call("<div>#{html_fragment}</div>") # <- Wrap your own html fragments to avoid escaping
+```
+
+### 2. How do I customize a whitelist for `SanitizationFilter`s?
+
+`SanitizationFilter::WHITELIST` is the default whitelist used if no `:whitelist`
+argument is given in the context. The default is a good starting template for
+you to add additional elements. You can either modify the constant's value, or
+re-define your own constant and pass that in via the context.
+
+## Contributing
+
+Please review the [Contributing Guide](https://github.com/jch/html-pipeline/blob/master/CONTRIBUTING.md).
+
+1. [Fork it](https://help.github.com/articles/fork-a-repo)
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new [Pull Request](https://help.github.com/articles/using-pull-requests)
+
+To see what has changed in recent versions, see the [CHANGELOG](https://github.com/jch/html-pipeline/blob/master/CHANGELOG.md).
+
+### Contributors
+
+Thanks to all of [these contributors](https://github.com/jch/html-pipeline/graphs/contributors).
+
+Project is a member of the [OSS Manifesto](http://ossmanifesto.org/).
+
+### Releasing A New Version
+
+This section is for gem maintainers to cut a new version of the gem.
+
+* create a new branch named `release-x.y.z` where `x.y.z` follows [semver](http://semver.org)
+* update lib/html/pipeline/version.rb to next version number X.X.X
+* update CHANGELOG.md. Prepare a draft with `script/changelog`
+* push branch and create a new pull request
+* after tests are green, merge to master
+* on the master branch, run `script/release`

data/Rakefile

@@ -0,0 +1,15 @@
+#!/usr/bin/env rake
+require 'rubygems'
+require 'bundler/setup'
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = true
+  t.warning = false
+end
+
+task default: :test

data/bin/html-pipeline-plus

@@ -0,0 +1,78 @@
+#!/usr/bin/env ruby
+require 'html/pipeline-plus'
+
+require 'optparse'
+
+# Accept "help", too
+.map! { |a| a == 'help' ? '--help' : a }
+
+onParser.new do |opts|
+  opts.banner = <<-HELP.gsub(/^    /, '')
+    Usage: html-pipeline-plus [-h] [-f]
+           html-pipeline-plus [FILTER [FILTER [...]]] < file.md
+       cat file.md | html-pipeline-plus [FILTER [FILTER [...]]]
+  HELP
+
+ opts.separator 'Options:'
+
+  opts.on('-f', '--filters', 'List the available filters') do
+    filters = HTML::Pipeline.constants.grep(/\w+Filter$/)
+                            .map { |f| f.to_s.gsub(/Filter$/, '') }
+
+    # Text filter doesn't work, no call method
+    filters -= ['Text']
+
+    abort <<-HELP.gsub(/^      /, '')
+      Available filters:
+        #{filters.join("\n        ")}
+    HELP
+  end
+end.parse!
+
+# Default to a GitHub-ish pipeline
+if ARGV.empty?
+
+  filters = [
+    HTML::Pipeline::MarkdownFilter,
+    HTML::Pipeline::SanitizationFilter,
+    HTML::Pipeline::ImageMaxWidthFilter,
+    HTML::Pipeline::EmojiFilter,
+    HTML::Pipeline::AutolinkFilter,
+    HTML::Pipeline::TableOfContentsFilter
+  ]
+
+  # Add syntax highlighting if rouge is present
+  begin
+    require 'rouge'
+    filters << HTML::Pipeline::SyntaxHighlightFilter
+  rescue LoadError
+  end
+
+else
+
+  def filter_named(name)
+    case name
+    when 'Text'
+      raise NameError # Text filter doesn't work, no call method
+    end
+
+    HTML::Pipeline.const_get("#{name}Filter")
+  rescue NameError => e
+    abort "Unknown filter '#{name}'. List filters with the -f option."
+  end
+
+  filters = []
+  until ARGV.empty?
+    name = ARGV.shift
+    filters << filter_named(name)
+  end
+
+end
+
+context = {
+  asset_root: '/assets',
+  base_url: '/',
+  gfm: true
+}
+
+puts HTML::Pipeline.new(filters, context).call(ARGF.read)[:output]

data/html-pipeline-plus.gemspec

@@ -0,0 +1,28 @@
+
+require File.expand_path('../lib/html/pipeline-plus/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.name          = 'html-pipeline-plus'
+  gem.version       = HTML::Pipeline::VERSION
+  gem.license       = 'MIT'
+  gem.authors       = ['Ryan Tomayko', 'Jerry Cheung', 'Garen J. Torikian', 'shines77']
+  gem.email         = ['ryan@github.com', 'jerry@github.com', 'gjtorikian@gmail.com', 'gz_shines@msn.com']
+  gem.description   = 'GitHub HTML processing filters and utilities'
+  gem.summary       = 'Helpers for processing content through a chain of filters'
+  gem.homepage      = 'https://github.com/shines77/html-pipeline-plus/'
+
+  gem.files         = `git ls-files -z`.split("\x0").reject { |f| f =~ %r{^(test|gemfiles|script)/} }
+  gem.require_paths = ['lib']
+
+  gem.add_dependency 'activesupport', '>= 2'
+  gem.add_dependency 'nokogiri', '>= 1.4'
+
+  gem.post_install_message = <<msg
+-------------------------------------------------
+Thank you for installing html-pipeline-plus!
+You must bundle Filter gem dependencies.
+See html-pipeline-plus README.md for more details.
+https://github.com/shines77/html-pipeline-plus#dependencies
+-------------------------------------------------
+msg
+end

data/lib/html/pipeline-plus/@mention_filter.rb

@@ -0,0 +1,138 @@
+require 'set'
+
+module HTML
+  class Pipeline
+    # HTML filter that replaces @user mentions with links. Mentions within <pre>,
+    # <code>, and <a> elements are ignored. Mentions that reference users that do
+    # not exist are ignored.
+    #
+    # Context options:
+    #   :base_url - Used to construct links to user profile pages for each
+    #               mention.
+    #   :info_url - Used to link to "more info" when someone mentions @mention
+    #               or @mentioned.
+    #   :username_pattern - Used to provide a custom regular expression to
+    #                       identify usernames
+    #
+    class MentionFilter < Filter
+      # Public: Find user @mentions in text.  See
+      # MentionFilter#mention_link_filter.
+      #
+      #   MentionFilter.mentioned_logins_in(text) do |match, login, is_mentioned|
+      #     "<a href=...>#{login}</a>"
+      #   end
+      #
+      # text - String text to search.
+      #
+      # Yields the String match, the String login name, and a Boolean determining
+      # if the match = "@mention[ed]".  The yield's return replaces the match in
+      # the original text.
+      #
+      # Returns a String replaced with the return of the block.
+      def self.mentioned_logins_in(text, username_pattern = UsernamePattern)
+        text.gsub MentionPatterns[username_pattern] do |match|
+          login = Regexp.last_match(1)
+          yield match, login, MentionLogins.include?(login.downcase)
+        end
+      end
+
+      # Hash that contains all of the mention patterns used by the pipeline
+      MentionPatterns = Hash.new do |hash, key|
+        hash[key] = /
+          (?:^|\W)                    # beginning of string or non-word char
+          @((?>#{key}))  # @username
+          (?!\/)                      # without a trailing slash
+          (?=
+            \.+[ \t\W]|               # dots followed by space or non-word character
+            \.+$|                     # dots at end of line
+            [^0-9a-zA-Z_.]|           # non-word character except dot
+            $                         # end of line
+          )
+        /ix
+      end
+
+      # Default pattern used to extract usernames from text. The value can be
+      # overriden by providing the username_pattern variable in the context.
+      UsernamePattern = /[a-z0-9][a-z0-9-]*/
+
+      # List of username logins that, when mentioned, link to the blog post
+      # about @mentions instead of triggering a real mention.
+      MentionLogins = %w[
+        mention
+        mentions
+        mentioned
+        mentioning
+      ].freeze
+
+      # Don't look for mentions in text nodes that are children of these elements
+      IGNORE_PARENTS = %w(pre code a style script).to_set
+
+      def call
+        result[:mentioned_usernames] ||= []
+
+        doc.search('.//text()').each do |node|
+          content = node.to_html
+          next unless content.include?('@')
+          next if has_ancestor?(node, IGNORE_PARENTS)
+          html = mention_link_filter(content, base_url, info_url, username_pattern)
+          next if html == content
+          node.replace(html)
+        end
+        doc
+      end
+
+      # The URL to provide when someone @mentions a "mention" name, such as
+      # @mention or @mentioned, that will give them more info on mentions.
+      def info_url
+        context[:info_url] || nil
+      end
+
+      def username_pattern
+        context[:username_pattern] || UsernamePattern
+      end
+
+      # Replace user @mentions in text with links to the mentioned user's
+      # profile page.
+      #
+      # text      - String text to replace @mention usernames in.
+      # base_url  - The base URL used to construct user profile URLs.
+      # info_url  - The "more info" URL used to link to more info on @mentions.
+      #             If nil we don't link @mention or @mentioned.
+      # username_pattern  - Regular expression used to identify usernames in
+      #                     text
+      #
+      # Returns a string with @mentions replaced with links. All links have a
+      # 'user-mention' class name attached for styling.
+      def mention_link_filter(text, _base_url = '/', info_url = nil, username_pattern = UsernamePattern)
+        self.class.mentioned_logins_in(text, username_pattern) do |match, login, is_mentioned|
+          link =
+            if is_mentioned
+              link_to_mention_info(login, info_url)
+            else
+              link_to_mentioned_user(login)
+            end
+
+          link ? match.sub("@#{login}", link) : match
+        end
+      end
+
+      def link_to_mention_info(text, info_url = nil)
+        return "@#{text}" if info_url.nil?
+        "<a href='#{info_url}' class='user-mention'>" \
+          "@#{text}" \
+          '</a>'
+      end
+
+      def link_to_mentioned_user(login)
+        result[:mentioned_usernames] |= [login]
+
+        url = base_url.dup
+        url << '/' unless url =~ /[\/~]\z/
+
+        "<a href='#{url << login}' class='user-mention'>" \
+          "@#{login}" \
+          '</a>'
+      end
+    end
+  end
+end

data/lib/html/pipeline-plus/absolute_source_filter.rb

@@ -0,0 +1,45 @@
+require 'uri'
+
+module HTML
+  class Pipeline
+    class AbsoluteSourceFilter < Filter
+      # HTML Filter for replacing relative and root relative image URLs with
+      # fully qualified URLs
+      #
+      # This is useful if an image is root relative but should really be going
+      # through a cdn, or if the content for the page assumes the host is known
+      # i.e. scraped webpages and some RSS feeds.
+      #
+      # Context options:
+      #   :image_base_url - Base URL for image host for root relative src.
+      #   :image_subpage_url - For relative src.
+      #
+      # This filter does not write additional information to the context.
+      # This filter would need to be run before CamoFilter.
+      def call
+        doc.search('img').each do |element|
+          next if element['src'].nil? || element['src'].empty?
+          src = element['src'].strip
+          next if src.start_with? 'http'
+          base = if src.start_with? '/'
+                   image_base_url
+                 else
+                   image_subpage_url
+                 end
+          element['src'] = URI.join(base, src).to_s
+        end
+        doc
+      end
+
+      # Private: the base url you want to use
+      def image_base_url
+        context[:image_base_url] || raise("Missing context :image_base_url for #{self.class.name}")
+      end
+
+      # Private: the relative url you want to use
+      def image_subpage_url
+        context[:image_subpage_url] || raise("Missing context :image_subpage_url for #{self.class.name}")
+      end
+    end
+  end
+end