GitHub Pages-Extended Resources





Open Graph - Favicons and More


Build Local - Bug Testing

Buidling your site locally is the best way to figure out why it’s not publishing correctly via GitHub.

You must set up your gemfile specifically for each theme.

then prepare bundler for your project:

 bundle update

 bundle install

Build gives an error message if the build fails

 bundle exec jekyll build

Serve builds and “serves” a local browsable copy

 bundle exec jekyll serve

Trace gives details on errors (but won’t always show your problem)

 bundle exec jekyll build --trace

Verbose… you get the idea.

 bundle exec jekyll build --verbose



coming soon….






API Evangelist

Not sure how much of this is useful, but I’ll save for further examination.


GitHub Pages-Starter Pack

Github makes it easy to get started, 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.

I first started playing around with GitHub to make an awesome-list, in November.

The number of technical subjects I’ve begun to learn, thanks to github, is incredible. Publishing via github-pages is really empowering.


I’m just a newb that created this resource to help myself. It does take a lot of work to create bigger projects like, however it’s really simple to create a blog, or a homepage.

Corrections, suggestions, tips, and links would be all appreciated.

Github pages runs Jekyll, which uses Kramdown to transform yaml, markdown, and a number of related languages into proper html.

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. Brand-newbs go with the theme chooser.

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,


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.

Besides the Theme Chooser

It’s time for an update, since I previously didn’t really understand all of the options very well.

There are a few ways to use GitHub Pages. How many?

I’ll list the ones that I can think of:

Gem Based Themes

Gem files are 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.

  • planetjekyll/awesome-jekyll-themes

    Q: How can I get started with gem-packaged themes? / Do I need to package my theme into a gem?

    Gem-packaged themes are just an advanced option and in addition they are in development for (real world) experiments (e.g. think v0.1 as stated by the Ben Balter - the lead designer / manager / dev at GitHub).

    Thus, to conclude do NOT read too much into the official themes docs e.g. as the only or “right” way to design a theme. Just (continue to) use “classic” themes - there are hundreds to learn from and once you have mastered “classic” themes you can “graduate” to the master class, that is, using gem-packaged themes.

GitHub Supported

GitHub Pages Supports the following gem themes:

  • Architect
  • Cayman
  • Dinky
  • Hacker
  • Leap day
  • Merlot
  • Midnight
  • Minima
  • Minimal
  • Modernist
  • Slate
  • Tactile
  • Time machine

Everything Else

You can use any gem based theme that you want. However, GitHub won’t build those for you.

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).

Github Pages


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.

Finding Themes

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:


If you don’t want to think too much about web-development, try Hydejack. It’s build with everything you need to create a beatiful responsive web-page, with plenty of options and configurations supported. It’s a free version of a more robust commercial option. But it’s easy to set up, and works great.

The only problem is that it is not open source. So it’s not 100% customizable. Then again, that keeps you from getting in and screwing things up. –>

Minimal Mistakes

Minimal Mistakes is the most popular theme for Github Pages, and with good cause. It creates gorgeous web-sites right out the box, and with some fine tuning is beautiful indeed. 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.

Made Mistakes

So Simple

Basically Basic

Skinny Bones


This site currently runs on Hpstr, but it is archived, and doesn’t support modern features of jekyll such as baseurl, nor can I get jekyll-redirect-from to work with it.

I will try migrating this to the Hugo port of this theme, which i believe is maintained. It’s been nice trying out though, and I’ve got a few I’d like to look at anyway.


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 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:

I’m wondering if I can move these documentation theme layouts, or even this post index from hpstr over to minimal-mistakes… probably so… except maybe there is custom css.. and I really haven’t taken the time to figure that out, yet.



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 :)

Learn SEO

SEO seems like a valuable subject to know about right?

The problem with SEO is that there’s so much to learn, it’s a vast domain of knowledge, with many branches that could each take up thier own websites of related information.

SEO is always changing, and a lot of incorrect or outdated information is republished.

What I’m trying to do is break it down into it’s various components.

The fundamental building blocks of SEO are:

  • Keyword Reserach
  • Content
  • Internal linking and Site Structure
  • A Multitude of Technical Optimizations.

Most of those optimizations revolve around gradually making every individual piece of code on your site more machine readable, so that it communicates essential bits of information to a variety of connecting sites\services that make it stand out from the crowd.

Before you worry about SEO

Mind you… none of this matters as much as having the highest quality content, if you’d like to show up (and\or remain) in the search rankings.

It’s better to start with a good foundation…

You should have at least 4 pages of 1500+ word information dense content. Find a subject you are excited about that your target market is interested in, and do some research.

You’ll likely find many valuable links, but nothing that presents all of the information you need in one place.

If you’re working on a well-researched and indexed subject, fine tune to a particular aspect that isn’t well indexed, but is particularly useful or interesting to you.

Point being, the internet is abundant with information that isn’t well organized amongst eachother. Provide value, it’s just work… not really hard.

Theeeeeeen you can start to think about your site structure and all of the details. If you have really informational content, there are going to be quite a few keywords, naturally…

I haven’t done any seo, besides making sure image\description pops up in social media, and my site is getting organic search traffic and rising through the rankings, relatively quickly.

Granted, I put out a ton of content.. and truthfully there are a lot of things I take for granted, like naming images with a likely key-phrases.

I gathered all this info here in prep for writing this article:




SEO is not hard. A step-by-step SEO tutorial for beginners that will get you ranked every single time. … coming soon …

Know Your Self-Customer-Competition

Keyword Research

Seed Keywords

For Bloggers

LSI Keywords

Domain Authority

I hear that Domain Authority is outdated.. but idk.



Internal Linking-Cornerstone Content

Evergreen-Skyscraper Content


Creating 10x Content:

  • Examples of trending quality content:
    • Guest Blogging
    • “opinion-forming journalism from recognized experts, and data-driven research studies showed a strong correlation between shares and links.”
    • Client case studies: These are shared by the client and can include exciting information about how they achieved their results, which can help others.
    • Infographics: These still get shared heavily online and are a great way to provide an instant view of data on a specific topic. It can be fun and informative, and usually, are republished on other blogs and shared on social media.
    • Other content that highlights influencers: This could include podcasts or video interviews.
    • Industry surveys: Many publishers do annual industry surveys, which have become well-known (and well-cited) each time they are released.
    • Free content or tools: This could include long-form content such as ebooks, or useful tools like quizzes and personalized reports that give users the helpful information they didn’t know before. -What to do when things go wrong
  • 1000 word articles vs 2000 word articles
  • Historical Blog SEO Optimization



  • Top SEO KPI
    1. Organic Sessions
    2. Keyword Ranking Increases
    3. Leads/Conversions
    4. Bounce Rate
    5. Pages/Session
    6. Average Session Duration
    7. Page Load Time
    8. Top Exit Pages
    9. Crawl Errors

Apply SEO to Different Platforms

  • App store
  • YouTube channel and video
  • Google My Business
  • Social media
  • Amazon
  • Yelp




Machine Learning