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.

Installation

Add this line to your application's Gemfile:

gem 'html-pipeline'

And then execute:

$ bundle

Or install it yourself as:

$ 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.

For example, to transform Markdown source into Markdown HTML:

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:

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:

<p>This is <em>great</em>:</p>

<div class="highlight">
<pre><span class="n">some_code</span><span class="p">(</span><span class="ss">:first</span><span class="p">)</span>
</pre>
</div>

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 want don't want to use GitHub formatted Markdown, you can pass an option in the context hash:

filter = HTML::Pipeline::MarkdownFilter.new("Hi **world**!", :gfm => false)
filter.call

Filters

• MentionFilter - replace @user mentions with links
• AutoLinkFilter - auto_linking urls in HTML
• CamoFilter - replace http image urls with camo-fied https versions
• EmailReplyFilter - util filter for working with emails
• EmojiFilter - everyone loves emoji!
• 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 santize user markup
• SyntaxHighlightFilter - code syntax highlighter with linguist
• TextileFilter - convert textile to html
• TableOfContentsFilter - anchor headings with name attributes

Development Setup

bundle
rake test

Contributing

1. Fork it
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

TODO

• test whether emoji filter works on heroku
• test whether nokogiri monkey patch is still necessary

Contributors

• Aman Gupta
• Jake Boxer
• Joshua Peek
• Kyle Neath
• Rob Sanheim
• Simon Rozet
• Vicent Martí
• Risk :danger: Olson