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.
.markdown, .mdown,
.md – gem install redcarpet
(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 –
easy_install docutils
.asciidoc – brew
install asciidoc
.pod –
Pod::Simple::HTML
comes with Perl >= 5.10. Lower versions
should install Pod::Simple from CPAN.
Want to contribute? Great! There are two ways to add markups.
If your markup is in a language other than Ruby, drop a translator script
in 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 guidance:
command(:rest2html, /re?st(.txt)?/)
Here we're telling GitHub Markup of the
existence of a rest2html
command which should be used for any
file ending in rest
, rst
, rest.txt
or rst.txt
. Any regular expression will do.
Finally add your tests. Create a README.extension
in
test/markups
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: rake
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 file to 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
Commands
section.
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:
$ rake
To add tests see the Commands
section earlier in this README.
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