rgrove / sanitize
watch download tarball
public
Forks16Right
Watchers252Right
Description: Whitelist-based Ruby HTML sanitizer.
Homepage: http://rgrove.github.com/sanitize/
Clone URL: git://github.com/rgrove/sanitize.git
sanitize / README.rdoc
raw normal view history
50cdcf2c » rgrove 2008-12-24 Initial commit. 1 = Sanitize
2
3 Sanitize is a whitelist-based HTML sanitizer. Given a list of acceptable
4 elements and attributes, Sanitize will remove all unacceptable HTML from a
5 string.
6
7 Using a simple configuration syntax, you can tell Sanitize to allow certain
8 elements, certain attributes within those elements, and even certain URL
9 protocols within attributes that contain URLs. Any HTML elements or attributes
10 that you don't explicitly allow will be removed.
11
12 Because it's based on Hpricot, a full-fledged HTML parser, rather than a bunch
13 of fragile regular expressions, Sanitize has no trouble dealing with malformed
14 or maliciously-formed HTML. When in doubt, Sanitize always errs on the side of
15 caution.
16
17 *Author*:: Ryan Grove (mailto:ryan@wonko.com)
5d01e561 » rgrove 2009-04-23 Release 1.0.8 18 *Version*:: 1.0.8 (2009-04-23)
77c428a5 » rgrove 2009-01-01 Happy New Year! 19 *Copyright*:: Copyright (c) 2009 Ryan Grove. All rights reserved.
50cdcf2c » rgrove 2008-12-24 Initial commit. 20 *License*:: MIT License (http://opensource.org/licenses/mit-license.php)
21 *Website*:: http://github.com/rgrove/sanitize
22
23 == Requires
24
25 * RubyGems
26 * Hpricot 0.6+
27
28 == Usage
29
30 If you don't specify any configuration options, Sanitize will use its strictest
31 settings by default, which means it will strip all HTML.
32
33 require 'rubygems'
34 require 'sanitize'
35
36 html = '<b><a href="http://foo.com/">foo</a></b><img src="http://foo.com/bar.jpg" />'
37
38 Sanitize.clean(html) # => 'foo'
39
40 == Configuration
41
42 In addition to the ultra-safe default settings, Sanitize comes with three other
43 built-in modes.
44
45 === Sanitize::Config::RESTRICTED
46
47 Allows only very simple inline formatting markup. No links, images, or block
48 elements.
49
50 Sanitize.clean(html, Sanitize::Config::RESTRICTED) # => '<b>foo</b>'
51
52 === Sanitize::Config::BASIC
53
54 Allows a variety of markup including formatting tags, links, and lists. Images
55 and tables are not allowed, links are limited to FTP, HTTP, HTTPS, and mailto
56 protocols, and a <code>rel="nofollow"</code> attribute is added to all links to
57 mitigate SEO spam.
58
59 Sanitize.clean(html, Sanitize::Config::BASIC)
60 # => '<b><a href="http://foo.com/" rel="nofollow">foo</a></b>'
61
62 === Sanitize::Config::RELAXED
63
64 Allows an even wider variety of markup than BASIC, including images and tables.
65 Links are still limited to FTP, HTTP, HTTPS, and mailto protocols, while images
66 are limited to HTTP and HTTPS. In this mode, <code>rel="nofollow"</code> is not
67 added to links.
68
69 Sanitize.clean(html, Sanitize::Config::RELAXED)
70 # => '<b><a href="http://foo.com/">foo</a></b><img src="http://foo.com/bar.jpg" />'
71
72 === Custom Configuration
73
74 If the built-in modes don't meet your needs, you can easily specify a custom
75 configuration:
76
77 Sanitize.clean(html, :elements => ['a', 'span'],
78 :attributes => {'a' => ['href', 'title'], 'span' => ['class']},
79 :protocols => {'a' => {'href' => ['http', 'https', 'mailto']}})
80
81 ==== :elements
82
83 Array of element names to allow. Specify all names in lowercase.
84
85 :elements => [
86 'a', 'b', 'blockquote', 'br', 'cite', 'code', 'dd', 'dl', 'dt', 'em',
87 'i', 'li', 'ol', 'p', 'pre', 'q', 'small', 'strike', 'strong', 'sub',
88 'sup', 'u', 'ul'
89 ]
90
91 ==== :attributes
92
93 Attributes to allow for specific elements. Specify all element names and
94 attributes in lowercase.
95
96 :attributes => {
97 'a' => ['href', 'title'],
98 'blockquote' => ['cite'],
99 'img' => ['alt', 'src', 'title']
100 }
101
c0495a85 » rgrove 2009-02-14 Use :all instead of '*' to ... 102 If you'd like to allow certain attributes on all elements, use the symbol
103 <code>:all</code> instead of an element name.
104
105 :attributes => {
106 :all => ['class'],
31fd7e30 » rgrove 2009-02-14 Fix stray comma. 107 'a' => ['href', 'title']
c0495a85 » rgrove 2009-02-14 Use :all instead of '*' to ... 108 }
109
50cdcf2c » rgrove 2008-12-24 Initial commit. 110 ==== :add_attributes
111
112 Attributes to add to specific elements. If the attribute already exists, it will
113 be replaced with the value specified here. Specify all element names and
114 attributes in lowercase.
115
116 :add_attributes => {
117 'a' => {'rel' => 'nofollow'}
118 }
119
120 ==== :protocols
121
122 URL protocols to allow in specific attributes. If an attribute is listed here
123 and contains a protocol other than those specified (or if it contains no
124 protocol at all), it will be removed.
125
126 :protocols => {
127 'a' => {'href' => ['ftp', 'http', 'https', 'mailto']},
128 'img' => {'src' => ['http', 'https']}
129 }
130
5682777c » rgrove 2008-12-28 You can now specify :relati... 131 If you'd like to allow the use of relative URLs which don't have a protocol,
c0495a85 » rgrove 2009-02-14 Use :all instead of '*' to ... 132 include the symbol <code>:relative</code> in the protocol array:
5682777c » rgrove 2008-12-28 You can now specify :relati... 133
134 :protocols => {
135 'a' => {'href' => ['http', 'https', :relative]}
136 }
137
91d22e46 » rgrove 2009-02-14 Add list of contributors. 138
139 == Contributors
140
141 The following lovely people have contributed to Sanitize in the form of patches
142 or ideas that later became code:
143
00ed7c12 » rgrove 2009-05-19 Update history, bump gemspe... 144 * Peter Cooper <git@peterc.org>
91d22e46 » rgrove 2009-02-14 Add list of contributors. 145 * Ryan Grove <ryan@wonko.com>
11ae498e » rgrove 2009-02-14 Whoops, forgot one. 146 * Adam Hooper <adam@adamhooper.com>
91d22e46 » rgrove 2009-02-14 Add list of contributors. 147 * Mutwin Kraus <mutle@blogage.de>
148 * Dev Purkayastha <dev.purkayastha@gmail.com>
71238c18 » rgrove 2009-04-23 Work around an Hpricot bug ... 149 * Ben Wanicur <bwanicur@verticalresponse.com>
91d22e46 » rgrove 2009-02-14 Add list of contributors. 150
50cdcf2c » rgrove 2008-12-24 Initial commit. 151 == License
152
ad7b4839 » rgrove 2009-01-01 Release 1.0.1 153 Copyright (c) 2009 Ryan Grove <ryan@wonko.com>
50cdcf2c » rgrove 2008-12-24 Initial commit. 154
155 Permission is hereby granted, free of charge, to any person obtaining a copy of
156 this software and associated documentation files (the 'Software'), to deal in
157 the Software without restriction, including without limitation the rights to
158 use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
159 the Software, and to permit persons to whom the Software is furnished to do so,
160 subject to the following conditions:
161
162 The above copyright notice and this permission notice shall be included in all
163 copies or substantial portions of the Software.
164
165 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
166 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
167 FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
168 COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
169 IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
170 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.