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.
Add this line to your application's Gemfile:
gem 'html-pipeline'
And then execute:
$ bundle
Or install it yourself as:
$ gem install html-pipeline
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
MentionFilter
- replace@user
mentions with linksAutoLinkFilter
- auto_linking urls in HTMLCamoFilter
- replace http image urls with camo-fied https versionsEmailReplyFilter
- util filter for working with emailsEmojiFilter
- everyone loves emoji!HttpsFilter
- HTML Filter for replacing http github urls with https versions.ImageMaxWidthFilter
- link to full size image for large imagesMarkdownFilter
- convert markdown to htmlPlainTextInputFilter
- html escape text and wrap the result in a divSanitizationFilter
- whitelist santize user markupSyntaxHighlightFilter
- code syntax highlighter with linguistTextileFilter
- convert textile to htmlTableOfContentsFilter
- anchor headings with name attributes
We define different pipelines for different parts of our app. Here are a few paraphrased snippets to get you started:
# 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
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 [
ImageMaxWidthFilter
], {}, {}
# Just emoji.
EmojiPipeline = Pipeline.new [
HTMLInputFilter,
EmojiFilter
], context, {}
To see what has changed in recent versions, see the CHANGELOG.
bundle
rake test
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Added some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request
- test whether emoji filter works on heroku
- test whether nokogiri monkey patch is still necessary
- Aman Gupta
- Jake Boxer
- Joshua Peek
- Kyle Neath
- Rob Sanheim
- Simon Rozet
- Vicent Martí
- Risk :danger: Olson
Project is a member of the OSS Manifesto.