1GitHub Markup
 2=============
 3
 4We use this library on GitHub when rendering your README or any other
 5rich text file.
 6
 7Want to contribute? Great! There are two ways to add markups.
 8
 9
10### Commands
11
12If your markup is in a language other than Ruby, drop a translator
13script in `lib/github/commands` which accepts input on STDIN and
14returns HTML on STDOUT. See [rest2html][r2h] for an example.
15
16Once your script is in place, edit `lib/github/markups.rb` and tell
17GitHub Markup about it. Again we look to [rest2html][r2hc] for
18guidance:
19
20    command(:rest2html, /rest|rst/)
21
22Here we're telling GitHub Markup of the existence of a `rest2html`
23command which should be used for any file ending in `rest` or
24`rst`. Any regular expression will do.
25
26Finally add your tests. Create a `README.extension` in `test/markups`
27along with a `README.extension.html`. As you may imagine, the
28`README.extension` should be your known input and the
29`README.extension.html` should be the desired output.
30
31Now run the tests: `rake`
32
33If nothing complains, congratulations!
34
35
36### Classes
37
38If your markup can be translated using a Ruby library, that's
39great. Check out Check `lib/github/markups.rb` for some
40examples. Let's look at Markdown:
41
42    markup(:markdown, /md|mkdn?|markdown/) do |content|
43      Markdown.new(content).to_html
44    end
45
46We give the `markup` method three bits of information: the name of the
47file to `require`, a regular expression for extensions to match, and a
48block to run with unformatted markup which should return HTML.
49
50If you need to monkeypatch a RubyGem or something, check out the
51included RDoc example.
52
53Tests should be added in the same manner as described under the
54`Commands` section.
55
56
57Usage
58-----
59
60    require 'github/markup'
61    GitHub::Markup.render('README.markdown', "* One\n* Two")
62
63Or, more realistically:
64
65    require 'github/markup'
66    GitHub::Markup.render(file, File.read(file))
67
68
69Contributing
70------------
71
721. Fork it.
732. Create a branch
743. Commit your changes
754. Push to the branch
765. Create an [Issue][1] with a link to your branch
776. Enjoy a refreshing Diet Coke and wait
78
79
80[r2h]: http://github.com/defunkt/github_markup/tree/master/lib/github/commands/rest2html
81[r2hc]: http://github.com/defunkt/github_markup/tree/master/lib/github/markups.rb#L13
82[1]: http://github.com/defunkt/github_markup/issues