Jekyll + TeXt Theme으로 GitHub 블로그 개발하기

neori·2022년 2월 18일
Github 블로그jekyll
1

구글링을 하다가 우연히 깔끔한 UI의 Jekyll GitHub 블로그를 발견했다. 개발 공부를 하면서 기록을 남길 수 있는 블로그를 직접 만들어보고 싶어서 해당 블로그에서 사용한 TeXt Theme을 선택했다.

✨ 내가 원하는 블로그
1. 깔끔한 코드 테마
2. 우측 고정 목차 (벨로그처럼)
3. 익숙하고 편리한 MarkDown 문법 사용
4. 태그별 글 목록 (+ 날짜순 정렬)

공식 문서에 테마를 적용하는 방법이 잘 나와있기는 하지만, Jekyll 블로그의 치명적인 단점 중 하나인 어려운 커스터마이징 🤯  을 직접 겪고 나니 그냥 흘러보내기는 아쉬워서 기록을 남겨본다! ➡️ 블로그

1. GitHub Repository 생성

repository(이하 repo)의 이름은 (GitHub username).github.io로 한다.

public repo로 운영할 경우 repo를 따로 만들지 않고 테마 repo를 fork한 후 repo 이름을 (GitHub username).github.io로 변경해도 된다.

username과 name이 헷갈린다면 깃헙 우측 상단의 프로필을 클릭했을 때 보이는 'Signed in as (username)'을 확인하자!

2. 내 Repository 클론 + 테마 Repository 파일 다운로드

나는 블로그 repo를 private으로 관리하고 싶어서 따로 repo를 만들었다. 빈 repo를 로컬에 clone한 후, 테마 repo의 모든 파일을 다운로드한다. 다운로드한 파일을 모두 clone한 repo 폴더((username).github.io)로 옮긴다.

3. Ruby와 Jekyll 설치 + 로컬 환경에서 실행

로컬 환경에서 실행하기 위해서는 Ruby와 Jekyll이 설치되어 있어야 한다. 구체적인 설치 가이드는 여기에서 확인할 수 있다. 아래와 같이 ruby -v, gem -v, gcc -v, g++ -v를 터미널에 입력했을 때 정상적으로 잘 출력되면 설치가 된 것이다.
(macOS의 경우 기본적으로 설치되어 있는데 Ruby에 대한 환경 변수 설정이 필요할 수 있다. 참고)

그 후 Dependenceis를 설치하기 위해 번들러를 실행한다. 공식 문서에는 bundle install --path vendor/bundle 명령어로 나와 있지만, --path 옵션이 deprecated 됐으므로bundle config set --local path 'vendor/bundle'로 실행하면 된다.

이제 기본적인 개발 환경 설치는 끝! bundle exec jekyll serve로 개발 서버를 실행하면 http://localhost:4000/ 에서 미리 볼 수 있다. ctrl+c로 실행을 중단시킬 수 있다.

4. 빌드 및 배포

블로그((username).github.io) repo의 main(또는 master) 브랜치에 수정한 내용을 push하면 자동으로 빌드되고 몇 분 후에 수정한 대로 배포된 걸 확인할 수 있다.

해당 repo의 Settings > Pages를 확인하면 연결된 것을 확인할 수 있다.

5. 커스터마이징

초반에 언급한 것처럼 원하는 대로 꾸미는 게 쉽지 않다. 하지만 ruby를 처음 접해보더라도 프로그래밍 언어를 조금 다뤄봤다면 어렵지 않게 적용할 수 있다!

🧱 디렉토리 구조

