I wanted to start my own GitHub Pages site from scratch. In particular, I really want to be able to develop and test the site locally and push to GitHub only, if new contributions have been tested on my local machine.

To start a jekyll-based site on GitHub pages from scratch, I have oriented myself along the instructions in the GitHub documentstion. Yet, some details were missing or confusing (at least to me).

Here are the steps, that work for me:

  1. Navigate to the parent directory, in which you want to create the folder to store the website repository

     cd <parentDirectory>

  2. Create an empty git repository for the website:

     git init <GitHubUserName>.github.io
  3. Create an emtpy jekyll-based site via jekyll new ..
  4. Open the auto-generated Gemfile
    1. Follow the instructions in the Gemfile’s comments to use GitHub Pages.
    2. Update the gem "github-pages"line so that the line looks like this, replacing <version> with the current dependency version for github-pages.
     gem "github-pages", "~> <version>", group: :jekyll_plugins

    For more information, see Dependency versions on the GitHub Pages site.

    1. Close the Gemfile.
  5. Remove the auto-generated Gemfile.lock via rm Gemfile.lock. Otherwise, the next step failed with inconsistencies in version numbers of various components defined in the Gemfile.
  6. Run bundle install.

The jekyll setup is now finished and you can start do develop your site. To preview the site on your local machine, run bundle exec jekyll serve and use a brownser to navigate to the Server address:, that has been printed in the terminal.

As your site is wrapped into a regular git repository, remember to commit your changes. Once you’re ready to publish the site, commit everything and push to GitHub via:

  1. Create a repository with the name <GitHubUserName>.github.io on GitHub.
  2. Set the new repository as remote on your local repository.
  3. Push your local repository to GitHub.

Now, you can view your published site at https://<GitHubUserName>.github.io. It might take a minute or two for jekyll to actually generate your site, so be patient. The results will be worth it!