Github Pages provide a simple way to make a website using Markdown and git.

For me, the painful aspects of making a website are

  • Working with html and css
  • Finding a hosting site
  • Transferring stuff to the hosting site

With GitHub Pages, you just write things in Markdown, GitHub hosts the site for you, and you just push material to your GitHub repository with git add, git commit, and git push.

If you love git and GitHub, you’ll love GitHub Pages, too.

The sites use Jekyll, a ruby gem, to convert Markdown files to html, and this part is done automatically when you push the materials to the gh-pages branch of a GitHub repository.

The GitHub and Jekyll documentation is great, but I thought it would be useful to have a minimal tutorial, for those who just want to get going immediately with a simple site. To some readers, what GitHub has might be simpler and more direct. But if you just want to create a site like the one you’re looking at now, read on.

Start by reading the Overview page, which explains the basic structure of these sites. Then read how to make an independent website. Then read any of the other things, such as how to test your site locally.

If anything here is confusing (or wrong!), or if I’ve missed important details, please submit an issue, or (even better) fork the GitHub repository for this website, make modifications, and submit a pull request.


The source for this minimal tutorial is on github.

Also see my tutorials on git/github, GNU make, knitr, R packages, data organization, and reproducible research.