GitHub Pages

GitHub Pages are public web pages for users, organizations, and repositories, that are freely hosted on GitHub’s github.io domain or on a custom domain name of your choice. GitHub Pages are compatible with Bunto behind the scenes, so in addition to supporting regular HTML content, they’re also a great way to host your Bunto-powered website for free.

Never built a website with GitHub Pages before? See this marvelous guide by Jonathan McGlone to get you up and running. This guide will teach you what you need to know about Git, GitHub, and Bunto to create your very own website on GitHub Pages.

Project Page URL Structure

Sometimes it’s nice to preview your Bunto site before you push your gh-pages branch to GitHub. However, the subdirectory-like URL structure GitHub uses for Project Pages complicates the proper resolution of URLs. In order to assure your site builds properly, use site.github.url in your URL’s.

<!-- Useful for styles with static names... -->
<link href="{{ site.github.url }}/path/to/css.css" rel="stylesheet">
<!-- and for documents/pages whose URL's can change... -->
[{{ page.title }}]("{{ page.url | prepend: site.github.url }}")

This way you can preview your site locally from the site root on localhost, but when GitHub generates your pages from the gh-pages branch all the URLs will resolve properly.

Deploying Bunto to GitHub Pages

GitHub Pages work by looking at certain branches of repositories on GitHub. There are two basic types available: user/organization pages and project pages. The way to deploy these two types of sites are nearly identical, except for a few minor details.

source 'https://rubygems.org'

require 'json'
require 'open-uri'
versions = JSON.parse(open('https://pages.github.com/versions.json').read)

gem 'github-pages', versions['github-pages']

source 'https://rubygems.org'

gem 'github-pages'

User and Organization Pages

User and organization pages live in a special GitHub repository dedicated to only the GitHub Pages files. This repository must be named after the account name. For example, @mojombo’s user page repository has the name mojombo.github.io.

Content from the master branch of your repository will be used to build and publish the GitHub Pages site, so make sure your Bunto site is stored there.

Project Pages

Unlike user and organization Pages, Project Pages are kept in the same repository as the project they are for, except that the website content is stored in a specially named gh-pages branch or in a docs folder on the master branch. The content will be rendered using Bunto, and the output will become available under a subpath of your user pages subdomain, such as username.github.io/project (unless a custom domain is specified).

The Bunto project repository itself is a perfect example of this branch structure—the master branch contains the actual software project for Bunto, and the Bunto website that you’re looking at right now is contained in the docs folder of the same repository.

Please refer to GitHub official documentation on user, organization and project pages to see more detailed examples.