Create GitHub or GitLab hosted website

GitHub, GitLab, Bitbucket and similar services allow free, fast static websites under usage limits. Netlify is recommended for use with any static site generator (SSG). GitHub Pages is Jekyll only. GitLab Pages may be used with any SSG.

GitHub Pages is noticeably easier to use than GitLab or Bitbucket Pages. GitLab runners are slow and build quota can run out before month’s end. Most should start with GitHub Pages for websites of any size. While we generally recommned Hugo over Jekyll, here’s how to setup a Jekyll website.

The Minimal Mistakes Jekyll template is one of numerous quick-loading Jekyll templates. Forget about AMP, get lightning-fast mobile browsing Google PageSpeed scores with Jekyll and Minimal Mistakes. This procedure is based on Linux (including Windows Subsystem for Linux).

Install prereqs:

apt install ruby-dev libssl-dev

gem update --system

Configure Ruby Gem install without sudo and install Gem bundler (without sudo):

gem install jekyll bundler

Download and extract latest Minimal Mistakes release. Install needed Gems:

mv minimal-mistakes username.github.io
cd username.github.io

bundle install

where username is your GitLab or GitHub username. On GitHub/GitLab, create a new blank repository username.github.io (for GitLab, username.gitlab.io).

Edit _config.yml, change the following lines to fit your needs: title, name, description, url, repository

Connect your new website to GitLab/GitHub (swapping gitlab for github as appropriate)

git init
git add .
git commit -am init
git remote add origin https://github.invalid/username/username.github.io
git push

Future edits will follow the usual

git commit -am foo
git push

Now your page should be live at username.github.io. See Github Pages docs for custom domains and advanced configs.

Tips

Folders under _posts with filenames starting with date appear on the site. Subfolders under _posts are transparently processed. This is useful to organize posts by year for example, without affecting URL formatting.

Example filename: _posts/2018/2018-09-23-joes-big-vacation.md appears to the public with URL: https://username.github.io/joes-big-vacation

Enable search icon in _config.yml with key:

search: true

This enables site-wide Lunr instant search as the user types. The search icon is at the upper right corner of the toolbar on top of every page/post. It’s much better/faster than Google-based search of your site! This instant as-you-type search scales well for sites with thousands of pages.

Edit static navigation buttons in _data/navigation.yml. To improve default formatting, copy/paste into _config.yml these lines (anywhere in file):

defaults:
  -
    scope:
      path: ""

    values:
      layout: "single"
      toc: true
      author_profile: false
      read_time: false
      comments: true
      share: true
      related: true

include: ["_pages"]

To configure the banner, add to index.html header (between three dashes) the lines:

header:
    overlay_color: "#000"
    overlay_filter: "0.5"
    overlay_image: /images/header.jpg
excerpt: "text overlaid on banner image"

Remove the author image by:

author_profile: false

Remove category from permalinks: in case you later decide a page category should change, without screwing up your search engine results, in _config.yml:

permalink: /:title/

Control the number of posts per archive page in _config.yml:

paginate: 10 # amount of posts to show

Reference: Jekyll install reference