데스크탑 환경 없이 깃허브에 정적 블로그 만들기 2부

데스크탑 환경 없이 깃허브에 정적 블로그 만들기 1부 뒤에 이어지는 내용이다.

3. 설정 지옥

방금 레포를 떠 온 그 상태에서 ‘https://b-613t.github.io’ 를 입력해봤자 화면은 404 에러만 뱉을 것이다. 이게 진짜 블로그가 되기 위해서는 _config.yml 파일을 수정해야 한다.

깃허브의 레포 관리하는 페이지에서 _config.yml을 클릭하고 에디트를 해야 한다. 가장 중요한 것은 “url”이다. 내 관리페이지인 https://github.com/b-613t/b-613t.github.io 에서 _config.yml의 내용을 보면 26행에 있다. 26행의 항목에

url: “https://’자기 깃허브 id’.github.io”

이렇게 입력하면 된다.

152행에는 baseurl: “” 라는 항목이 있는데 ‘https://b-613t.github.io/words’ 라는 서브 페이지를 쓰고 싶다면 baseurl: “/words” 로 수정하면 된다.

이정도 했으면 주소창에 b-613t.github.io라고 입력하면 jekyll chirpy의 기본 양식이 떠야 한다. 하지만 그 당연한 게 안 떠서 나처럼 죽을 고생을 하는 경우가 있을 수 있다. 깃허브 상단의 액션(Actions) 탭을 눌렀을 때 워크 플로우에 빨간색 X 표시만 구경하며 절망하고 있다면, 범인은 바로 ‘테스트 루틴’이라고 인공지능에게 배웠다..

해당 레포의 ‘/.github/workflows’ 폴더에 있는 ‘pages-deploy.yml’ 파일을 수정하는 것이다.

그 파일의 53부터 57행까지는 테스트에 대한 내용인데 전부 앞에다가 ‘#’를 붙여서 주석화 시켜서 해당 사이트와 연결을 끊어버리면 깐깐한 검증으로 내 사이트가 낙태 당하는 슬픔을 피할 수가 있다.

 # - name: Test site
 #   run: |
 #    bundle exec htmlproofer _site \
 #       \-\-disable-external \
 #      \-\-ignore-urls "/^http:\/\/127.0.0.1/,/^http:\/\/0.0.0.0/,/^http:\/\/localhost/"

이정도까지 고생을 했으면 지성이면 감천이라고 웬만하면 제킬 처피 양식이 화면에 나올 것이다. 안나온다면 나로서는 뭐라 할 말이 없다. 삼가 고인의 명복을 빈다.

나는 왜 되고 왜 안되는지에 대한 원리를 설명한다기보다는 천신만고 끝에 얻어낸 1회성 성공기에 대한 처절한 경험담을 남기는 것에 가까우니까. 이 글을 쓰는데 한문단 한문단은 모두 1시간 이상을 버려가면서 진행해 온 것들이다. 그 한 시간이 당신의 1분을 아껴준다면 그저 흐뭇하게 만족할 뿐이다.

_config.yml로는 다양한 설정이 가능한데 자세한 사용법은 전문적인 기술 블로거나 유튜버의 자료를 보는 걸 추천한다. 내가 해 본 것은 단지 삼성 덱스만으로 깃허브 페이지를 띄워보기라는 매우 특이한 영역에 한정된 것이기 때문이다.

4. 글 올려보기

글 올리기는 여태까지 겪었던 일에 비하면 식은 죽 먹기다. 레포 관리하는 페이지에서 _posts 폴더에 들어간 다음에 add file를 누른다.

Create new file과 Upload files가 있다. 아직 업로드는 안해봤고 새파일 만들기로 글을 써봤다. 파일명은 적당히 정하면 되는데 한글로 쓰면 주소창이 지저분해지므로 원래 제목을 영문으로 번역하는 게 좋다. 파일명에 띄어쓰기가 들어가면 %20으로 표시되어서 지저분하므로 띄어쓰기는 ‘-‘(하이픈)으로 대체하는 게 좋다. 파일명 형식은 YYYY-MM-DD 형식+제목.md로 정해야 제킬 처피가 인식한다고 한다.

예시: 2025-01-07-saul-the-discarded-pawn.md (한국어 원제목: ‘신이 버린 장기말, 사울’)

모든 것은 마크다운 문서로 써야하고 특히 가장 앞에다가 front matter를 넣어야 한다.

프론트 매터의 형식은 이렇다. 일단 문단의 위 아래를 ‘—‘로 감싼다. 그 사이에 글에 대한 메타 데이터를 넣는다. 예를 들어 이런 식이다.

---
title: "신이 버린 장기말, 사울"
date: 2025-01-07 00:00:00 +0900
categories: [기독교]
tags: [사울, 다윗, 사무엘, 성경해석]
description: "이스라엘 최초의 왕 사울이 왜 신의 버림을 받은 장기말이 될 수밖에 없었는지, 그의 비극적 삶을 고찰합니다."
---

title은 블로그에서 노출될 글의 제목이고 date, categories, tags에 따라서 블로그에 글이 정리된다. description은 홈 화면에서 블로그를 읽는 사람에게 글의 내용으로 노출되면서 검색 엔진에게 그 글의 성격을 간략히 설명하는 역할을 한다고 한다.

그밖에 다양한 내용들을 프론트 매터 에 넣어볼 수가 있다. 특이한 항목을 넣는다고 해서 딱히 어떤 효과가 발휘되는 건 아니지만, 글이 등록되는데 방해가 되는 건 아니라고 한다.

