You can publish your project on Github Pages, which is a free web hosting service provided by Github. All you need is to put your content into a Github repo branch called gh-pages and make this your default branch in your repo. With a Jekyll site, you just commit your entire project into the gh-pages branch and Github Pages will build the site for you.

Set up your Github repo

  1. Make sure you have Git installed. You can download and install Git for Windows here and Git for Mac here. If you’re on a Mac, chances are you might already have git installed. You can check by opening up a terminal and typing which git.
  2. Go to Github.com and sign up for an account.
  3. Click the + button in the upper-right corner and select New repository.
  4. Name the repository something like mydoctheme.
  5. Type a description..
  6. Select the Initialize this repository with a README check box.
  7. Add a license if desired.
  8. Leave the other options at the defaults and click Create repository.
  9. Click the Settings button.
  10. Go to your repository’s home page, and click the branch drop-down menu.
  11. Create a new branch called gh-pages.
  12. Click Settings and change the default branch to gh-pages.
  13. Go back to your repository’s homepage. With the gh-pages branch selected, copy the https clone url:
  14. Open a terminal, browse to a convenient location for your project, and type git clone https://github.com/tomjoht/myreponame.git, replacing the https://github.com/tomjoht/myreponame.git with your repository’s https clone URL that you copied.
  15. Move the jekyll theme files into this new folder that you just created in the previous step.
  16. Open the _config.yml file and add the following:
   url: tomjoht.github.io
   baseurl: /myreponame

Change the url to your github account name, and the baseurl to your repo name.

Install Bundler

Bundler is a package manager for Ruby that will install all dependencies you might need to build your site locally. I recommend installing Bundler through homebrew. (Sorry, these instructions apply to Mac only.)

  1. Install homebrew:

    /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

  2. Install Bundler:

    gem install bundler

Add the github pages gem

  1. In terminal, browse to your Jekyll project directory.
  2. Type bundle init. This creates a Gemfile and Gemfile.lock in your project.
  3. Type open gemfile. This opens the gemfile in your default text editor.

  4. Add the following in the gemfile (replacing the existing contents):

    source 'https://rubygems.org'
gem 'github-pages'
  5. Run bundle install.
  6. Add the new jekyll files to git: git add --all.
  7. Commit the files: git commit -m "committing my jekyll theme".
  8. Push the files up to your github repo: git push.

Github Pages will now automatically build your site. Wait a minute or two, and then visit tomjoht.github.io/yourreponame, replacing this path with your github account and branch.

Customize your URL

You can also customize your Github URL. More instructions on this later….