Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
The code we use to render README.your_favorite_markup
Ruby Python Shell

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
bin
lib/github
test
.gitignore
.kick
HISTORY.md
LICENSE
README.md
Rakefile

README.md

GitHub Markup

We use this library on GitHub when rendering your README or any other rich text file.

Markups

  • .markdown - gem install markdown
  • .textile - gem install RedCloth
  • .rdoc
  • .org - gem install org-mode
  • .rst - easy_install docutils
  • .asciidoc - brew install asciidoc
  • .pod - Pod::Simple::HTML should come with Perl
  • .1 - Requires groff

Contributing

Want to contribute? Great! There are two ways to add markups.

Commands

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!

Classes

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|
  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.

Installation

gem install github-markup

Usage

require 'github/markup'
GitHub::Markup.render('README.markdown', "* One\n* Two")

Or, more realistically:

require 'github/markup'
GitHub::Markup.render(file, File.read(file))

Testing

To run the tests:

$ rake

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

Contributing

  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
Something went wrong with that request. Please try again.