GitHub Pages-Starter Pack + Extended Resources

GitHub Pages-Starter Pack + Extended Resources

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

Table of Contents

Edit

This content is open source. Help improve it.

I started collecting links in a text file, back when I first started to use GitHub pages. There were many resources available on how to use jekyll, but not so many on how to use GitHub pages.

Github makes it easy to get started web-publishing. With the click of a button, you can have a simple web-page live, requiring only markdown skills, that anyone can learn on the go.

I started out clicking on GitHub’s GUI, and each new feature I wanted to enable required 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

Before you start using Jekyll or any other static site generators, it’s helpful to understand how GitHub pages works.

In your repository settings you’ll find various options of where to publish your site from.

image

Whichever of those options you choose, you can drop an index.html in the root of whatever location you chose in the above settings, and that site will be published.

If you have other posts or pages, you can assign one of them the root permalink, in its frontmatter, and in this case you do not need index.html

Example: permalink: /

Repository Naming Conventions

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, /Dynamite and you go into settings select pages to publish from the master branch, then that page will be found at https://awesomesauce.github.io/Dynamite.

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

Following these steps, so far, is all without jekyll, just html, css, and javascript.

Classic Themes

You can install ‘classic themes’ simply by copying (or forking) their repository to a space you control, and change them by editing their files manually. These are just files and folders, with everything where you can see it.

Resources

Jekyll

What separates ‘classic themes’ from jekyll themes is a configuration file called _config.yml. This lets jekyll know how to build your site, and it lets github know it can be built.

Official GitHub Pages Themes

The simplest way to use jekyll\github-pages is to choose one of the official GitHub pages themes.

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 learning. Using the theme chooser, you can get started writing blogs immediately, and begin learning the basics of how jekyll sites are configured.

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 parts of your site to display differently.

GitHub Pages has the following themes built in, you can begin learning with a few clicks:

After you’ve learned the ropes, it’s easy to bring any content you created to a new theme.

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

Finding Jekyll Themes

There are tons of themes available for Jekyll… it’s just not neccessarily easy to figure out how to use them, when you’re first learning. Especially because they’ve all been built with\for different versions of Jekyll.

After I find a theme I like, I fork it and then go to settings and choose master, docs, or gh-pages, depending on how the site is designed, to make sure it’s working. I’ve spent a lot of time configuring themes I didn’t verify I could get running first. Don’t do that :)

Minimal Mistakes

When I was first looking for a jekyll theme, I couldn’t get away from this theme in google search results, and had a lot of trouble getting others to work. Minimal Mistakes is probably the most robust and reliable jekyll theme available.

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.

Minimal Mistakes is forkable to create a working site, and its a gem-based theme.

I have my own demo site with lots of detailed instructions on how I set them up, you can check out here: web-work-tools.github.io/minimal-mistakes/

Other Jekyll Themes I Like

Here are some themes that have caught my eye, and I know they work.

Other @mmistakes Themes

Setup

Front Matter

Layouts

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:

Collections

Plugins

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

Domains

Customizations

Comments

SEO

Jekyll-SEO-Tag

Open Graph, Twitter Cards, Favicons and More

Gem Based Themes

Gem files are ruby packages that contain all of the files necessary for building your site, allowing you to keep your repository un-cluttered, and keeps your site up to date, when the gems developer makes updates.

If you want to change a file that’s in the gem, you just create the directory and put the file where it goes, to configure as you wish.

Until GitHub Actions were introduced, you needed to Install jekyll and build them locally, to the docs directory, which you may have noticed as an option in your repository settings.

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.

Although that’s consistant with everything I’ve read, in practice I’ve found that after forking minimal mistakes, and setting up the gemfile, it will build the site for me. I think the idea is that once the site is completely built, with a gemfile and a gemfile.lock, then GitHub Pages uses jekyll to build any updates when you change it’s content\html\css\includes\layouts.

(see decentralized-id/decentralized-id.github.io’s: ‘_config.yml’) and gemfile for reference)

There’s also using the gh-pages branch, but that’s getting a little more technical.

Until you’ve set up a few different sites, and figure out the ins and outs, each new site takes some tinkering to get working.

Build with Jekyll Locally

You will find that GitHub error messages are not very descriptive. Buidling your site locally is the best way to figure out why GitHub Pages can’t build your site.

_config.yml

You can set the destination in your _config.yml, otherwise jekyll will build to the _site directory, which is usually added to your .gitignore file.

destination: docs

If you’re publishing from the docs directory, be sure and don’t add that to your .gitignore, since you want your website uploaded to GitHub to be published..

Gemfile

Then add the gem and its source, also add any plugins you are using:

source 'https://rubygems.org'
gem "minimal-mistakes-jekyll"

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

Install and Build the Site

Hopefully you have installed git, by now. You’ll need that to push any local changes to GitHub.

Then use bundler to install the theme

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

Resources

Remote Themes

This makes it simpler to keep your source files up to date. However, it is much slower than using gems to build locally (which only really matters if your site has a lot of content).

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.

Technical

Liquid

Data

JSON

API Evangelist

Automation

You can use GitHub actions or other CI to build your site automatically when you push to the repository and\or on a schedule. There are many other possibilities for creating content automatically based on web-events, and using staticman for forms that do more than just comments.

Indieweb

This is beyond the scope of a GitHub pages post, but I can’t help but adding a few links to indieweb. If you are publishing a personal blog, independent from an enterprise, then you are part of the indieweb.

web-work-tools.github.io/indieweb/