Jekyll을 사용하여 GitHub Pages 사이트 만들기

GitHub Pages, Jekyll, 그리고 설치법 몇가지와 문서오류에 대해

Table of contents

GitHub Pages

https://docs.github.com/ko/pages

GitHub를 통해 호스트되고 게시되는 퍼블릭 웹 페이지로서,
문서에 따르면 저장소를 먼저 만들라고 하지만, 테마를 사용할 경우 건너뛰도록 한다.

Adding a theme

Fork or clone a theme (repository)

https://github.com/cotes2020/jekyll-theme-chirpy

• Create a new fork → owner/username.github.io
• master → main
• 테마 초기화 : 로컬에서 tools/init.sh 혹은 직접 삭제 — Gemfile.lock, .travis.tml, _posts/, docs/, .github/workflows/pages-deploy.yml.hook 외 (pages-deploy.yml 으로 변경)

# 로컬 작업시,
git clone https://github.com/owner/username.github.io.git

cd username.github.io
bash tools/init.sh
bundle
npm install && npm run build

Configure a publishing source

게시 소스 구성을 GitHub Actions으로 변경하여, 미리 설치된 Jekyll 사이트를 패키징하거나 정적 HTML을 배포할 수 있다.

• repository/ Settings/ Code and automaiton - Pages/ Build and deployment/ GitHub Actions
• https://github.com/actions/starter-workflows/tree/main/pages

Jekyll

https://jekyllrb.com/docs/

지킬은 간단한 정적 사이트 생성기이다. 복잡함 없는 파일 기반 CMS.
콘텐츠를 가져와 Markdown 및 Liquid 템플릿을 렌더링하여 정적 웹사이트를 생성한다.
GitHub Pages의 엔진으로 GitHub 저장소에서 바로 사이트를 호스팅하는데 사용되고 있다.

Install

Requirements

• Ruby 2.7.0+
  • Moncef Belyamani, Why You Shouldn’t Use the System Ruby to Install Gems on a Mac
  • asdf | chruby | rbenv | rvm
• RubyGems
• GCC and Make

Instructions

gem install jekyll bundler
jekyll -v     # jekyll 4.4.1
bundler -v    # Bundler version 2.6.8

# 지킬을 구성한다. 테마를 사용할 경우 git clone 한다.
jekyll new username.github.io
cd username.github.io
# ├── _config.yml
# ├── _posts/
# │   └── 2025-06-07-welcome-to-jekyll.markdown
# ├── .gitignore
# ├── 404.html
# ├── about.markdown
# ├── Gemfile
# ├── Gemfile.lock
# └── index.markdown

bundle exec jekyll serve --livereload
# browse to http://localhost:4000
# press ctrl-c to stop.

# ├── _site/
# │   ├── 404.html
# │   ├── about
# │   │   └── index.html
# │   ├── assets
# │   │   ├── main.css
# │   │   ├── main.css.map
# │   │   └── minima-social-icons.svg
# │   ├── feed.xml
# │   ├── index.html
# │   └── jekyll
# │       └── update
# │           └── 2025
# │               └── 06
# │                   └── 07
# │                       └── welcome-to-jekyll.html
# └── .jekyll-cache

# If you are using Ruby version 3.0.0 or higher, step 5 may fail.
# You may fix it by adding webrick to your dependencies: bundle add webrick
bundle add webrick

Configuration

url: https://username.github.io
baseurl:
title:
description:
theme: jekyll-theme-minimal
permalink: none
# date    to /:categories/:year/:month/:day/:title:output_ext (default)
# pretty  to /:categories/:year/:month/:day/:title/
# ordinal to /:categories/:year/:y_day/:title.html
# none    to /:categories/:title.html
# page와 collection은 시간이나 범주가 없기 때문에 permalink는 무시된다.

markdown: GFM # or kramdown, GFM(GitHub Flavored Markdown), https://github.github.com/gfm/
comments: true
plugins:
  - jekyll-asciidoc
  - jekyll-target-blank
  ..._config.yml

# frozen_string_literal: true
source "<https://rubygems.org>"
gemspec
gem "jekyll-theme-chirpy", "~> 7.2", ">= 7.2.4"
gem "html-proofer", "~> 5.0", group: :test
platforms :mingw, :x64_mingw, :mswin, :jruby do
  gem "tzinfo", ">= 1", "< 3"
  gem "tzinfo-data"
end
gem "wdm", "~> 0.2.0", :platforms => [:mingw, :x64_mingw, :mswin]
gem 'jekyll-target-blank'Gemfile

Creating posts

• _posts/ 디렉토리에 새로운 YEAR-MONTH-DAY-NAME-OF-POST.MARKUP 파일을 만든다.
• frontmatter는 yaml 형식으로 작성한다.

---
layout: post
permalink:
published:
title:
date: YYYY-MM-DD hh:mm:ss +0900
categories: blog
tags: []

custom-variable:
---

이하 본문

{% highlight javascript %}
{% endhighlight %}

[Jekyll docs][links-1]
[Post-1]({% post_url yyyy-mm-dd-post %})

[links-1]: {% link /assets/files/doc.pdf %}_posts/yyyy-mm-dd-post.md

Git sync

# Bundler cache
.bundle
vendor
# if publishing your site with GitHub Pages, you can match production version of Jekyll
# by using the github-pages gem instead of jekyll in your Gemfile.
# In this scenario you may also want to exclude Gemfile.lock from your repository
# because GitHub Pages ignores that file.
Gemfile.lock

# Jekyll cache
.jekyll-cache
.jekyll-metadata
.sass-cache
_site

# RubyGems
*.gem

# NPM dependencies
node_modules
package-lock.json

# IDE configurations
.idea
.vscode

# Misc
_sass/vendors
assets/js/dist.gitignore

git add *
git status
git commit -m 'Initial commit'
git remote add origin https://github.com/owner/repository.git
git remote -v
git push origin main

ref.

• Namhoon Kim, jekyll, 2017.2, https://namhoon.kim/categories/jekyll/
• Chulgil Lee, 블로그 만들기 GitHub편 총정리, 2019, https://blog.chulgil.me/how-to-make-blog-using-github/
• Gwenneg Lepage, Blogging on GitHub Pages with minimal effort, 2024.8, https://gwenneg.com/2024/08/17/blogging-with-minimal-effort.html