목차
- 들어가며
- 1단계: GitHub 저장소(Repository) 생성 및 Pages 활성화
- 2단계: 블로그 기본 설정하기 (_config.yml)
- 3단계: Jekyll 핵심 디렉토리 구조 만들기
- 4단계: 블로그의 기본 레이아웃(Layout) 설계하기
- 5단계: 방문자를 맞이할 첫 페이지 만들기 (index.md)
- 6단계: RAG 연동을 위한 GitHub PAT(Fine-grained Token) 생성하기
- 마무리하며
- 유용한 참고 링크
들어가며
안녕하세요! 이번 포스트는 RAG(검색 증강 생성) 시스템이나 다른 자동화 도구가 생성한 콘텐츠를 자동으로 게시할 수 있는 블로그를 만드는 과정을 안내합니다. GitHub에서 무료로 제공하는 정적 사이트 호스팅 서비스인 GitHub Pages와, 마크다운이라는 간단한 텍스트 형식으로 웹사이트를 만들 수 있게 도와주는 Jekyll이라는 정적 사이트 생성기를 사용할 것입니다.
이 가이드를 끝까지 따라오시면, 여러분의 자동화 시스템이 GitHub API를 통해 직접 새로운 포스트를 작성하고 발행할 수 있는 멋진 블로그를 갖게 될 것입니다. 그럼, 지금부터 단계별로 차근차근 시작해 보겠습니다.
1단계: GitHub 저장소(Repository) 생성 및 Pages 활성화
가장 먼저 블로그의 기반이 될 GitHub 저장소를 만들어야 합니다. GitHub Pages는 특정 규칙에 따라 만들어진 저장소의 콘텐츠를 웹사이트로 자동 변환해 줍니다.
- GitHub에 로그인한 후, 새 저장소(New Repository) 생성 페이지로 이동합니다.
- 저장소 이름(Repository name)을 반드시
your-username.github.io형식으로 지정해야 합니다. (your-username부분은 실제 GitHub 사용자 이름으로 변경해 주세요.) 이 이름 규칙은 GitHub Pages가 개인 계정 블로그를 인식하는 핵심적인 부분입니다. - 저장소를 Public으로 설정하고, "Add a README file" 옵션을 체크하여 저장소를 생성합니다.
저장소가 성공적으로 생성되었다면, 이제 GitHub Pages 기능을 활성화할 차례입니다.
- 방금 만든 저장소의 메인 페이지에서 Settings 탭으로 이동합니다.
- 왼쪽 메뉴에서 Pages를 클릭합니다.
- Branch 섹션에서 소스를
main브랜치로 선택하고 Save 버튼을 누릅니다.
잠시 후 페이지 상단에 "Your site is live at https://your-username.github.io"라는 메시지가 나타납니다. 이제 여러분의 블로그가 인터넷에 공개되었습니다! 아직은 아무 내용이 없지만, 곧 채워나갈 것입니다.
2단계: 블로그 기본 설정하기 (_config.yml)
이제 우리 블로그의 기본적인 정보와 디자인 테마를 설정해 보겠습니다. Jekyll은 _config.yml이라는 특별한 파일을 통해 사이트 전체의 설정을 관리합니다.
- 저장소 메인 페이지에서 Add file > Create new file 버튼을 클릭합니다.
- 파일 이름 입력란에
_config.yml이라고 정확하게 입력합니다. - 파일 내용으로 아래 코드를 복사하여 붙여넣습니다.
title과description은 여러분의 블로그에 맞게 자유롭게 수정하세요.
title: My AI-Generated Blog
description: RAG 애플리케이션으로 생성된 포스트
theme: jekyll-theme-minimal- 각 항목은 다음과 같은 의미를 가집니다.
title: 브라우저 탭이나 검색 결과에 표시될 블로그의 제목입니다.description: 블로그를 설명하는 짧은 문장으로, 검색 엔진 최적화(SEO)에 도움을 줍니다.theme: 블로그의 전체적인 디자인을 결정하는 Jekyll 테마입니다. 우리는 GitHub에서 공식적으로 지원하는jekyll-theme-minimal테마를 사용했습니다. 다른 테마를 원하시면 GitHub Pages 지원 테마 목록에서 찾아 변경할 수 있습니다.
- 내용 작성이 완료되면 Commit changes 버튼을 눌러 파일을 저장합니다.
3단계: Jekyll 핵심 디렉토리 구조 만들기
Jekyll은 정해진 폴더 구조를 기반으로 동작합니다. 지금부터 우리 블로그에 꼭 필요한 두 개의 핵심 폴더, _posts와 _layouts를 만들겠습니다.
_posts: 게시글이 저장되는 공간
이름 그대로, _posts 폴더는 우리 블로그의 모든 게시글(포스트) 파일이 저장될 장소입니다. RAG 애플리케이션은 바로 이 폴더에 마크다운(.md) 형식의 글 파일을 생성하게 될 것입니다.
- 저장소 메인 페이지에서 Add file > Create new file을 클릭합니다.
- 파일 이름 입력란에
_posts/.gitkeep이라고 입력합니다._posts/까지만 입력하면 파일 이름이 아닌 폴더 경로로 인식됩니다. Git은 빈 폴더를 추적하지 않기 때문에,.gitkeep이라는 빈 파일을 생성하여_posts폴더가 저장소에 항상 존재하도록 보장하는 역할을 합니다. 파일 내용은 비워두어도 괜찮습니다.
- Commit changes 버튼을 눌러 파일을 저장합니다. 이제
_posts폴더가 성공적으로 생성되었습니다.
_layouts: 페이지 디자인 템플릿 보관함
_layouts 폴더에는 각 페이지가 어떻게 보일지를 정의하는 HTML 템플릿 파일들이 들어갑니다. 예를 들어 '블로그 글' 템플릿, '메인 페이지' 템플릿 등을 만들어두고 필요할 때마다 가져와서 내용을 채워 넣는 방식입니다. 이 폴더를 만드는 과정은 다음 4단계에서 자세히 다루겠습니다.
4단계: 블로그의 기본 레이아웃(Layout) 설계하기
이제 _layouts 폴더 안에 실제 디자인 템플릿 파일들을 만들어 보겠습니다. 우리는 모든 페이지의 기본이 될 default.html과 블로그 게시글 전용인 post.html 두 가지를 만들 것입니다.
default.html 생성: 모든 페이지의 기본 틀
default.html은 우리 블로그의 가장 바깥 껍데기 역할을 합니다. 모든 페이지에 공통으로 들어갈 HTML 구조(예: <html>, <body> 태그)를 여기에 정의합니다.
- Add file > Create new file을 클릭하고, 파일 경로를
_layouts/default.html로 지정합니다. - 아래의 HTML 코드를 복사하여 붙여넣고 커밋합니다.
<!DOCTYPE html>
<html>
<head>
<title>{{ page.title }}</title>
</head>
<body>
{{ content }}
</body>
</html>{{ page.title }}과{{ content }}는 Jekyll이 사용하는 Liquid 템플릿 언어의 변수입니다. Jekyll이 사이트를 빌드할 때,{{ page.title }}은 해당 페이지의 제목으로,{{ content }}는 각 페이지의 실제 마크다운 내용이 HTML로 변환된 것으로 자동 교체됩니다.
post.html 생성: 블로그 게시글 전용 양식
이제 default.html의 기본 구조를 그대로 사용하면서, 블로그 게시글에 필요한 제목과 작성일 등을 추가로 보여주는 post.html 템플릿을 만들겠습니다.
- 다시 Add file > Create new file을 클릭하고, 파일 경로를
_layouts/post.html로 지정합니다. - 아래 코드를 복사하여 붙여넣고 커밋합니다.
---
layout: default
---
<h1>{{ page.title }}</h1>
<p>{{ page.date | date_to_string }}</p>
<hr>
{{ content }}맨 위의 --- layout: default --- 구문은 이 post.html 템플릿이 default.html 레이아웃을 기반으로 한다는 것을 Jekyll에게 알려주는 중요한 설정입니다. 따라서 이 템플릿을 사용하는 페이지는 default.html의 <body> 태그 안에 <h1>(제목), <p>(날짜), <hr>, 그리고 실제 글 내용({{ content }})이 순서대로 표시됩니다.
5단계: 방문자를 맞이할 첫 페이지 만들기 (index.md)
이제 블로그의 대문 역할을 할 홈페이지를 만들 차례입니다. 이 페이지는 _posts 폴더에 있는 모든 게시글의 목록을 자동으로 보여주는 기능을 갖게 됩니다.
- 저장소 메인 페이지에서 Add file > Create new file을 클릭합니다.
- 파일 이름을
index.md로 지정합니다. - 아래의 코드를 복사하여 붙여넣고 커밋합니다.
---
layout: default
---
# 내 블로그에 오신 것을 환영합니다
## 포스트
<ul>
{% for post in site.posts %}
<li>
<a href="{{ post.url }}">{{ post.title }}</a>
</li>
{% endfor %}
</ul>- 여기서는 Jekyll의 Liquid 템플릿 언어로 된
for반복문이 사용되었습니다.{% for post in site.posts %}는 Jekyll에게_posts폴더 안에 있는 모든 글(site.posts)을 하나씩 순회하라는 명령어입니다. 각 글에 대해 제목({{ post.title }})과 고유 주소({{ post.url }})를 가져와<a>태그로 감싸진 목록(<li>) 항목을 생성합니다. 덕분에 우리는 새 글을 쓸 때마다 홈페이지를 수정할 필요 없이,_posts폴더에 파일을 추가하기만 하면 자동으로 목록이 업데이트됩니다.
6단계: RAG 연동을 위한 GitHub PAT(Fine-grained Token) 생성하기
마지막으로, 우리 RAG 애플리케이션이 GitHub 저장소에 접근하여 글을 쓸 수 있도록 허용하는 인증 키(PAT)를 생성해야 합니다. 보안을 위해 최소한의 권한만 가진 토큰을 만드는 것이 중요합니다.
- GitHub 우측 상단의 프로필 아이콘을 클릭한 후, Settings로 이동합니다.
- 왼쪽 메뉴 맨 아래에 있는 Developer settings를 클릭합니다.
- Personal access tokens > Fine-grained tokens를 선택하고 Generate new token 버튼을 클릭합니다.
- Token name에 "RAG Application Writer"와 같이 용도를 알아보기 쉬운 이름을 입력하고 Expiration에서 토큰의 유효 기간을 설정합니다. (보안을 위해 주기적으로 갱신하는 것이 좋습니다.)
- Repository access 섹션에서 "Only select repositories"를 선택한 후, 드롭다운 메뉴에서 방금 만든
your-username.github.io저장소를 선택합니다.
- Permissions 섹션으로 스크롤하여 Repository permissions를 찾은 뒤, Contents 항목의 접근 수준(Access)을 Read and write로 변경합니다. RAG 애플리케이션이 글을 읽고 쓸 수 있게 하는 핵심 권한입니다.
- 페이지 하단의 Generate token 버튼을 클릭합니다.
- 중요: 생성된 토큰은 화면에 단 한 번만 표시됩니다. 반드시 안전한 곳(예: 비밀번호 관리자)에 즉시 복사해 두세요. 이 페이지를 벗어나면 다시는 토큰 값을 확인할 수 없습니다.
이제 이 토큰을 사용하면 RAG 애플리케이션이 우리를 대신하여 블로그에 자동으로 글을 게시할 수 있게 됩니다!
마무리하며
모든 단계를 완료했습니다! 지금까지 우리는 RAG 애플리케이션의 콘텐츠를 담을 GitHub Pages 블로그를 성공적으로 구축했으며, 애플리케이션이 저장소에 안전하게 접근하는 데 필요한 Personal Access Token까지 생성했습니다. 방금 커밋한 파일들이 GitHub 서버에 반영되고 사이트가 다시 빌드되기까지는 몇 분 정도 소요될 수 있습니다.
잠시 후 https://your-username.github.io 주소로 접속하여 "내 블로그에 오신 것을 환영합니다"라는 제목이 보이는 홈페이지를 확인해 보세요.
이제 이 블로그는 RAG 애플리케이션으로부터 새로운 포스트를 받을 모든 준비를 마쳤습니다. 수고하셨습니다!
유용한 참고 링크
1. 시작하기 (Getting Started)
- GitHub Pages 빠른 시작 - GitHub에서 직접 사이트를 생성하고 배포하는 첫 단계
- Jekyll 빠른 시작 - 로컬 컴퓨터에 Jekyll을 설치하고 사이트를 실행하는 방법
2. 콘텐츠 작성 및 설정 (Content & Configuration)
- Jekyll 포스트 작성법 - 블로그 글을 작성하고 관리하는 가장 기본적인 방법
- Jekyll 디렉토리 구조 -
_posts,_layouts등 필수 폴더의 역할을 이해 - Jekyll 설정 파일 (_config.yml) - 사이트 제목, URL 등 전역 설정을 관리
3. 고급 설정 및 보안 (Advanced & Security)
- 사용자 정의 도메인 설정 - 개인 도메인(예:
my-blog.com)을 연결하는 방법 - Personal Access Token 생성 - 자동화된 배포나 API 사용 시 필요한 보안 토큰 생성법
- GitHub Pages와 Jekyll 호환성 - GitHub 환경에서의 플러그인 제한 등 제약사항 확인
