1GitHub Markup
  2=============
  3
  4We use this library on GitHub when rendering your README or any other
  5rich text file.
  6
  7Markups
  8-------
  9
 10* .markdown - `gem install markdown`
 11* .textile - `gem install RedCloth`
 12* .rdoc
 13* .org - `gem install org-mode`
 14* .rst - `easy_install docutils`
 15* .asciidoc - `brew install asciidoc`
 16* .pod - `Pod::Simple::HTML` should come with Perl
 17* .1 - Requires `groff`
 18
 19
 20Contributing
 21------------
 22
 23Want to contribute? Great! There are two ways to add markups.
 24
 25
 26### Commands
 27
 28If your markup is in a language other than Ruby, drop a translator
 29script in `lib/github/commands` which accepts input on STDIN and
 30returns HTML on STDOUT. See [rest2html][r2h] for an example.
 31
 32Once your script is in place, edit `lib/github/markups.rb` and tell
 33GitHub Markup about it. Again we look to [rest2html][r2hc] for
 34guidance:
 35
 36    command(:rest2html, /re?st(.txt)?/)
 37
 38Here we're telling GitHub Markup of the existence of a `rest2html`
 39command which should be used for any file ending in `rest`,
 40`rst`, `rest.txt` or `rst.txt`. Any regular expression will do.
 41
 42Finally add your tests. Create a `README.extension` in `test/markups`
 43along with a `README.extension.html`. As you may imagine, the
 44`README.extension` should be your known input and the
 45`README.extension.html` should be the desired output.
 46
 47Now run the tests: `rake`
 48
 49If nothing complains, congratulations!
 50
 51
 52### Classes
 53
 54If your markup can be translated using a Ruby library, that's
 55great. Check out Check `lib/github/markups.rb` for some
 56examples. Let's look at Markdown:
 57
 58    markup(:markdown, /md|mkdn?|markdown/) do |content|
 59      Markdown.new(content).to_html
 60    end
 61
 62We give the `markup` method three bits of information: the name of the
 63file to `require`, a regular expression for extensions to match, and a
 64block to run with unformatted markup which should return HTML.
 65
 66If you need to monkeypatch a RubyGem or something, check out the
 67included RDoc example.
 68
 69Tests should be added in the same manner as described under the
 70`Commands` section.
 71
 72
 73Installation
 74-----------
 75
 76    gem install github-markup
 77
 78
 79Usage
 80-----
 81
 82    require 'github/markup'
 83    GitHub::Markup.render('README.markdown', "* One\n* Two")
 84
 85Or, more realistically:
 86
 87    require 'github/markup'
 88    GitHub::Markup.render(file, File.read(file))
 89
 90
 91Testing
 92-------
 93
 94To run the tests:
 95
 96    $ rake
 97
 98To add tests see the `Commands` section earlier in this
 99README.
100
101
102Contributing
103------------
104
1051. Fork it.
1062. Create a branch (`git checkout -b my_markup`)
1073. Commit your changes (`git commit -am "Added Snarkdown"`)
1084. Push to the branch (`git push origin my_markup`)
1095. Create an [Issue][1] with a link to your branch
1106. Enjoy a refreshing Diet Coke and wait
111
112
113[r2h]: http://github.com/defunkt/github-markup/tree/master/lib/github/commands/rest2html
114[r2hc]: http://github.com/defunkt/github-markup/tree/master/lib/github/markups.rb#L13
115[1]: http://github.com/defunkt/github-markup/issues