Readme.js

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 15 Open GitHub ↗

Readme.js embeds a Github Repo's README into any website.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Readme.js
[Readme.js](http://readmejs.herokuapp.com/) is a jQuery Plugin that embeds the Readme of a Github Repo into any website.

Demo & Examples: [Readme.js](http://readmejs.herokuapp.com/)

### How to Use
You have two options when using Readme.js:
  - Using HTML Data-Attributes
    ```html
      <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
    ```html
      <div id='Readme'></div>

<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:  
  ```html
    <script src="PATH/TO/jquery.js"><script>  
    <script src="PATH/TO/readme.js"><script>
  ```
2. Create an element for the Readme:  
  ```html
    <div id='Readme'></div>
  ```
3. Instantiate Readme.js:  
```html
    <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](http://developer.github.com/v3/repos/contents/) 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](http://developer.github.com/v3/#cross-origin-resource-sharing). 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](http://darcyclarke.me/dev/repojs/): 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)](https://github.com/darcyclarke/Repo.js)
- [Gist-It by Robert Krimen](http://gist-it.appspot.com/): Gist-It lets you take a file from your GitHub repository and embed it into any webpage, just like a gist. [(Github)](https://github.com/robertkrimen/gist-it)

### Is it any good?
[Yes.](http://news.ycombinator.com/item?id=3067434)

### License
MIT

Readme.js

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README