Create Jekyll GitHub or GitLab hosted website

GitHub, GitLab, Bitbucket and similar services allow free, fast static websites under usage limits:

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.

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

  1. get prereqs

    apt install ruby-dev libssl-dev
    
    gem update --system
    
  2. Configure Ruby Gem install without sudo

  3. install Gem bundler (without sudo):

    gem install jekyll bundler
    
  4. Download and extract latest Minimal Mistakes release.

  5. Install needed Gems:

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

    username : your GitLab or GitHub username

  6. On GitHub/GitLab, create a new blank repository username.github.io (for GitLab, username.gitlab.io).

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

  8. 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 -u origin master
    

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.

Writing blog posts

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

Jekyll Format tip

These tips are based on the Minimal Mistakes Jekyll theme

Enable search icon

in _config.yml

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.

remove default “layout: post” from migrated posts

This is useful for the default layout: single in _config.yml below.

sed -i '/layout: post/d' *.html

static nav buttons

edit _data/navigation.yml

Nice 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"]

Beautiful 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"

Remote author image

index.html:

author_profile: false

It’s smart to do this in case you later decide a page category should change, without screwing up your search engine results.

_config.yml:

permalink: /:title/

number of posts per archive page

_config.yml:

paginate: 10 # amount of posts to show

Notes

Jekyll install reference

Academic / professional web profile page