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 set up a GitHub Pages branch which is hosted under our GitHub Organization's subdomain, and used the Automatic Page Generator simply loading in our README.md file when we created our page. However, I notice that when I update our README.md file, it does not update the project page. Instead, we must go to the GitHub settings tab and recreate the project page, reloading the README.md file when we do it.

Also, after reading about relative linking working between documentation files on the GitHub project directory pages. I very much like the markdown as it saves tons of time from having to write all the HTML out by hand for our documentation. What I would like however is to be able to have one README.md file which is able to include relative links to other documentation files located at docs/*.md. I was hoping there was an easy solution so that my other documentation files might also be included in my gh-pages branch and be hosted under my GitHub Pages subdomain and be rendered and/or themed.

In other words, my questions are:

Is there a way to have my README.md file automatically update on my Github Page subdomain?
- [ EDIT ] : No appears to be the answer if using the Automatic Page Generator. You must go to the settings page for the repo and reload it every time there is a change in order to update it.
Is there a way I can have my relative links to my documentation on my README.md file work on my Github Pages, perhaps my somehow syncing my /docs/*.md to my Github Pages and somehow rendering and/or theming them?
- [ EDIT ] : From what I've learned since writing this question it appears that this is only possible on GitHub pages through the use of a static site generator like the ruby gem Jekyll and probably some uses of the webhooks supported by GitHub that are mentioned in the comments below. I am trying currently trying to find an optimal solution.
Better yet, is there an even easier way I can do this and perhaps have just one copy of my README.md and documentation that is used on both gh-pages and my main branch and makes everything easiest?
- [ EDIT ] : It seems this one is almost definitely a no. I was thinking about the possibility of something built into GitHub to allow this. It seems that better support for this kind of thing may could be built into GitHub Pages in the future, or at least I definitely hope it will be.

GitHub has support for post-receive webhooks. Have you thought of adding a hook that calls some remote script that pushes the new README.md version into GitHub pages? — ubik
Thanks for being awesome and editing in your findings. Not enough people do that on this site. — Matt Kantor
For the first question, here is a manual approach, not auto, but it is simple and works. For the HTML generation part, one can use dillinger.io. I've also found this automatic method, although I gave it a try but didn't get it to work. — iled
GitHub has just enabled using any branch and directory as the source for the docs. You no longer have to use gh-pages. — Dan Dascalescu

Cory Gross Cory Gross · Accepted Answer · 2013-05-05T22:13:51

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.

git checkout gh-pages
mkdir _layouts
mv index.html _layouts
git checkout master -- README.md
mv README.md index.md
Prepend the following text to index.md

---
layout: index
---

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

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.
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' />
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.

How can I sync documentation with Github Pages?

10 Answers

The setup

Automating