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.
     

Answer 1

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.

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.