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.

Introduction

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.

Note: this page is just for Jekyll\GHPages. I’m making new pages for the other stuff like static site generators besides jekyll, and content creation.

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

Github pages can be used, like, 4 different ways. It’s versitile, but can be confusing.

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: username.github.io. For example, the repository for my personal page is called infominer33.github.io. Simply create a new repository, and if your github username is @awesomesauce then you would create a new directory named awesomesauce.github.io.

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 https://awesomesauce.github.io/Dynomite.

so github.com/infominer33/DIDecentralized is published at infominer.id/DIDecentralized, because I have a custom domain. But it can still be found at, infominer33.github.io/DIDecentralized.

Domains

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.

• https://help.github.com/en/articles/using-a-custom-domain-with-github-pages
• Using Custom Domain for Github Pages
• namecheap.com - how-do-i-link-my-domain-to-github-pages

Getting Started

If you used the theme chooser, all you need to do is edit README.md, and your page is built instantly when you save a commit to the repository.

Create an index.md

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

in that index.md you need to include front matter:

---
layout: default
---

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

Besides the Theme Chooser

1. Remote Themes.

This is supposed to be the easy route, and makes it simpler to keep your source files up to date.

• github.blog/2017-11-29-use-any-theme-with-github-pages/

• Jekyll Remote Theme

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

1. You can also run any Gem based theme from your page. 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.
     > >I understand what they’re saying, but I feel kind of the opposite. I used the theme chooser and remote\gem themes to begin learning. Then again, I didn’t really understand my options when I started.

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

Moved

Running out of space on this page ;)

NOTE: The following resources are specifically for github-pages\jekyll compatible themes. Anything requiring a local build will now live on another page:

Static Site Generators Other Than Jekyll

Static Site Generators

Content Creation

Content Creation

Fundamentals

GitHub Learning Lab

Markdown

• Kramdown - QuickRef Guide
• Mastering Markdown
• Markdown Cheet-Sheet

Github Pages

• Github Pages Community Forum
• https://pages.github.com/versions/ - These plugins can be used via gh-pages.
• Configuring a Publishing Source for GitHub Pages
• help.github.com - User, Organization, and Project Pages
• http://ragupappu.com/2015/04/22/setup-website-using-github-pages-and-jekyll/
• Setting up You GitHub Pages Site Locally with Jekyll
  • – Local development with GitHub Pages
• Getting started with GitHub Pages: Part 4 – Customizing your Pages site
• Clearing Up Confusion around Baseurl

Jekyll

• Jekyll README
• planetjekyll
  • planetjekyll/awesome-jekyll
• Jekyll - Cheat Sheet
• Jekyll Community Forum
• Jekyll - Pagination Docs
• Jekyll - Navigation Tutorial
• https://wiredcraft.com/blog/make-jekyll-fast
• Jekyll - Static Site Generator | Tutorial > This course covers the basics of using Jekyll - Static Site Generator. Work your way through the videos and we’ll teach you everything you need to know to create a professional and scalable website or blog!
• Run a Specific Version of Bundler
  • Can get older themes to work if you use the right verion of bundler (found in gemfile.lock).
• benbalter/jekyll-style-guide

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

• planetjekyll/awesome-jekyll-themes (gem-based)
• http://themes.jekyllrc.org/
• jekyll-theme-showcase-share-your-jekyll-themes/1382
• forked.yannick.io - Find maintained forks of your favorite GitHub repos.

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:

• projectpages.github.io/project-pages/
  • project-pages/wiki
• bradleytaunt/lightspeed
• Just the Docs
• era.yayd.in/jekyll-bulma/
• https://ndrewtl.github.io/airspace-jekyll/
  • ndrewtl/airspace-jekyll/
• deanattali.com/beautiful-jekyll/
• github/personal-website > Code that’ll help you kickstart a personal website that showcases your work as a software developer.
• Documentation Theme Jekyll

Classic

• drjekyllthemes.github.io (classic ‘files and folders’)
• indieweb/blank-gh-site
• ChristopherA/simplest-github-page
• prose/starter
• https://github.com/kinlane/beforeeighteen (template for presentation style pages.)

Hydejack

• /qwtel/hydejack/
• /qwtel/hydejack-starter-kit
• Hydejack Print Documentation
• Hydejack Documentation.pdf
• Hydejack Advanced

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.

• minimal-mistakes/docs/quick-start-guide
• Sample Posts
• Sample Collections
• mmistakes/minimal-mistakes
  • Minimal Mistakes remote theme starter
  • mmistakes/minimal-mistakes-algolia-search - reference if you have problems enabling search.
• mmistakes/jekyll-theme-unit-test
• Minimal Mistakes Navigation Examples

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

• mademistakes.com -Michael Rose’s Homepage
  • mmistakes/made-mistakes-jekyll

So Simple

• So Simple Theme
  • mmistakes/so-simple-theme

Basically Basic

• Basically Basic
  • mmistakes/jekyll-theme-basically-basic
  • mmistakes/jekyll-theme-basically-basic-algolia-search

Skinny Bones

• Skinny Bones
  • mmistakes/skinny-bones-jekyll

Hpstr

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.

• Hpstr
  • mmistakes/hpstr-jekyll-theme

Continued in GitHub Pages Extended Resources