GitHub Pages Basic Setup

ref: github.io setting reference Moving from velog.io/@naem1023 to naem1023.github.io. Customization, local posting, and the ability to deploy on a personal server if needed — these advantages seemed better than Velog’s simplicity.

Installation

# install ruby, jekyll, bundler
# Ubuntu
sudo apt install ruby ruby-dev build-essential

# m1 mac
brew install ruby rbenv
rbenv install 3.1.2
rbenv global 3.1.2

# install jekyll, bundler
gem install jekyll bundler
bundle update --bundler
bundle add webrick
bundle install --redownload

# set zshrc
echo 'eval "$(rbenv init - zsh)"' >> ~/.zshrc
echo 'export PATH="/usr/local/opt/ruby/bin:/usr/local/lib/ruby/gems/3.0.0/bin:$PATH"' >> ~/.zshrc


# setup jekyll theme and deploy
git clone {git address of jekyll theme}
mv ./minimal-mistakes {name of my github.io repository}
cd {{name of my github.io repository}}
git remote remove origin
git remote add origin {link of my github.io repository}
git push -u origin master

Testing

# Serve in local environment
bundle exec jekyll serve

YFM (YAML Front Matter)

• Specifies post metadata in markdown format.
• Written in YAML.
• Placed at the top of the markdown file as follows:

1
---
2
title:  "velog to github.io"
3
excerpt: "excerpt"
4
toc: true
5
toc_sticky: true
6
toc_label: "Page table of contents" # default: On this page
7
header:
8
  teaser: /assets/images/bio-photo-keyboard-teaser.jpg
9

10
categories:
11
  - Blog building
12
tags:
13
  - Blog
14
last_modified_at: 2022-04-06T08:06:00-05:00
15
---
16
YFM info can be accessed through double curly braces
17
e.g., {{ page.title }}, {{ page.last_modified_at }}

toc (table of contents) lets you display a list of H1-H6 headers on the right side of the page.

_config.yml

Contains Jekyll’s operational settings. While other files auto-reflect changes during the Jekyll server run, _config.yml changes only take effect on rebuild.

_config.yml content can be used like this:

1
<{{ site.url }}{{ site.baseurl }}/blog/>

When built with Jekyll, the above renders as <{{ site.url }}{{ site.baseurl }}/blog/>.

Comments

You can add a comment service by modifying the comments section in _config.yml. Planning to use utterances. ref: utterances setting blog

Open Graph Image

You can configure the Open Graph Protocol.

1
og_image    : "path"
2
og_description  : ""
3
og_title    : ""

What is Open Graph Protocol

Site Author

Information displayed in the left sidebar. Note that URLs should be written without quotes.

1
# Site Author
2
author:
3
  name             : "Hobbyist developer"
4
  avatar           : "/assets/images/bio-photo-keyboard.jpg"
5
  bio              : "A developer who codes for salary at work and for fun at home"
6
  location         : "South Korea"
7
  email            :
8
  links:
9
    - label: "Email"
10
      icon: "fas fa-fw fa-envelope-square"
11
      url: mailto:devinlifeidea@gmail.com
12
    - label: "Website"
13
      icon: "fas fa-fw fa-link"
14
      url: "https://devinlife.com"

Outputting

Settings for how the blog is displayed. The paginate value controls how many recent posts appear on the first page. Exceeding that number shows page numbers.

_posts, _pages

_posts contains date-based posts. _pages is for non-date-based posts. You can write posts that appear at specific URLs within the site.

Settings defined for _posts and _pages in _config.yml become the defaults for markdown posts. Redefining YFM in individual posts overrides those defaults.

Category, Tag

You can configure URLs and types for categories and tags.

Menu Bar

Editable via _data/navigation.yml.

Categories, Tag

Separate pages for categories and tags need to be created via Pages. Create pages with ‘/categories’ and ‘/tag’ as permalinks. Any URL works as long as it’s the base URL configured in _config.yml. Categories and tags have author profile set to false by default, so I changed it to true.

Category

If Categories contains all blog categories, individual category pages should show posts for that single category. Create pages with permalink as a sub-URL of categories.

1
---
2
title: "About building blog"
3
permalink: /categories/blog
4
layout: category
5
author_profile: true
6
taxonomy: blog-building
7
---

The taxonomy field specifies which category to display.

Comments

Make sure to set comments to true in _config.yml. I struggled with this for a while…

1
defaults:
2
  # _posts
3
  - scope:
4
      path: ""
5
      type: posts
6
    values:
7
      comments: true

I used utterances. Since it uses GitHub issues, if it’s a forked repo you must verify that issue creation is enabled. Unlike permalinks, the repo name must be enclosed in quotes.

1
repository: # GitHub username/repo-name e.g. "mmistakes/minimal-mistakes"
2

3
comments:
4
  provider: "utterances"
5
  utterances:
6
    theme: "github-light" # "github-dark"
7
    issue_term: "pathname"

If issue_term is “pathname”, comments map to GitHub issues based on the URL path. If the post title changes and the URL path changes, the comments disappear.

Font

You can change the font by editing scss files.

1
# In _sass/minimal-mistakes/_variables.scss, modify User Font
2
$sans-serif: -apple-system, BlinkMacSystemFont, {User Font}
3

4

5
# Add the following to assets/css/main.scss
6
@import url('https://fonts.googleapis.com/css?family=Noto+Sans+KR');
7

8
# Change font size in _sass/minimal-mistakes/_reset.scss
9

10
html {
11
  box-sizing: border-box;
12
  background-color: $background-color;
13
  font-size: 14px;
14

15
  @include breakpoint($medium) {
16
    font-size: 14px;
17
  }
18

19
  @include breakpoint($large) {
20
    font-size: 16px;
21
  }
22

23
  @include breakpoint($x-large) {
24
    font-size: 18px;
25
  }
26

27
  -webkit-text-size-adjust: 100%;
28
  -ms-text-size-adjust: 100%;
29
}

Date Display

Modifying _config.yml as follows removes the reading time and shows the posting date instead. Settings placed here automatically apply to all posts’ YFM. ref: Reference github comment

1
# Defaults
2
defaults:
3
  # _posts
4
  - scope:
5
      path: ""
6
      type: posts
7
    values:
8
      layout: single
9
      author_profile: true
10
      read_time: false
11
      comments: true
12
      share: true
13
      related: true
14
      show_date: true