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
 57Installation
 58-----------
 59
 60    gem install github-markup
 61    gem install org-ruby
 62
 63
 64Usage
 65-----
 66
 67    require 'github/markup'
 68    GitHub::Markup.render('README.markdown', "* One\n* Two")
 69
 70Or, more realistically:
 71
 72    require 'github/markup'
 73    GitHub::Markup.render(file, File.read(file))
 74
 75
 76Testing
 77-------
 78
 79To run the tests:
 80
 81    $ rake
 82
 83To add tests see the `Commands` section earlier in this 
 84README.
 85
 86
 87Contributing
 88------------
 89
 901. Fork it.
 912. Create a branch
 923. Commit your changes
 934. Push to the branch
 945. Create an [Issue][1] with a link to your branch
 956. Enjoy a refreshing Diet Coke and wait
 96
 97
 98[r2h]: http://github.com/defunkt/github-markup/tree/master/lib/github/commands/rest2html
 99[r2hc]: http://github.com/defunkt/github-markup/tree/master/lib/github/markups.rb#L13
100[1]: http://github.com/defunkt/github-markup/issues