1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
GitHub Markup
=============
We use this library on GitHub when rendering your README or any other
rich text file.
Markups
-------
The following markups are supported. The dependencies listed are required if
you wish to run the library. You can also run `script/bootstrap` to fetch them all.
* [.markdown, .mdown, .md](http://daringfireball.net/projects/markdown/) -- `gem install redcarpet` (https://github.com/vmg/redcarpet)
* [.textile](http://www.textism.com/tools/textile/) -- `gem install RedCloth`
* [.rdoc](http://rdoc.sourceforge.net/) -- `gem install rdoc -v 3.6.1`
* [.org](http://orgmode.org/) -- `gem install org-ruby`
* [.creole](http://wikicreole.org/) -- `gem install creole`
* [.mediawiki](http://www.mediawiki.org/wiki/Help:Formatting) -- `gem install wikicloth`
* [.rst](http://docutils.sourceforge.net/rst.html) -- `easy_install docutils`
* [.asciidoc, .adoc, .asc](http://asciidoc.org/) -- `gem install asciidoctor` (http://asciidoctor.org)
* [.pod](http://search.cpan.org/dist/perl/pod/perlpod.pod) -- `Pod::Simple::HTML`
comes with Perl >= 5.10. Lower versions should install Pod::Simple from CPAN.
HTML sanitization
-----------------
HTML rendered by the various markup language processors gets passed through an [HTML sanitization filter](https://github.com/jch/html-pipeline/blob/master/lib/html/pipeline/sanitization_filter.rb) for security reasons. HTML elements not in the whitelist are removed. HTML attributes not in the whitelist are removed from the preserved elements.
The following HTML elements, organized by category, are whitelisted:
* Headings: h1, h2, h3, h4, h5, h6, h7, h8
* Prose: p, div, blockquote
* Preformatted: pre
* Inline: b, i, strong, em, tt, code, ins, del, sup, sub, kbd, samp, q, var
* Lists: ol, ul, li, dl, dt, dd
* Tables: table, thead, tbody, tfoot, tr, td, th
* Breaks: br, hr
* Ruby (East Asian): ruby, rt, rp
The following attributes, organized by element, are whitelisted:
* a: href (http://, https://, mailto://, github-windows:// and github-mac:// URI schemes and relative paths only)
* img: src (http:// and https::// URI schemes and relative paths only)
* div: itemscope, itemtype
* all: abbr, accept, accept-charset, accesskey, action, align, alt, axis, border, cellpadding, cellspacing, char, charoff, charset, checked, cite, clear, cols, colspan, color, compact, coords, datetime, dir, disabled, enctype, for, frame, headers, height, hreflang, hspace, ismap, label, lang, longdesc, maxlength, media, method, multiple, name, nohref, noshade, nowrap, prompt, readonly, rel, rev, rows, rowspan, rules, scope, selected, shape, size, span, start, summary, tabindex, target, title, type, usemap, valign, value, vspace, width, itemprop
Note that the id attribute is *not* whitelisted.
Contributing
------------
Want to contribute? Great! There are two ways to add markups.
### Commands
If your markup is in a language other than Ruby, drop a translator
script in `lib/github/commands` which accepts input on STDIN and
returns HTML on STDOUT. See [rest2html][r2h] for an example.
Once your script is in place, edit `lib/github/markups.rb` and tell
GitHub Markup about it. Again we look to [rest2html][r2hc] for
guidance:
command(:rest2html, /re?st(.txt)?/)
Here we're telling GitHub Markup of the existence of a `rest2html`
command which should be used for any file ending in `rest`,
`rst`, `rest.txt` or `rst.txt`. Any regular expression will do.
Finally add your tests. Create a `README.extension` in `test/markups`
along with a `README.extension.html`. As you may imagine, the
`README.extension` should be your known input and the
`README.extension.html` should be the desired output.
Now run the tests: `rake`
If nothing complains, congratulations!
### Classes
If your markup can be translated using a Ruby library, that's
great. Check out `lib/github/markups.rb` for some
examples. Let's look at Markdown:
markup(:markdown, /md|mkdn?|markdown/) do |content|
Markdown.new(content).to_html
end
We give the `markup` method three bits of information: the name of the
file to `require`, a regular expression for extensions to match, and a
block to run with unformatted markup which should return HTML.
If you need to monkeypatch a RubyGem or something, check out the
included RDoc example.
Tests should be added in the same manner as described under the
`Commands` section.
Installation
-----------
gem install github-markup
Usage
-----
require 'github/markup'
GitHub::Markup.render('README.markdown', "* One\n* Two")
Or, more realistically:
require 'github/markup'
GitHub::Markup.render(file, File.read(file))
Testing
-------
To run the tests:
$ rake
To add tests see the `Commands` section earlier in this
README.
Contributing
------------
1. Fork it.
2. Create a branch (`git checkout -b my_markup`)
3. Commit your changes (`git commit -am "Added Snarkdown"`)
4. Push to the branch (`git push origin my_markup`)
5. Open a [Pull Request][1]
6. Enjoy a refreshing Diet Coke and wait
[r2h]: lib/github/commands/rest2html
[r2hc]: lib/github/markups.rb#L51
[1]: http://github.com/github/markup/pulls
|
