[Git] Github 깃허브 블로그 만들기, HTML 몰라도 가능! - Ruby 설치, 커스터마이징, 배포까지

저는 얼마전 Github 블로그를 만들었습니다.

네이버 블로그는 일상글, 티스토리 블로그에는 공부/연구 자료를 포스팅 하려고 합니다.

아직 깃허브 블로그의 용도는 정하지 않았으나

아마 제가 웹 개발이나 UI 디자인/기획을 찍먹하게 된다면 깃허브 블로그에 정리하지 않을까 싶어요.

 

깃허브 블로그는 만드는데 시간이 조금 들지만,

커스터마이징이 엄청나게 자유롭다는 장점이 있습니다.

Git, HTML, 특히 마크다운을 다뤄봤다면 만들 때 크게 어렵지 않았을 것 같은데..

저는 HTML을 다뤄본 적이 없어서 조금 헤맸답니다.

 

깃허브 블로그 만들기를 설명하는 많은 포스트들이 있지만

한 두개의 글만 봐서는 쉽지 않더라구요.

또 예전 버전의 프로그램을 사용하는 글들을 보고 오류를 잡기도 어려웠구요.

 

그래서 2023년 버전! 깃허브 블로그 만들기에 대해 알아보겠습니다.

제가 겪었던 몇가지 오류들에 대해 해결법도 하단에 제시해 두겠습니다.

 

 

아, 만들기 전 Git에 대해 기초 지식이 있으면 편한데

Git은 모르더라도 필요한 부분 서칭하면서 따라오시면 만드실 수 있을 거라고 생각됩니다.

혹시 모르니 링크를 하나 첨부하겠습니다.

 

이것도 github 블로그에서 업로드된 포스트네요. Evan Moon님이 정리하신 Git 기초 사용법입니다.

 

https://evan-moon.github.io/2019/07/25/git-tutorial/

Git 뉴비를 위한 기초 사용법 - 시작하기

 

---

1. Ruby 설치

https://rubyinstaller.org/downloads/

위의 링크에 들어가 Ruby를 설치해줍니다. Ruby는 로컬에서 Jekyll을 실행시키는 역할을 합니다.

우측에 3.2.X (64bit) 버전을 설치를 권장한다고 되어있네요.

하지만 Jekyll이 32bit이기 때문에, 32bit로 설치해주겠습니다.

WITH DEVKIT의 Ruby+Devkit 3.1.4-1 (x86)을 설치해줍니다.

 

 

2. Jekyll 설치

커맨드 창을 열어 아래와 같이 입력해줍니다. (윈도우 기준 cmd(명령 프롬프트) 켜서 입력하시면 됩니다.)

$ gem install jekyll
$ gem install bundler

설치 후 아래와 같이 입력했을 때 버전이 확인된다면 바르게 설치된 것입니다.

$ jekyll -v

$ bundler -v

 

3. Github에서 소스 fork 받기

깃허브 블로그를 만들기 위해 이 방법만 있는 것은 아닙니다.

소스를 zip파일로 받아서 로컬에서 굴린 다음 마지막에 github repository에 업로드 할 수도 있는데,

저는 그 방식으로 하니까 오류 수정하기가 너무 어렵더라구요.

그리고 fork 받는게 커스터마이징 할 때도 훨씬 편할 것 같아서 결국 이 방법으로 했답니다.

https://github.com/cotes2020/jekyll-theme-chirpy/fork 를 클릭해 본인의 깃허브 계정으로 소스를 fork 받습니다.

 

repository명을 <본인 github 아이디>.github.io 형식으로 바꿔줍니다.

나중에 배포까지 완료하고 나면 https://<본인 github 아이디>.github.io로 블로그에 접속할 수 있게 됩니다.

 

 

4. 소스를 로컬에 clone 받기

 

3단계까지 준비를 마치고 나면 본격적으로 소스를 커스터마이징 하기 전에 로컬로 clone 받아야 합니다.

