> git add . > git status // to see what changes are going to be commited > git commit -m 'Some descriptive commit message' > git push origin master

Now then to update gh-pages

> git checkout gh-pages // go to the gh-pages branch > git rebase master // bring gh-pages up to date with master > git push origin gh-pages // commit the changes > git checkout master // return to the master branch

There is no scope for adding Jekyll plugins to your site if you are using gh-pages to host. I wanted to add a last updated date, I don’t blog there but I do update the site on a reasonably regular basis and wanted to reflect this somehow. 

I have added the the date to the footer, see http://clar.ky

Here’s how i did it with some javascript the Github API the a little help from the Timeago the jQuery fuzzy date plugin.

$.getJSON('https://api.github.com/repos/netotaku/netotaku.github.io/commits', function(data){ var commit = data[0].commit; $('#last-updated').html('Last updated <a href="' + commit.url + '" target="_blank">' + $.timeago(commit.author.date) + '</a>'); });

netotaku being my Github user name and netotaku.github.io being the name of the repository.

Working on someone's repo today. I very very quickly configured a domain name (using Namecheap) and github pages, and I was surprised because I've definitely spent agonizingly long to do that for prior projects. 

What made this one faster? 

1. Namecheap has a university offer where students with a .edu email can get a .me domain name for 1 yr/ free.

2. Github pages worked seamlessly with the repo. We already had an index.html file, so we just started a new branch and walaaaaaa....basically instantaneous username.github.io/reponame was set up. 

3. You need to create a CNAME file in your repo for whatever domain name you bought. 

4. On the Namecheap side, you only need to change the part that already has the domain name in it (the CNAME part) to be your username.github.io., with the period at the end. 

THESE THINGS HAVE TO HAPPEN in order for your custom domain GitHub pages site to work:

1) Repo containing your files must be named 'name.github.io'

2) A file named 'CNAME' must contain your custom domain name (i.e. examplename.com). This file would is placed in the repo.

3) Instead of master, a branch named 'gh-pages' must be the default branch. You can change the default branch in your repo/settings/Default Branch dropdown under 'Settings'

GitHub is awesome. It's so awesome that they even provide you with super basic web hosting for static pages, so you can re-up your old GeoCities site. However, their documentation isn't that stellar, so I wrote up this quick little guide...

1) Make a new repo on GitHub with the following name: [username].github.io

The name before github.io needs to be your exact GitHub handle. So if you're xSk8oRDiEx on GitHub, it'll be xsk8ordiex.github.io, sorry.

2) Once the repo is created, go to the settings (last item in the menu on the right):

3) Click on the Automatic Page Generator (you can skip writing in content on the following page):

4) Select a template and click publish!

Great! Within 15 minutes, you should be able to visit yourname.github.io (or in my case, cmdoptesc.github.io). And to edit the site, clone down the repo and edit it like any other static site. If you want to run Node.js, you'll have to look to paid hosting, or get a trial at Heroku, or Nodejitsu.

Hope this helps!

    Follow-ups:

If you own a domain and would like to direct it to yourname.github.io, check out GitHub's help page. In short, it's a two-step process of (1) modifying information on your registrar (e.g. NameCheap or Gandi) like this:

And (2) adding a CNAME file to the root of the repo. CNAME should have no extensions, and should contain one simple line: yourdomain.com

Recently I created home page for my project Scaldi. I wanted to make it for a long time, but from the other hand I don't want to spend much time finding some hosting and maintaining its infrastructure, making page design, etc. Github page is nice, but still I would like to have somethng more simple and unique as a project's front page. So my main goals were:

Use very nice feature of Github - gh-pages to host my pages

Use markdown to create my pages without spending much time making page design

Design that comes out-of-box should be clean and pretty

Integrate pages generation and publishing in SBT build process

Pamflet

And I finally found solution that addresses all these requirements. Pamflet is very nice Scala library that allows you to define your site using markdown. It's very easy to use: you just create your pages that are named according to their position in the resulting table of contents with .md or .markdown extension. You can also define some properties in the template.properties which you can use in your pages (they would be processed using StringTemplate). If you want, you can add some custom CSS in order to make it even more prettier. So resulting file structure should look like this:

00.md

01.md

02.md

custom.css

template.properties

Pamflet has even more features, but it was enough for me to start creating Scaldi's home page. So I ended up with following files in my project's docs folder. It was pretty straightforward to create, but now I need to generate actual HTML from my markdown markup.

SBT Integration

In order to generate my pages and publish them to the gh-pages I need following SBT plugins:

pamflet-plugin - it generates actual site

xsbt-ghpages-plugin - adds generated pages to the gh-pages branch and pushes changes to github

At first you need to create  gh-pages branch in your git repository. You can make it like this:

After executing this, you need to add SBT plugins in your project/project/Build.scala:

After adding these plugins, you should be able to generate HTML pages. All you need to do is to execute write-pamflet task and your pages would be generated in target/docs folder.

Now comes your main build.sbt file:

I hope comments will help you in understanding what each of these settings does. So now in order to publish my pages I need to execute ghpages-push-site task. I can also run ghpages-synch-local in order to add pages to the gh-pages branch locally.

As bonus, Scalasodocs would be also published by xsbt-ghpages-plugin.

Conclusion

It was pretty easy to integrate Pamflet with SBT and gh-pages. I ended up with nice looking site and published Scaladoc. And it's really easy to manage and publish them.

Too often, I come across GitHub Pages branches (gh-pages) branches that are simply forks from the master branch of the repository. This is not ideal.

There are several problems with this strategy:

Unless you manually update the gh-pages branch every time you add a commit to master, you will be out of date.

It makes for a much more difficult to understand source folder for the jekyll or HTML site, since people have to mentally categorize every file and folder into either “part of the site” or “an artifact from the master branch”.

It introduces the need to have lines like this in _config.yml to prevent unrelated files from being included in the gh-pages site:

exclude: ./app, ./lib, ./project.gemspec, ./Gemfile, ./LICENSE, ./Rakefile, ./readme.md, ./features, ./spec

git checkout --orphan gh-pages

When it comes time to create a GitHub Page for your project, use the above command. This creates a branch that is completely separate from the history of the rest of the repository. You will need to delete the files by running “git rm -rf .”:

If you want to start a disconnected history that records a set of paths that is totally different from the one of <start_point>, then you should clear the index and the working tree right after creating the orphan branch by running "git rm -rf ." from the top level of the working tree. Afterwards you will be ready to prepare your new files, repopulating the working tree, by copying them from elsewhere, extracting a tarball, etc.

— git checkout --help

After you have an empty branch, you’re ready to get started on your jekyll or HTML site with a clean history and a clear conscience.