The code we use to render README.your_favorite_markup
Python Ruby Perl
Pull request Compare This branch is 3 commits ahead, 461 commits behind github:master.
Failed to load latest commit information.
bin $ github-markup Mar 11, 2010
lib/github support for creole Jul 5, 2010
test support for creole Jul 5, 2010
.gitignore always pyc Oct 31, 2009
.kick add .kick, i love it Oct 31, 2009 v0.4.0 Apr 23, 2010
LICENSE license Oct 31, 2009 update with creole details Jul 5, 2010
Rakefile superfluous require Jan 10, 2010

GitHub Markup

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 -- gem install rdiscount
  • .textile -- gem install RedCloth
  • .creole -- easy_install creole
  • .rdoc
  • .org -- gem install org-ruby
  • .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.
  • .1 - Requires groff


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 Check lib/github/markups.rb for some examples. Let's look at Markdown:

markup(:markdown, /md|mkdn?|markdown/) do |content|

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'


To run the tests:

$ rake

To add tests see the Commands section earlier in this README.


  1. Fork it.
  2. Create a branch (git checkout -b my_markup)
  3. Commit your changes (git commit -am "Added Snarkdown")
  4. Push to the branch (git push origin my_markup)
  5. Create an Issue with a link to your branch
  6. Enjoy a refreshing Diet Coke and wait