Readme.js

Readme.js is a jQuery Plugin that embeds the Readme of a Github Repo into any website.

Demo & Examples: Readme.js

How to Use

You have two options when using Readme.js:

• Using HTML Data-Attributes

    <div class='readme_js' data-owner='thomasklemm' data-repo='Readme.js'></div>
  
    Note: Readme.js will automatically instantiate elements with a class of 'readme_js'

• Using Javascript

    <div id='Readme'></div>
  
    <!-- Note: jQuery and Readme.js have to be loaded -->
    <script>
      $('#Readme').readme({
        'owner': 'thomasklemm',
        'repo':  'Readme.js'
      });
    </script>

That's it. The Readme will be pulled from Github's respective API and inserted along with some basic styles.

Step-by-Step

1. Include jQuery and readme.js files in your HTML:

  <script src="PATH/TO/jquery.js"><script>  
  <script src="PATH/TO/readme.js"><script>

2. Create an element for the Readme:

  <div id='Readme'></div>

3. Instantiate Readme.js:

    <script>
      $('#Readme').readme({
        'owner': 'thomasklemm',
        'repo':  'Readme.js'
      });
    </script>

4. You are all set up!

How does it work?

Some jaw-dropping kind of Yedi-Style Magic :-D Nah - that would be nice. However, Readme.js actually just requests a Github Repo's Readme at the corresponding Github API and inserts the html into the elements you specify. It also ships with some styles extracted from the Github homepage (Note: As for permission) so that proper Syntax Highlighting can happen as well.

FAQs & Common Error Messages

What does "XMLHttpRequest cannot load https://api.github.com/repos/sinatra/sinatra/readme. Origin http://mysite.com is not allowed by Access-Control-Allow-Origin." mean?
The most common error to occur is related to Ajax Cross-Site Requests. I'll refer to the Github API Manual for you to read up on how to enable Ajax Cross-Site Requests to Github from your Domain. You will be able to get it working in a few minutes.

Requirements & Testing

Readme.js requires jQuery 1.4+ and should work in all current browsers.

Alternatives

• Repo.js by Darcy Clarke: Repo.js is a light-weight jQuery Plugin that lets you easily embed a Github repo onto your site. As a plugin or library author this is a great way to showcase the contents of a repo on a project page. (Github)
• Gist-It by Robert Krimen: Gist-It lets you take a file from your GitHub repository and embed it into any webpage, just like a gist. (Github)

Is it any good?

Yes.

License

MIT