커맨드 창에 아래와 같이 입력해 fork한 소스 파일을 clone 받아줍니다.

$ git clone https://github.com/{my_github_username}/{my_github_username}.github.io  

혹시 git이 처음이시라면 git부터 설치하셔야 합니다!

 

 

로컬에 clone을 받았다면, {my_github_username}.github.io 파일에 들어가 아래 항목들을 삭제해주어야 합니다.

• Gemfile.lock 파일 삭제
• .travis.tml 파일 삭제
• _posts 디렉토리 안에 작성되어 있는 마크다운 파일들 삭제
• docs 디렉토리 삭제
• .github/workflows/pages-deploy.yml.hook 파일을 제외한 나머지 파일 삭제
• .github/workflows/pages-deploy.yml.hook 파일명을 pages-deploy.yml로 변경

(애초부터 없던 파일이라면 신경쓰지 않으셔도 됩니다.)

 

 

5. 로컬에서 실행해보기

 

커맨드 창에 아래와 같이 입력하면 초기 상태의 블로그에 접속해볼 수 있습니다.

$ bundle install
$ jekyll serve
(혹은 $ bundle exec jekyll serve)

커맨트 창에 다음과 같이 표시되면 해당 링크(http://127.0.0.1:4000/)로 접속합니다.

 

 

 

6. _config.yml 수정으로 초기 커스터마이징

 

_config.yml 파일을 통해 블로그 제목, 프로필 이미지, 언어 등을 바꿀 수 있습니다.

lang을 ko로 설정해 기본 언어를 한국어로 바꿔주고, 시간도 Seoul로 바꿔주었습니다.

그리고 title, tagline(일종의 sub title), description, url, github username을 바꿔주었습니다.

아래 social에 social name, mail, link도 추가할 수 있습니다.

 

프로필 이미지는 아래와 같이 변경할 수 있습니다.

/assets/img 폴더에 프로필 이미지 파일(jpg)를 추가합니다. 저는 flower.jpg 파일을 추가했습니다.

위와 같이 _config.yml의 avatar에 해당 이미지 파일의 경로를 적어줍니다.

 

 

 

7. 마크다운 형식으로 포스트 작성하기

구색을 맞추기 위해 배포 전 임시로 포스트를 하나 작성해 봅시다.

jekyll은 마크다운 형식으로 포스트를 작성할 수 있습니다.

이때 파일 이름은 꼭 YYYY-MM-DD-제목.md 여야 합니다. (실제 연, 월, 일로 채워 넣어 주어야 합니다.)

작성한 파일은 /_posts 디렉토리에 넣어주어야 합니다.

파일 생성 방법은 여러가지가 있겠지만, 저는 아래와 같은 방식으로 접근했습니다.

 

_posts 디렉토리에 들어가 아래와 같이 실행해줍니다.

$ echo > 2023-07-26-첫글.md

이렇게 하면 2023-07-26-첫글.md라는 빈 마크다운 파일이 생성됩니다.

(포스트를 업로드하는 날짜와 원하는 포스트 제목으로 직접 바꿔주세요.)

((혹시 echo 명령어가 실행되지 않나요? 프로그램을 설치하셔야 합니다! 구글링 해보시기 바랍니다.))

 

 

마크다운 파일을 수정해줍시다. 저는 VS code를 사용해 수정했습니다.

마크다운 파일은 기본적으로 아래와 같은 형식에 따라 작성되어야 합니다.

---
title: 포스트 제목
date: YYYY-MM-DD HH:MM:SS +09:00
categories: [메인 카테고리 이름, 서브 카테고리 이름]
tags:
  [
    태그1, 태그2, 태그3...
  ]
---

이때 주의할 것은 title, categories, tags에는 직접 원하는 내용을 적어주는 것이 맞지만,

date는 위의 형식 그대로 적어야 한다는 것입니다.

 

아래는 제 첫글 포스트 마크다운 파일 예시입니다.

 

 

포스트 작성까지 마쳤다면 다시 jekyll로 serve해 http://127.0.0.1:4000/에 접속해봅시다.

아래와 같이 초기 설정된 것을 확인할 수 있습니다.

 

 

8. 배포하기

가장 큰 난관입니다. 저도 다섯번 정도 시도한 끝에 성공했답니다.

 

github의 repository에 들어가 Settings > Pages에서 Source를 GitHub Actions로 바꿔줍니다.

 

원래는 gh-pages 브랜치를 추가해 이런저런 설정을 해줘야하는데, 그 귀찮은 작업이 beta 기능을 통해 자동화된 것 같습니다. 혹시 여기서 오류가 발생한다면 아래 링크를 참고해보세요.

 

https://github.com/marketplace/actions/github-pages-action

GitHub Pages action - GitHub Marketplace

https://davidyang2149.dev/front-end/github-actions%EB%A5%BC-%EC%9D%B4%EC%9A%A9%ED%95%98%EC%97%AC-gh-pages-%EC%9E%90%EB%8F%99-%EB%B0%B0%ED%8F%AC%ED%95%98%EA%B8%B0/

Github Actions를 이용하여 gh-pages 자동 배포하기

https://www.irgroup.org/posts/jekyll-chirpy/

Jekyll Chirpy 테마 사용하여 블로그 만들기

 

 

 

이제 커맨드 창에서 아래와 같이 입력해 github에 소스 파일을 다시 올려줄 차례입니다.

$ git add -A

$ git commit -m "commit이름"

$ git push

commit이름은 나중에 github에서 몇번째 시도였는지 체크하는데에 쓰이는 부분이니

그냥 first commit, second, commit3등 아무거나 적으시면 됩니다.

 

 

성공적으로 build되었다면 Actions에서 아래와 같이 확인할 수 있습니다.

commit 이름이 sec였습니다.

 

 

pages build and deployment가 자동으로 끝난 것을 확인할 수 있습니다.

 

 

이제 배포되었습니다. https://<본인 github 아이디>.github.io로 블로그에 접속할 수 있습니다!

 

 

 

---

 

빌드 실패 오류 해결법

제가 겪었던 오류들에 한해 해결법을 적어보겠습니다.

 

 

---

 

1. js file does not exist.

 

깃허브 push 후 build 중에 assets/js/dist 파일 안에 js 파일이 없다며 build가 안 되는 오류.

직접 확인해보니 js 폴더에 dist라는 파일이 없었습니다. 이게 무슨..?

 

이때 해결법은

1) 로컬에서 dist 폴더 만들고 해당 js 파일들 직접 넣은 뒤 다시 push

