We use this library on GitHub when rendering your README or any other rich text file.
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 --
gem install redcarpet(https://github.com/vmg/redcarpet)
- .textile --
gem install RedCloth
- .rdoc --
gem install rdoc -v 3.6.1
- .org --
gem install org-ruby
- .creole --
gem install creole
- .mediawiki --
gem install wikicloth
- .rst --
- .asciidoc, .adoc, .asc --
gem install asciidoctor(http://asciidoctor.org)
- .pod --
Pod::Simple::HTMLcomes with Perl >= 5.10. Lower versions should install Pod::Simple from CPAN.
HTML rendered by the various markup language processors gets passed through an HTML sanitization filter 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.
Want to contribute? Great! There are two ways to add markups.
If your markup is in a language other than Ruby, drop a translator
lib/github/commands which accepts input on STDIN and
returns HTML on STDOUT. See rest2html 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 for
Here we're telling GitHub Markup of the existence of a
command which should be used for any file ending in
rst.txt. Any regular expression will do.
Finally add your tests. Create a
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:
If nothing complains, congratulations!
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
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
gem install github-markup
require 'github/markup' GitHub::Markup.render('README.markdown', "* One\n* Two")
Or, more realistically:
require 'github/markup' GitHub::Markup.render(file, File.read(file))
To run the tests:
To add tests see the
Commands section earlier in this
- Fork it.
- Create a branch (
git checkout -b my_markup)
- Commit your changes (
git commit -am "Added Snarkdown")
- Push to the branch (
git push origin my_markup)
- Open a Pull Request
- Enjoy a refreshing Diet Coke and wait