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