├── _data
│   ├── locale.yml
│   ├── navigation.yml
│   └── variables.yml
├── _includes
│   ├── analytics-providers
│   ├── aside
│   ├── comments-providers
│   ├── markdown-enhancements
│   ├── pageview-providers
│   ├── scripts
│   ├── sidebar
│   ├── snippets
│   ├── svg
│   │   ├── icon
│   │   │   ├── social
│   │   │   │   ├── facebook.svg
│   │   │   │   └── ...
│   │   └── logo.svg
│   └── ...
├── _layouts
│   ├── 404.html
│   ├── archive.html
│   ├── article.html
│   ├── base.html
│   ├── home.html
│   ├── none.html
│   └── page.html
├── _sass
├── assets
│   ├── css
│   │   └── blog.scss
│   └── images
├── tools
├── 404.html
├── Gemfile
├── _config.yml
├── about.md
├── archive.html
├── favicon.ico
├── gulpfile.js
├── index.html
├── jekyll-text-theme.gemspec
└── package.json

공식 문서를 참고하면 더 다양한 옵션을 적용할 수 있는데, 내가 직접 블로그에 적용했던 기능을 위주로 정리했다. 기본 테마에서 수정하지 않은 부분은 생략했다.

기본 정보 입력

_config.yml

## => Site Settings
highlight_theme: tomorrow-night-bright
title: (블로그 이름)
description: >
  (블로그 설명)

## => Langauge and Timezone
lang: ko
timezone: Asia/Seoul

