How can I sync documentation with Github Pages?

I am going to post a solution that I setup that takes advantage of the fact that GitHub Pages uses Jekyll already using the Automatic Page Generator.

1. git checkout gh-pages
2. mkdir _layouts
3. mv index.html _layouts
4. git checkout master -- README.md
5. mv README.md index.md
6. Prepend the following text to index.md

---
layout: index
---

You also need to open the index.html file and make the following changes:

1. Remove the rendered HTML from the markdown in your README.md file. This is usually between <section> or <article> tags. Replace this HTML with the text {{ content }} this will allow us to use this file as a jekyll. The file we apply the layout to will be placed where the content tag is.

2. Locate the CSS for your project page theme. for me this was a line like the following:

   <link rel='stylesheet' href='stylesheets/stylesheet.css' />

   This needs to be changed to

   <link rel='stylesheet' href='{{ site.path }}/stylesheets/stylesheet.css' />

3. Any other assets stored on your site that will be used in this layout will also need to be prefixed with {{ site.path }}.

By doing this, Jekyll will render the markdown file as the content of the index.html layout in the _layouts directory. In order to automate this process for not just the README.md file, but also other docs you may have in your master branch, I have taken the following steps:

Created the file called post-commit containing the following:

#!/bin/bash
###
### The following block runs after commit to "master" branch
###
if [ `git rev-parse --abbrev-ref HEAD` == "master" ]; then

    # Layout prefix is prepended to each markdown file synced
    ###################################################################
    LAYOUT_PREFIX='---\r\nlayout: index\r\n---\r\n\r\n'

    # Switch to gh-pages branch to sync it with master
    ###################################################################
    git checkout gh-pages

    # Sync the README.md in master to index.md adding jekyll header
    ###################################################################
    git checkout master -- README.md
    echo -e $LAYOUT_PREFIX > index.md
    cat README.md >> index.md
    rm README.md
    git add index.md
    git commit -a -m "Sync README.md in master branch to index.md in gh-pages"

    # Sync the markdown files in the docs/* directory
    ###################################################################
    git checkout master -- docs
    FILES=docs/*
    for file in $FILES
    do
        echo -e $LAYOUT_PREFIX | cat - "$file" > temp && mv temp "$file"
    done

    git add docs
    git commit -a -m "Sync docs from master branch to docs gh-pages directory"

    # Uncomment the following push if you want to auto push to
    # the gh-pages branch whenever you commit to master locally.
    # This is a little extreme. Use with care!
    ###################################################################
    # git push origin gh-pages

    # Finally, switch back to the master branch and exit block
    git checkout master
fi

EDIT: I updated the above script for both the README.md file and the markdown in docs/* to both use the same layout file. This is a much better setup than what I had before. This script goes in your .git/hooks/ directory. bash must be in your path.

Create the file _config.yml with the following

markdown: redcarpet
path: http://username.github.io/reponame

The above script also syncs markdown files found in the docs/* directory of the master branch, in order that they may be viewed on the GitHub Pages site as well. Relative linking to these documents works if you include the following jQuery function in order to strip the .md extension from the anchors on the gh-pages branch. You can add the following script to index.html in the _layouts directory:

$(document).on('ready', function () {
    $('a').each(function (i, e) {
        var href = e.href;
        if (href.search('.md') > 0)
            $(this).attr('href', href.split('.md')[0]);
    });
});

EDIT: I changed the code above in my repository, this was a quick and dirty way to do this, but it won't work right in all cases if you know what I mean.. For example, the markdown file company.mdata.md would not be processed correctly. To fix this I updated this to the following script which more carefully checks out the href and removes the extension if found. I also made the script more generic, allowing it to be used to remove other extensions by changing the ext variable. Here is the code:

$(function () {
    $('a').each(function () {
        var ext = '.md';
        var href = $(this).attr('href');
        var position = href.length - ext.length;
        if (href.substring(position) === ext)
            $(this).attr('href', href.substring(0, position));
    });
});

I setup an example repo at CoryG89/docsync, which has a project page here, if you'd like to see how all this works together.

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.

You can use DocumentUp to render your README.md.