A static website has noteworthy advantages over a dynamic one, like improved performance and security.

Here is a simple (and opinionated) way to build a static website, with Jekyll and GitHub Pages.

Step 1: Create the repository

Create a new repository named username.github.io, where username is your GitHub username, and clone it:

git clone https://github.com/username/username.github.io.git

Step 2: Create the bare minimum website structure

You can create a Jekyll GitHub Pages website with just a simple text editor, without being necessary to install any additional software on your computer (Ruby, Jekyll, Bundler).

Here is an example using the default Jekyll theme, minima, which is also one for the supported GitHub themes. Note that the pages in this example are created in Markdown, with front matter.

Create the files:

cd username.github.io
touch _config.yml index.md about.md

with the following content:

_config.yml - the Jekyll configuration file, in YAML format

theme: minima

title: Simple GitHub Pages website with Jekyll
author: your_name
description: >
  This is a simple GitHub Pages website with Jekyll

show_excerpts: false

minima:
  date_format: "%Y-%m-%d"

twitter_username: your_username
github_username: your_username
rss: rss

plugins:
 - jekyll-feed
 - jekyll-seo-tag

index.md - the homepage of your website

---
layout: home
---

about.md - the about page

---
layout: page
title: About
permalink: /about/
---

A simple GitHub Pages website with Jekyll.

Step 3: Push the files to GitHub

Although is recommended to test on your local computer before pushing the changes to GitHub, if you’re impatient (and followed the above steps), you can now push the newly created files and see your blog live at https://username.github.io

git add _config.yml index.md about.md
git commit
git push

Step 4: Add the first blog post

Create the first blog post:

mkdir _posts
cd _posts
touch 2019-06-30-first-blog-post.md

with some content, like the standard Lorem Ipsum passage, used since the 1500s:

---
layout: post
title: "First Blog Post"
categories: web
---

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore
eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt
in culpa qui officia deserunt mollit anim id est laborum.

Step 5: Add more files

Here are some recommended files for any git repository:

.gitignore - customize it for your needs

# local bundle/gems install
.bundle

# gemfile - used for local testing
Gemfile
Gemfile.lock

# generated site
_site

# on macOS
.DS_Store

.editorconfig

root = true

[*]
charset = utf-8
end_of_line = lf
indent_size = 2
indent_style = space
insert_final_newline = true
trim_trailing_whitespace = true

README.md - file that usually holds the description of the git repository content

# Simple GitHub Pages site with Jekyll

A simple GitHub Pages site with Jekyll.

Step 6: Customization

The following defaults are set by GitHub, which you are free to override in your _config.yml file:

github: [metadata]
encoding: UTF-8
kramdown:
  input: GFM
  hard_wrap: false
future: true
jailed: false
theme: jekyll-theme-primer
gfm_quirks: paragraph_end

GitHub Pages & Jekyll override the following settings in your _config.yml file, which you cannot change:

lsi: false
safe: true
source: [your repo's top level directory]
incremental: false
highlighter: rouge
gist:
  noscript: false
kramdown:
  math_engine: mathjax
  syntax_highlighter: rouge

Default plugins are enabled by default and cannot be disabled:

- jekyll-coffeescript
- jekyll-gist
- jekyll-github-metadata
- jekyll-paginate
- jekyll-relative-links
- jekyll-optional-front-matter
- jekyll-readme-index
- jekyll-default-layout
- jekyll-titles-from-headings

With gem-based themes, some of the site’s directories (such as the assets, _layouts, _includes, and _sass directories) are stored in the theme’s gem, hidden from your immediate view. Yet all of the necessary directories will be read and processed during Jekyll’s build process.

You can customize the default theme, minima, but pay attention to the theme version:

open $(bundle show minima)

Step 7: Test the website locally

You can set up a local version of your Jekyll GitHub Pages website by creating a Gemgile with the github-pages gem and test your website locally.

The Gemfile and Gemfile.lock files are used by Bundler to keep track of the required gems and gem versions you need to build your Jekyll website.

Install Jekyll and Bundler:

gem install --user-install bundler jekyll

Then, create the Gemfile:

touch Gemfile
echo "source 'https://rubygems.org'" >> Gemfile
echo "gem 'github-pages', group: :jekyll_plugins" >> Gemfile
bundle install --path .bundle
bundle exec jekyll serve

Now you can browse your website locally at http://127.0.0.1:4000

By the way, from time to time, make sure you have the updated version of the gems:

bundle update

That’s all folks!

Reference