How can I sync documentation with Github Pages?

Question

I have a project together with several people and we have a README.md file with a bunch of GitHub Flavored Markdown that is rendered on our GitHub page. We also

Answer 1

Another method that I've gotten to work pretty successfully is using Ajax to fetch the docs using the Github API and a Javascript markdown engine to render the HTML (as also suggested by Nathan).

1. Use the Github API and JSONP to fetch the doc from Github
2. Decode the base64 content in the response from the Github API
3. Render the markdown using a javascript markdown engine
4. Display the rendered html

Nathan expressed some concern over performance but in my experience, it loads seemingly instantly so I don't think it's actually a problem.

The advantage is that it's easy to setup and it will always update your docs even if you just edit the markdown directly in a browser on github.

I set up an example on Github pages at http://bradrhodes.github.io/GithubDocSync/ to show it working.

Answer 2

My solution to the problem of syncing a README with a Github page deviates slightly from the above. Instead of using a separate JavaScript Markdown engine, one can use the Github API to return a Markdown file rendered as HTML.

1. Fetch the README.md from https://api.github.com/repos/<owner>/<repo>/contents/README.md.
2. Decode the Base64 response: window.atob( JSON.parse( blob ).content );

3. Post the decoded README to https://api.github.com/markdown in a JSON body

    {
      "text": "<README>",
      "mode": "markdown",
      "context": "<owner>/<repo>"
    }
   

4. Insert the rendered HTML into a DOM element, as done by Brad Rhodes.

Two caveats to this approach:

1. Performing two serial requests slows down page load.
2. May encounter rate limits when accessing the Github API.

For a low traffic page where load time is not critical (~1-2sec), then the above method works well enough.

Answer 3

I have a couple ideas for sharing a single readme file between your documentation site and main github repo:

1. You could use only a single gh-pages branch that contains both your code and a jekyll documentation site. Your repository could get a bit cluttered and you will need to put a YAML header at the top of the readme. It almost supports relative linking. The problem is that if you want jekyll to render your markdown it will give it a .html extension. Maybe there is a way to configure this though. Here's an example I threw together to see if it works.

2. You could use AJAX calls in your documentation site to read the readme from your main branch then render it with a Javascript Markdown renderer. This will take a little longer to load and it won't support relative links without you writing some clever Javascript. It is also more work to implement than idea 1.

Answer 4

You can use DocumentUp to render your README.md.