Readme.js is a jQuery Plugin that embeds the Readme of a Github Repo into any website.
Demo & Examples: Readme.js
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.
- Include jQuery and
readme.js
files in your HTML:
<script src="PATH/TO/jquery.js"><script>
<script src="PATH/TO/readme.js"><script>
- Create an element for the Readme:
<div id='Readme'></div>
- Instantiate Readme.js:
<script>
$('#Readme').readme({
'owner': 'thomasklemm',
'repo': 'Readme.js'
});
</script>
- You are all set up!
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.
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.
Readme.js requires jQuery 1.4+ and should work in all current browsers.
- 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)
MIT