GitHub Pages-Starter Pack

Extended Resources

GitHub Pages-Starter Pack

Publishing a Website via GitHub pages is free, and easy. Everything you need to get going in one place + extended resources.


This content is open source. Help improve it.

I’m just a newb that created this resource to help myself. Github makes it easy to get started web-publishing. With the click of a button, you can have a web-page live, requiring only markdown skills (that anyone can learn on the go).

Each feature you want to enable requires a little more learning, and GitHub Pages is set up so that if you decide to, you can gradually progress from content creator to web-developer.

If you don’t want to think about web-development, and simply want your markdown files to look beautiful once published, github pages can help you do that too.

The number of technical subjects I’ve begun to learn is incredible!

Thanks to github and it’s dedicated community of open-source creators.

Getting Started

The simplest way to use pages is to choose one of the official GitHub pages themes. Just go into your repository settings:

All you really need to do is select a branch and it will begin publishing your repository. Then choose a method to publish.

The first repository for your web-page must be named like so: For example, the repository for my personal page is called Simply create a new repository, and if your github username is @awesomesauce then you would create a new directory named

Every other repository you own can also be made into its own web-page, that will published off of your user page, with the same name following your domain. So if you have a repository called, /Dynomite and you go into settings select pages to publish from the master branch, then that page will be found at

so is published at, because I have a custom domain. But it can still be found at,

GitHub Supported

Those basic github themes are mostly for developers who want a page to put up for a software project, or anyone who just wants a basic blog to get started. This way, you could get started writing blogs immediately, and learn the basics. Later, it’s easy to bring those old posts to a new theme.

GitHub Pages Supports the following gem themes:

Gem Based Themes

Gem files are ruby packages that contain all of the files necessary for building your site, and keep your repository directory un-cluttered. Then, if you want to change a file that’s in the gem, you just create the directory and pur the file where it goes, and configure as you wish.

You must build them locally, and tell jekyll to build to the docs directory, which you may have noticed as an option in your repository settings, and github will publish that directory. However, for user or organization pages, you can only publish from the master directory.

So this will only work for projects other than your homepage, or your organizations homepage.

Simply add the following line to your _config.yml

destination: docs

Then add the gem and the source, also add any plugins you are using, such as in this example:

source ''
gem "minimal-mistakes-jekyll"

gem "jekyll-paginate"
gem "jekyll-sitemap"
gem "jekyll-gist"
gem "jekyll-feed"
gem "jemoji"
gem "jekyll-include-cache"

then from the root of your project directory, on your local command-line:

bundle install bundle exec jekyll serve

And you can view your updates to the project locally, before sending them over to github.

Even if you don’t use this install method, you should use the same steps to build locally, regardless.

Remote Themes

This makes it simpler to keep your source files up to date. However, it is slower than using gems to build locally

  - jekyll-remote-theme

remote_theme: benbalter/retlab

Essentially, if you’re just editing files on github, you should just add those lines to your _config.yml along w an index file and Jekyll should build your site.

Classic Themes

These classic themes are just files and folders, everything where you can see it (and should be forkable to create working websites).


Jekyll Themes

I’ll say now, if you are new to web-development, best to start off trying out a few of the official GitHub Pages Themes.

Once installed, I cloned those repos locally so its easier to see how everything works. Then, if I want to configure a file that’s not in my repository, I have a copy nearby. You can grab the _layouts/default.html, put it in your repo, and get a feel for how configuring that template shapes your entire site. But then you configure individual pages, and categories, perhaphs, to display differently.

The problem is that all of these websites are not exactly up to date. Many of the themes listed above were written for older versions of Jekyll.

Choosing a theme is very personal to your needs, also.

Found Themes

I’m keeping track of themes that catch my eye:

Minimal Mistakes

When I was first looking for a jekyll theme, it seemed I couldn’t get away from this theme in google search results. No wonder, it’s stable, creates gorgeous sites right out the box, and has every feature you could want, as a beginner. I see plenty of professional sites built with it, tho I don’t always even realize right away.

Not only that, it has excellent documentation! You can find pretty much everything you need to run Minimal Mistakes in the Quickstart Guide, Sample Posts and Collections, along with their corresponding files on Github.

Other themes by @mmistakes:

I’ve just listed what repositories most fit my use cases, you might want to browse through his github portfolio, yourself.


Create an

Although pages will build an index.html from your, pages will not behave as expected if you try to do any configuration or additional optimization with only

in that you need to include front matter:

layout: default

There is a plugin that will builds index files from all the files of your repository.. but it has trouble creating an index.html from your repositories primary

Front Matter


Layouts are preconfigured page templates. When I started, it was too much to think about layouts, and I would use “single” and “page”. Now that I am using blog posts.. (because they populate your RSS feed, and increases their portability) I’m also using the Home layout:



Use redirect_from: internal/url to change the location you are publishing, but keep old links. Use redirect_to: https://external.url to send visitors somewhere else (perhaps you want it to live on another site, but not lose your valuable links :)


Namecheap supports BTC purchases, so I’m including their github how-to here. If you know of other crypto-friendly domain providers, lmk in the issues.