그렇게 새 글을 작성하고는 Commit changes 녹색 버튼을 누르면 그 글이 깃허브 페이지(블로그)에 등재된다. 누르자마자 등록되는 건 아니고 몇 분(짧게는 1-2분 길게는 15분 이상) 정도 걸린다. 다만 파일명을 잘못 지을 경우에는 글을 인식하지 못하는 경우도 생기는데 그럴 때는 과감하게 글을 지우고 새로 파일을 생성하는 게 낫다. 인공지능에게 제목을 영어로 지어달라고 할 때, 보이지 않는 특수문자(Zero-width space)가 끼어들기 때문일 수도 있다고 한다. 따라서 파일 제목은 귀찮지만 복붙보다는 직접 키보드로 입력하는 게 안정적이라고 한다.

마크다운에 익숙하지 않은 사람에 대한 팁인데, 마크다운은 엔터키를 많이 누른다고 외관상 줄을 많이 띄워주지 않는다. 문장을 다 쓰고 틀림없이 엔터를 눌렀다고 생각했더라도 다음 줄이 문장 끝에 이어붙는 경우도 있다. 확실하게 다음줄로 가고 싶다면 html태그인 <br>을 적극적으로 활용해야 한다. 원하는 글자가 출력되지 않는다면 ￦(역슬래시)도 적극적으로 사용해야 한다. 깃허브 프리뷰에 비해서 제킬 처피 테마로 만든 홈페이지가 받아들이는 마크다운 문법은 훨씬 엄격하므로 웹페이지가 원하는대로 출력이 될 수 있음을 인지하고 업로드 후에는 모니터링을 해보는 게 좋다.

5. 아무도 안찾는 글무덤에서 벗어나려면? : 구글에 출생신고 준비하기

나는 seo(검색 엔진 최적화)에 대해서는 완전히 문외한이다. 기존에 글을 써 왔던 티스토리 블로그는 그동안 태그 같은 것 조차 하나도 안 달고 글만 써왔다. 다만 깃허브 페이지는 아무런 seo작업을 하지 않는다면 아무도 모르는 4차원의 무인도가 될 가능성이 다분하다. 따라서 포탈 사이트에서 제공하는 블로그와 달리 깃허브 페이지는 검색 엔진에게 출생신고를 하는 게 중요하다.

구글 서치 콘솔(Google Search Console) 같은 곳에 자신의 홈페이지를 등록하는 건데, 그 점에 대해서는 아주 충실하게 다루는 페이지들이 많이 있으니 그쪽을 참조하면 된다. 다만 나는 거기에 등록할 때 필요한 sitemap.xml, feed.xml 문제에 대해서 다루고자 한다.

앞에서 설명한 것들을 그대로 따라서 사이트를 만들었다면 아마도 나와 똑같은 결과를 맞이하게 될 공산이 크다.

블로그를 처음 만들었을 때 ‘b-613t.github.io/sitemap.xml’ 을 주소창에 넣으면 제킬 처피의 테마가 뜨면서 화면 가운데에 404 에러 메시지가 나왔었다. feed.xml은 직접 넣어보지 않았지만 크게 다르진 않았을 것 같다. 만약 404 대신에 복잡한 코드들이 화면을 가득 메웠다면 이후의 내용을 읽지 않아도 되니까 축하한다.

하지만 그런 축복을 받지 못한 이들을 위해 내가 극복해 낸 해결책을 제시해보겠다. 이 문제를 해결하기 위해서도 역시나 죽을 고생을 했었는데 앞뒤 다 자르고 핵심만 말하겠다. 모든 사례를 해결해 줄 수 있는 모범답안이라고 말할 자신은 없고, 운좋게 트러블 슈팅에 성공한 사례일 뿐임을 우선 밝힌다.

루트에 있는 _config.yml과 Gemfile를 수정해야 하는데 일단 Gemfile를 수정해보자. 순서가 달라서 문제가 있을지 없을지는 모르겠지만 성공한 방법을 답습해서 시행착오를 피하는 것도 나쁘지는 않을 거다.

Gemfile을 깃허브 에디터에 띄우고 마지막 줄에 이걸 추가하고 저장한다. 참고로 내 페이지의 Gemfile에서는 16행에 붙여 넣으면 된다.

group :jekyll_plugins do
  gem "jekyll-feed"
  gem "jekyll-sitemap"
  gem "jekyll-seo-tag"
  gem "jekyll-paginate"
end

그리고 _config.yml의 끝에다가는 이걸 이어붙이고 저장한다. 순정 상태에서 손을 보지 않았다면 플러그인이라는 항목 자체가 존재하지 않을 것이다. 그럼에도 혹시 플러그인 항목이 있다면 겹치지 않도록 주의하면 된다.

plugins:
  - jekyll-sitemap
  - jekyll-paginate
  - jekyll-seo-tag

이렇게 내용을 추가하고서 자기 깃허브주소.io/sitemap.xml 과 주소/feed.xml을 주소창에 넣어보면 뭔가 복잡한 코드들이 보일 것이다. 이 세가지 플러그인들은 넣어도 에러를 일으키지 않는 검증된 것들이다. 그래도 xml파일들이 안 보인다면? 역시 삼가 고인의 명복을 빈다. 나로서는 해줄 수 있는 말이 없다. 시행착오로 될 때까지 뭐라도 하는 수밖에…

이렇게 생성된 sitemap.xml과 feed.xml은 레포 파일 목록에서는 보이지가 않는다. 이유는 모른다. 구글에 알려줄 파일이 있다는 것 자체만으로도 다행으로 여기고 행복해하면 된다.

앞서 말했지만 구체적인 출생신고 방법은 다른 블로거들이 검색엔진별로 매우 친절하게 설명해 놨으므로 거기서 찾아보면 된다. 내가 고통받으며 무익하게 버린 시간을 다른 사람들이 이 글로 다소나마 피할 수 있다면 그걸로 나는 만족이다.