## => Author and Social
author:
	name: (블로그 저자 이름)
	avatar: (이미지 링크)
	bio: (자기소개)
	email: (이메일 주소)
	github: (https://github.com/username)
	medium: (https://medium.com/username)

## => GitHub Repository (if the site is hosted by GitHub)
repository: (GitHub username)/(GitHub username).github.io
repository_tree: main (또는 master)
	
## => Markdown Enhancements
mathjax: true
mathjax_autoNumber: true 

## => Analytics
analytics:
  provider: google
  
  google:
    tracking_id: (측정 ID)
    anonymize_ip: false
    
defaults:
  - scope:
      path: ''
      type: posts
    values:
      layout: article
      sharing: true
      license: false
      aside:
        toc: true
      show_edit_on_github: false
      show_subscribe: false
      pageview: true

기본적인 블로그 정보와 언어/시간대부터 블로그 하단에 들어가는 소셜 링크를 입력할 수 있다.

추가로 수식을 쓰기 위해 MathJax를 적용하고 방문자 수를 확인하기 위해 구글 애널리틱스에 등록했다. 참고 tracking_id에는 데이터 스트림 생성 후 확인할 수 있는 측정 ID(G-로 시작)를 넣으면 된다.

defaults에는 기본으로 적용할 옵션을 설정할 수 있는데 글 우측 고정 목차를 적용하기 위해 toc를 true로, 불필요한 것은 보이지 않게 false로 설정했다.

로고와 파비콘 변경

블로그 상단의 아이콘(로고)과 파비콘(favicon) 모양을 바꾸고 싶었다.

이모지 이미지(.png)를 .svg 형식으로 변환해서 _includes/svg/logo.svg를 대체했다.

파비콘은 공식 문서에서 추천한 이곳에서 변환한 후 기존의 파일들을 대체해서 assets 폴더에 넣었다. 공식 문서

헤더 수정

Home과 Archive만 사용하기 위해 헤더를 수정했다. 공식 문서를 참고해서 사이드바도 추가할 수 있다.

_data/navigation.yml

header:
  - titles:
      ko      : &EN       HOME
      ko-KR   : *EN
    url: /
  - titles:
      ko      : &EN       ARCHIVE
      ko-KR   : *EN

헤더의 배경 색은 흰색으로 바꿨다.

_sass/components/_header.scss

.header {
  background: #ffffff;
  ...
}

변경 사항이 적용된 헤더.

댓글 기능 추가

TeXt 테마에서 disqus, gitalk 등의 댓글 호스팅 서비스를 쉽게 적용할 수 있게 해놨다. 그 중 UI도 깔끔하고 가벼운 gitalk을 적용했다(현재는 막아놓음).

gitalk을 이용하려면 우선 블로그 사이트를 GitHub OAuth App에 등록해야 한다. gitalk은 각 포스트의 댓글이 repo의 issue로 추가되기 때문에 댓글이 저장될 public repo가 필요하다. 나는 블로그 repo와 별도로 관리하고 싶기도 했고 블로그 repo가 private이라서 repo를 따로 만들었다. 추가로 각 포스트마다 key를 부여해야만 해당 포스트에 댓글 기능을 쓸 수 있다. 참고

_config.yml

## => Comments
comments:
  provider: 'gitalk'
 
gitalk:
    clientID: (GitHub Application Client ID)
    clientSecret: (GitHub Application Client Secret)
    repository: (username을 제외한 repo 이름)
    owner: (GitHub username)
    admin:
      - (GitHub username)

gitalk dependencies 업데이트된 게 아직 TeXt 테마에는 적용이 안되어 있다. _data/variables.yml에서 gitalk 부분의 모든 버전을 1.2.2 ➡️ 1.7.2로 변경해줘야 에러 없이 적용된다.

그리고 gitalk은 로컬 환경에서 실행할 때는 안 보이는 게 맞다! 변경사항 적용 후 push하면 배포된 사이트에서 확인할 수 있다. 자신의 계정으로 로그인을 해두면 댓글 기능을 이용할 수 있다.

폰트 크기 조정

코드와 목차, 인용구(>)의 폰트 크기가 유독 작은 것 같아서 조금 키웠다.

_sass/common/_reset.scss

code {
  font-size: map-get($base, font-size-sm);
  ...
}

_sass/common/components/_toc.scss

.toc-h2,
.toc-h3,
.toc-h4,
.toc-h5,
.toc-h6 {
  &, a {
    font-size: map-get($base, font-size-sm);
    ...
    line-height: map-get($base, line-height-sm);
    ...
  }
}

_sass/components/_article-content.scss

blockquote {
  ...
  font-size: map-get($base, font-size-m);
  ...
}

목차(toc) 줄바꿈 처리

h1, h2, h3 태그에 해당되는 내용의 글자 수가 많을 때 단어 단위로 줄바꿈이 되도록 설정했다. white-space 속성을 pre-line으로 설정하면 된다.

_sass/common/components/_toc.scss

& > li {
  ...
  white-space: pre-line;
}

푸터 문구 수정

@ (블로그 이름) (연도)로만 표시되게 하고 싶어서 수정했다.

먼저 _data/locale.yml에 있는 COPYRIGHT_DATES를 모두 원하는 연도(e.g. 2022)로 수정한다.

그리고 _includes/footer.html를 수정한다(약 28~33라인).

<div>
  {%- include snippets/get-locale-string.html key='COPYRIGHT_DATES' -%}
  {%- assign _locale_copyright_dates = __return -%}
  © {{ site.title }} {{ _locale_copyright_dates }}
</div>

6. 글 작성하기

_posts 폴더에 Markdown 형식의 파일을 추가해서 포스팅을 할 수 있다. 먼저 각 파일의 제목은 2022-02-19-how-to-write-a-blog.markdown처럼 날짜와 텍스트가 하이픈으로 연결된 형태여야 한다. 공식 문서

그리고 각 파일 상단에 YAML Front Matter를 추가해야만 의도한대로 key와 제목(title), 요약/미리보기(excerpt), 태그 목록(tags)을 반영할 수 있다.

---
key: jekyll-text-theme
title: 'Jekyll + TeXt Theme로 GitHub 블로그 개발하기'
excerpt: 'Jekyll 설치부터 커스터마이징, 포스트 작성까지 모두 다뤄봤습니다 😎'
tags: [GitHub 블로그, Jekyll]
---

YAML Front Matter를 작성했다면 하단에 포스트 내용을 Markdown 문법으로 작성한다. 추가적으로 본문에 적용할 수 있는 스타일은 공식 문서에 설명되어 있다.

profile
neori
다음 포스트

[HTML] <a>에 target="_blank"와 rel="noreferrer noopener"를 함께 사용해야 하는 이유

0개의 댓글