html-pipeline 2.14.3 → 3.0.0.pre1

data/README.md

@@ -1,23 +1,23 @@
-# HTML::Pipeline [![Build Status](https://travis-ci.org/jch/html-pipeline.svg?branch=master)](https://travis-ci.org/jch/html-pipeline)
+# HTMLPipeline
 
-HTML processing filters and utilities. This module includes a small
-framework for defining DOM based content filters and applying them to user
+> **Note**
+> This README refers to the behavior in the new 3.0.0.pre1 gem.
+
+HTML processing filters and utilities. This module is a small
+framework for defining CSS-based content filters and applying them to user
 provided content.
 
-[This project was started at GitHub](https://github.com/blog/1311-html-pipeline-chainable-content-filters). While GitHub still uses a similar design and pattern for rendering content, this gem should be considered standalone and independent from GitHub.
+[Although this project was started at GitHub](https://github.com/blog/1311-html-pipeline-chainable-content-filters), they no longer do. This gem must be considered standalone and independent from GitHub.
 
 - [Installation](#installation)
 - [Usage](#usage)
-  - [Examples](#examples)
+  - [More Examples](#more-examples)
 - [Filters](#filters)
 - [Dependencies](#dependencies)
 - [Documentation](#documentation)
-- [Extending](#extending)
-  - [3rd Party Extensions](#3rd-party-extensions)
 - [Instrumenting](#instrumenting)
-- [Contributing](#contributing)
-  - [Contributors](#contributors)
-  - [Releasing A New Version](#releasing-a-new-version)
+- [Third Party Extensions](#third-party-extensions)
+- [FAQ](#faq)
 
 ## Installation
 
@@ -42,220 +42,216 @@ $ gem install html-pipeline
 ## 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.
+content into HTML markup. Each filter does some work, and then hands off the
+results tothe next filter. A pipeline has several kinds of filters available to use:
 
-For example, to transform Markdown source into Markdown HTML:
+- Multiple `TextFilter`s, which operate a UTF-8 string
+- A `ConvertFilter` filter, which turns text into HTML (eg., Commonmark/Asciidoc -> HTML)
+- A `SanitizationFilter`, which remove dangerous/unwanted HTML elements and attributes
+- Multiple `NodeFilter`s, which operate on a UTF-8 HTML document
 
-```ruby
-require 'html/pipeline'
+You can assemble each sequence into a single pipeline, or choose to call each filter individually.
 
-filter = HTML::Pipeline::MarkdownFilter.new("Hi **world**!")
-filter.call
-```
+As an example, suppose we want to transform Commonmark source text into Markdown HTML. With the content, we also want to:
+
+- change every instance of `$NAME` to "`Johnny"
+- strip undesired HTML
+- linkify @mention
 
-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:
+We can construct a pipeline to do all that like this:
 
 ```ruby
-pipeline = HTML::Pipeline.new [
-  HTML::Pipeline::MarkdownFilter,
-  HTML::Pipeline::SyntaxHighlightFilter
-]
-result = pipeline.call <<-CODE
-This is *great*:
+require 'html_pipeline'
 
-    some_code(:first)
+class HelloJohnnyFilter < HTMLPipelineFilter
+  def call
+    text.gsub("$NAME", "Johnny")
+  end
+end
 
-CODE
-result[:output].to_s
+pipeline = HTMLPipeline.new(
+  text_filters: [HelloJohnnyFilter.new]
+  convert_filter: HTMLPipeline::ConvertFilter::MarkdownFilter.new),
+    # note: next line is not needed as sanitization occurs by default;
+    # see below for more info
+  sanitization_config: HTMLPipeline::SanitizationFilter::DEFAULT_CONFIG,
+  node_filters: [HTMLPipeline::NodeFilter::MentionFilter.new]
+)
+pipeline.call(user_supplied_text) # recommended: can call pipeline over and over
 ```
 
-Prints:
-
-```html
-<p>This is <em>great</em>:</p>
+Filters can be custom ones you create (like `HelloJohnnyFilter`), and `HTMLPipeline` additionally provides several helpful ones (detailed below). If you only need a single filter, you can call one individually, too:
 
-<pre><code>some_code(:first)
-</code></pre>
+```ruby
+filter = HTMLPipeline::ConvertFilter::MarkdownFilter.new(text)
+filter.call
 ```
 
-To generate CSS for HTML formatted code, use the [Rouge CSS Theme](https://github.com/rouge-ruby/rouge#css-options) `#css` method. `rouge` is a dependency of the `SyntaxHighlightFilter`.
+Filters combine into a sequential pipeline, and each filter hands its
+output to the next filter's input. Text filters are
+processed first, then the convert filter, sanitization filter, and finally, the node filters.
 
-Some filters take an optional **context** and/or **result** hash. These are
+Some filters take optional `context` and/or `result` hash(es). 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:
+example, if you want to disable footnotes in the `MarkdownFilter`, you can pass an option in the context hash:
 
 ```ruby
-filter = HTML::Pipeline::MarkdownFilter.new("Hi **world**!", :gfm => false)
+context =  { markdown: extensions: { footnotes: false } }
+filter = HTMLPipeline::ConvertFilter::MarkdownFilter.new("Hi **world**!", context: context)
 filter.call
 ```
 
-### Examples
+Please refer to the documentation for each filter to understand what configuration options are available.
+
+### More Examples
 
-We define different pipelines for different parts of our app. Here are a few
+Different pipelines can be defined for different parts of an 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"
+  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))
+MarkdownPipeline = HTMLPipeline.new (
+  text_filters: [HTMLPipeline::TextFilter::ImageMaxWidthFilter.new],
+  convert_filter: [HTMLPipeline::ConvertFilter::MarkdownFilter.new],
+  node_filters: [
+    HTMLPipeline::NodeFilter::HttpsFilter.new,HTMLPipeline::NodeFilter::MentionFilter.new,
+  ], context: context)
 
 # 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
+HtmlEmailPipeline = HTMLPipeline.new(
+  text_filters: [
+    PlainTextInputFilter.new,
+    ImageMaxWidthFilter.new
+  ], {})
 ```
 
 ## Filters
 
-* `MentionFilter` - replace `@user` mentions with links
-* `TeamMentionFilter` - replace `@org/team` 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` - allow 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
+### TextFilters
 
-## Dependencies
+`TextFilter`s must define a method named `call` which is called on the text. `@text`, `@config`, and `@result` are available to use, and any changes made to these ivars are passed on to the next filter.
+
+- `ImageFilter` - converts image `url` into `<img>` tag
+- `PlainTextInputFilter` - html escape text and wrap the result in a `<div>`
 
-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:
+### ConvertFilter
+
+The `ConvertFilter` takes text and turns it into HTML. `@text`, `@config`, and `@result` are available to use. `ConvertFilter` must defined a method named `call`, taking one argument, `text`. `call` must return a string representing the new HTML document.
+
+- `MarkdownFilter` - creates HTML from text using [Commonmarker](https://www.github.com/gjtorikian/commonmarker)
+
+### Sanitization
+
+Because the web can be a scary place, HTML is automatically sanitized after the `ConvertFilter` runs and before the `NodeFilter`s are processed. This is to prevent malicious or unexpected input from entering the pipeline.
+
+The sanitization process takes a hash configuration of settings. See the [Selma](https://www.github.com/gjtorikian/selma) documentation for more information on how to configure these settings.
+
+A default sanitization config is provided by this library (`HTMLPipeline::SanitizationFilter::DEFAULT_CONFIG`). A sample custom sanitization allowlist might look like this:
 
 ```ruby
-gem 'rouge'
+ALLOWLIST = {
+  elements: ["p", "pre", "code"]
+}
+
+pipeline = HTMLPipeline.new \
+  text_filters: [
+    HTMLPipeline::MarkdownFilter,
+  ],
+  convert_filter: [HTMLPipeline::ConvertFilter::MarkdownFilter.new],
+  sanitization_config: ALLOWLIST
+
+result = pipeline.call <<-CODE
+This is *great*:
+
+    some_code(:first)
+
+CODE
+result[:output].to_s
 ```
 
-* `AutolinkFilter` - `rinku`
-* `EmailReplyFilter` - `escape_utils`, `email_reply_parser`
-* `EmojiFilter` - `gemoji`
-* `MarkdownFilter` - `commonmarker`
-* `PlainTextInputFilter` - `escape_utils`
-* `SanitizationFilter` - `sanitize`
-* `SyntaxHighlightFilter` - `rouge`
-* `TableOfContentsFilter` - `escape_utils`
-* `TextileFilter` - `RedCloth`
+This would print:
 
-_Note:_ See [Gemfile](/Gemfile) `:test` block for version requirements.
+```html
+<p>This is great:</p>
+<pre><code>some_code(:first)
+</code></pre>
+```
 
-## Documentation
+Sanitization can be disabled if and only if `nil` is explicitly passed as
+the config:
 
-Full reference documentation can be [found here](http://rubydoc.info/gems/html-pipeline/frames).
+```ruby
+pipeline = HTMLPipeline.new \
+  text_filters: [
+    HTMLPipeline::MarkdownFilter,
+  ],
+  convert_filter: [HTMLPipeline::ConvertFilter::MarkdownFilter.new],
+  sanitization_config: nil
+```
+
+For more examples of customizing the sanitization process to include the tags you want, check out [the tests](test/sanitization_filter_test.rb) and [the FAQ](#faq).
 
-## Extending
-To write a custom filter, you need a class with a `call` method that inherits
-from `HTML::Pipeline::Filter`.
+### NodeFilters
 
-For example this filter adds a base url to images that are root relative:
+`NodeFilters`s can operate either on HTML elements or text nodes using CSS selectors. Each `NodeFilter` must define a method named `selector` which provides an instance of `Selma::Selector`. If elements are being manipulated, `handle_element` must be defined, taking one argument, `element`; if text nodes are being manipulated, `handle_text_chunk` must be defined, taking one argument, `text_chunk`. `@config`, and `@result` are available to use, and any changes made to these ivars are passed on to the next filter.
+
+`NodeFilter` also has an optional method, `after_initialize`, which is run after the filter initializes. This can be useful in setting up a custom state for `result` to take advantage of.
+
+Here's an example `NodeFilter` that adds a base url to images that are root relative:
 
 ```ruby
 require 'uri'
 
-class RootRelativeFilter < HTML::Pipeline::Filter
+class RootRelativeFilter < HTMLPipeline::NodeFilter
 
-  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
+  SELECTOR = Selma::Selector.new(match_element: "img")
+
+  def selector
+    SELECTOR
   end
 
+  def handle_element(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
 end
 ```
 
-Now this filter can be used in a pipeline:
+For more information on how to write effective `NodeFilter`s, refer to the provided filters, and see the underlying lib, [Selma](https://www.github.com/gjtorikian/selma) for more information.
 
-```ruby
-Pipeline.new [ RootRelativeFilter ], { :base_url => 'http://somehost.com' }
-```
+- `AbsoluteSourceFilter` - replace relative image urls with fully qualified versions
+- `EmojiFilter` - converts `:<emoji>:` to [emoji](http://www.emoji-cheat-sheet.com/)!
+- `HttpsFilter` - Replacing http urls with https versions
+- `ImageMaxWidthFilter` - link to full size image for large images
+- `MentionFilter` - replace `@user` mentions with links
+- `SanitizationFilter` - allow sanitize user markup
+- `TableOfContentsFilter` - anchor headings with name attributes and generate Table of Contents html unordered list linking headings
+- `TeamMentionFilter` - replace `@org/team` mentions with links
 
-### 3rd Party Extensions
+## Dependencies
 
-If you have an idea for a filter, propose it as
-[an issue](https://github.com/jch/html-pipeline/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.
+Since filters can be customized to your heart's content, gem dependencies are _not_ bundled; this project doesn't know which of the default filters you might use, and as such, you must bundle each filter's gem
+dependencies yourself.
 
-Here are some extensions people have built:
+> **Note**
+> See the [Gemfile](/Gemfile) `:test` group for any version requirements.
 
-* [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 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
+When developing a custom filter, call `HTMLPipeline.require_dependency` at the start to ensure that the local machine has the necessary dependency. You can also use `HTMLPipeline.require_dependencies` to provide a list of dependencies to check.
 
+## Documentation
+
+Full reference documentation can be [found here](http://rubydoc.info/gems/html-pipeline/frames).
 
 ## Instrumenting
 
@@ -263,107 +259,102 @@ 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.
+`HTMLPipeline.default_instrumentation_service` object.
 
-``` ruby
+```ruby
 # the AS::Notifications-compatible service object
 service = ActiveSupport::Notifications
 
 # instrument a specific pipeline
-pipeline = HTML::Pipeline.new [MarkdownFilter], context
+pipeline = HTMLPipeline.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
+HTMLPipeline.default_instrumentation_service = service
+pipeline = HTMLPipeline.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
+`call_filter.html_pipeline` event is published once any filter finishes; `call_text_filters`
+and `call_node_filters` is published when all of the text and node filters are finished, respectively.
+The `payload` should include the `filter` name. Each filter will trigger its own
 instrumentation call.
 
-``` ruby
+```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
+  payload[:result][:output] #=> output HTML String
 end
 ```
 
 The full pipeline is also instrumented:
 
-``` ruby
-service.subscribe "call_pipeline.html_pipeline" do |event, start, ending, transaction_id, payload|
+```ruby
+service.subscribe "call_text_filters.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[:doc] #=> HTML String
   payload[:context] #=> context Hash
   payload[:result] #=> instance of result class
-  payload[:result][:output] #=> output HTML String or Nokogiri::DocumentFragment
+  payload[:result][:output] #=> output HTML String
 end
 ```
 
+## Third Party Extensions
+
+If you have an idea for a filter, propose it as
+[an issue](https://github.com/gjtorikian/html-pipeline/issues) first. This allows us to 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 HTMLPipeline 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 used by GitLab
+- [html-pipeline-youtube](https://github.com/st0012/html-pipeline-youtube) - An HTMLPipeline filter for YouTube links
+- [html-pipeline-flickr](https://github.com/st0012/html-pipeline-flickr) - An HTMLPipeline filter for Flickr links
+- [html-pipeline-vimeo](https://github.com/dlackty/html-pipeline-vimeo) - An HTMLPipeline filter for Vimeo links
+- [html-pipeline-hashtag](https://github.com/mr-dxdy/html-pipeline-hashtag) - An HTMLPipeline filter for hashtags
+- [html-pipeline-linkify_github](https://github.com/jollygoodcode/html-pipeline-linkify_github) - An HTMLPipeline 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 HTMLPipeline
+- [korgi](https://github.com/jodeci/korgi) - HTMLPipeline filters for links to Rails resources
+
 ## 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,
+at the end of your `text_filter`s config . 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
-```
+yourself.
 
 ### 2. How do I customize an allowlist for `SanitizationFilter`s?
 
-`SanitizationFilter::ALLOWLIST` is the default allowlist used if no `:allowlist`
-argument is given in the context. The default is a good starting template for
+`HTMLPipeline::SanitizationFilter::ALLOWLIST` is the default allowlist used if no `sanitization_config`
+argument is given. 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
+re-define your own config and pass that in, such as:
 
-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).
+```ruby
+config = HTMLPipeline::SanitizerFilter::DEFAULT_CONFIG.dup
+config[:elements] << "iframe" # sure, whatever you want
+```
 
 ### 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/).
-
-The current maintainer is @gjtorikian
-
-### Releasing A New Version
-
-This section is for gem maintainers to cut a new version of the gem.
+Thanks to all of [these contributors](https://github.com/gjtorikian/html-pipeline/graphs/contributors).
 
-* 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`
+This project is a member of the [OSS Manifesto](http://ossmanifesto.org/).

data/Rakefile

@@ -1,17 +1,24 @@
 #!/usr/bin/env rake
 # frozen_string_literal: true
 
-require 'rubygems'
-require 'bundler/setup'
-
-require 'bundler/gem_tasks'
-require 'rake/testtask'
+require "bundler/gem_tasks"
+require "rubygems/package_task"
+require "rake/testtask"
 
 Rake::TestTask.new do |t|
-  t.libs << 'test'
-  t.test_files = FileList['test/**/*_test.rb']
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_test.rb"]
   t.verbose = true
   t.warning = false
 end
 
 task default: :test
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new(:rubocop)
+
+GEMSPEC = Bundler.load_gemspec("html-pipeline.gemspec")
+gem_path = Gem::PackageTask.new(GEMSPEC).define
+desc "Package the ruby gem"
+task "package" => [gem_path]

data/UPGRADING.md

@@ -0,0 +1,35 @@
+# Upgrade Guide
+
+## From v2 to v3
+
+HTMLPipeline v3 is a massive improvement over this still much loved (and woefully under-maintained) project. This section will attempt to list all of the breaking changes between the two versions and provide suggestions on how to upgrade.
+
+### Changed namespace
+
+This project is now under a module called `HTMLPipeline`, not `HTML::Pipeline`.
+
+### Removed filters
+
+The following filters were removed:
+
+- `AutolinkFilter`: this is handled by [Commonmarker](https://www.github.com/gjtorikian/commonmarker) and can be disabled/enabled through the `MarkdownFilter`'s `context` hash
+- `SyntaxHighlightFilter`: this is handled by [Commonmarker](https://www.github.com/gjtorikian/commonmarker) and can be disabled/enabled through the `MarkdownFilter`'s `context` hash
+- `SanitizationFilter`: this is handled by [Selma](https://www.github.com/gjtorikian/selma); configuration can be done through the `sanitization_config` hash
+
+- `EmailReplyFilter`
+- `CamoFilter`
+- `TextFilter`
+
+### Changed API
+
+The new way to call this project is as follows:
+
+```ruby
+HTMLPipeline.new(
+    text_filters: [], # array of instantiated (`.new`ed) `HTMLPipeline::TextFilter`
+    convert_filter:, # a filter that runs to turn text into HTML
+    sanitization_config: {}, # an allowlist of elements/attributes/protocols to keep
+    node_filters: []) # array of instantiated (`.new`ed) `HTMLPipeline::NodeFilter`
+```
+
+Please refer to the README for more information on constructing filters. In most cases, the underlying filter needs only a few changes, primarily to make use of [Selma](https://www.github.com/gjtorikian/selma) rather than Nokogiri.