gh-pages-tips.md

Working With Github Pages

The FAQ maintained by Github covers most stumbling blocks, some other tips and tricks supplied here.

Gitignore

Add _site to .gitignore. The generated site should not be uploaded to Github since its gets generated by github.

Working With Code Partials

It might be the case that you are able to eval your code on the browser (javascript, css, html). If you can, it is nice to provide example code and also, working examples. You can DRY up your code samples and keep them easily up to date with the following strategy.

You want to start with file structure that has an _includes directory where you will put your snippets, and a markdown file that will be parsed into your github page. "includes" are analogous to partials.

├── _includes
│   ├── alert_msg.js
├── index.markdown

and some js in your snippet.

  alert("hello world");

and include that snippet in your markdown for it to be picked up by pygments and rendered into HTML:

{% highlight javascript %}
{% include alert_msg.js %}
{% endhighlight %}

Now create the working example by evaling the partial.

  <script type="text/javascript" charset="utf-8">
    $(document).ready(function(){
      $("#submit").click(function(e){
        {% include alert_msg.js %}
        return false;
      })
    });
  </script>

Keeping documentation up to date

Having the gh-pages convention is nice, but it keeps it hard to share between to branches and this is a problem if you want to publish your documentation. A simple solution is to provide a post-commmit hook that clones the repo into a temp directory, generates the documentation, copies that documentation into that branch and then pushes the code to the gh-pages branch on your github remote; triggering the page build process.

  #!/usr/bin/env ruby
  require 'fileutils'
  if `git branch`.split("\n").detect{|x| x.match(/^\*/)}.match(/master/)
    puts "updating documentation on the gh-pages branch"
    myrepo = "git@github.com:myrepo.git"
    temp = "/tmp/myrepo"
    FileUtils.mkdir_p(temp)
    `docco src/*.coffee`
    `git clone -b gh-pages #{myrepo} #{temp}`
    FileUtils.cp_r("docs/", temp)
    FileUtils.cd(temp) do
      system("git remote add github #{myrepo}")
      system("git add docs && git commit -a -m 'updating documentation' && git push github gh-pages")
    end
    FileUtils.rm_rf(temp)
    FileUtils.rm_r("docs/")
  end