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

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.