혹은

2) github repository에 직접 dist 폴더 만들고 해당 js 파일들 직접 넣기

가 있습니다.

 

편한대로 하시면 될 것 같은데, 저는 1로 했더니 안 돼서 2로 했습니다.

로컬에는 있는데 push만 안 된 경우라면 2번 방법으로 시도해보세요.

 

dist.zip

0.01MB

위의 파일을 내려받아 넣으시면 됩니다.

 

 

 

---

 

2. Gemfile 오류

 

Gemfile이 작동해 배포가 안되는 오류.

 

clone 폴더에 .gitignore라는 텍스트 파일을 열어 다음의 내용을 마지막 줄에 붙여넣어 줍니다.

Gemfile.lock

 

 

 

---

3. .nojekyll 파일 없음

 

이 역시 없다면 추가해주면 됩니다.

 

여기서 팁은, 위에서 fork 받을 때 썼던 링크 https://github.com/cotes2020/jekyll-theme-chirpy/fork에서 View existing forks. 를 눌러 다양한 사용자들이 해당 소스를 사용하고 있는 것을 확인하는 것입니다.

잘 배포되어 굴러가고 있는 블로그의 파일들을 보고 본인의 파일들과 비교해 무엇이 없고 무엇이 이상한지 살펴보면, 미처 발견 못 한 오류를 찾을 수 있을겁니다.