포스트

Github 블로그에 구독 & 알림 시스템 구축하기

게시 업데이트
Masanam blog 업데이트 뉴스레터 예시
Masanam blog 업데이트 뉴스레터 예시
By Masanam
views 0

GitHub Pages로 블로그를 운영하다 보면 한 가지 아쉬운 점이 있습니다.

글을 올려도 방문자가 다시 찾아오지 않으면 새 글이 올라왔는지 알기 어렵다는 점입니다.
댓글 기능과 좋아요 기능을 붙인 뒤에는, 자연스럽게 새 글 알림 기능도 있으면 좋겠다는 생각이 들었습니다.

이번에는 블로그에 구독 버튼을 추가하고, 이메일을 입력한 방문자에게 새 글 업데이트를 알려줄 수 있는 구조를 만들어보았습니다.

개인정보와 실제 서버 설정값은 제외하고, 전체 흐름만 간단하게 정리합니다.

목표

이번 작업에서 만들고 싶었던 기능은 아래와 같았습니다.

  • 블로그 사이드바에 Subscribe 버튼을 추가한다.
  • 버튼을 누르면 구독 입력 모달이 열린다.
  • 이메일을 입력하면 서버에 구독 신청이 저장된다.
  • 구독 확인 메일을 보내고, 사용자가 확인하면 구독이 활성화된다.
  • 새 글이 배포되면 구독자에게 알림 메일을 보낼 수 있다.
  • 현재 구독자 수도 버튼에 함께 표시한다.

GitHub Pages는 정적 사이트이기 때문에 이메일 저장, 인증 메일 발송, 새 글 알림 같은 작업을 직접 처리할 수 없습니다.

그래서 기존 댓글과 좋아요 기능에 사용하던 서버에 작은 API를 추가하는 방식으로 구성했습니다.

전체 구조

전체 구조는 아래와 같습니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

GitHub Pages / Jekyll 블로그
  |
  |  Subscribe 버튼 클릭
  v
구독 모달
  |
  |  POST /api/subscribe
  v
Oracle Cloud API 서버
  |
  |  구독 신청 저장
  v
SQLite
  |
  |  구독 확인 메일 발송
  v
메일 발송 서비스

새 글 알림은 배포 과정과 연결했습니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

새 글 작성
  |
  v
GitHub push
  |
  v
GitHub Actions 배포
  |
  |  변경된 새 글 확인
  v
알림 API 호출
  |
  v
구독자에게 이메일 발송

블로그는 여전히 GitHub Pages에서 정적으로 배포됩니다.
동적인 기능만 별도 API 서버에서 처리하는 구조입니다.

1. Subscribe 버튼 만들기

먼저 왼쪽 사이드바에 Subscribe 버튼을 추가했습니다.

처음에는 버튼 아래에 이메일 입력 폼을 바로 보여주는 방식도 생각했지만, 사이드바가 복잡해지고 가독성이 떨어졌습니다.

그래서 버튼을 누르면 모달이 열리도록 바꾸었습니다.

모달에는 아래 내용을 넣었습니다.

  • 블로그 구독 안내 문구
  • 이메일 입력창
  • 구독 신청 버튼
  • 구독 처리 결과 메시지

안내 문구는 너무 길지 않게 정리했습니다.

1
2

블로그의 새로운 글과 최신 BI 연구 논문 리뷰,
관련 동향을 담은 뉴스레터를 이메일로 받아보실 수 있습니다.

단순한 입력 폼처럼 보이지 않도록, 블로그 테마에 맞춰 모달 배경과 버튼 스타일도 조금 다듬었습니다.

2. 구독 API 만들기

구독 신청은 API 서버에서 처리하도록 했습니다.

필요한 API는 크게 네 가지였습니다.

1
2
3
4

POST /api/subscribe
GET  /api/subscribe/confirm
GET  /api/unsubscribe
GET  /api/subscribers/count

POST /api/subscribe는 사용자가 입력한 이메일을 저장하고, 구독 확인 메일을 보냅니다.

구독자가 메일 안의 확인 버튼을 누르면 GET /api/subscribe/confirm이 호출되고, 해당 이메일의 상태가 활성화됩니다.

구독 취소는 GET /api/unsubscribe로 처리했습니다.

마지막으로 GET /api/subscribers/count는 현재 활성 구독자 수를 반환합니다.
이 값을 사이드바의 Subscribe 버튼 옆에 표시하도록 했습니다.

예를 들어 구독자가 2명이면 아래처럼 보이게 됩니다.

1

Subscribe 2

3. 구독 정보 저장

구독 정보는 가볍게 SQLite에 저장했습니다.

저장해야 하는 정보가 많지 않기 때문에, 별도의 큰 데이터베이스까지는 필요하지 않았습니다.

대략 아래와 같은 정보만 있으면 충분했습니다.

  • 이메일
  • 구독 상태
  • 확인 토큰
  • 구독 취소 토큰
  • 생성 시간
  • 확인 시간

여기서 중요한 점은 구독 신청과 구독 완료를 분리하는 것입니다.

이메일을 입력했다고 바로 구독 완료로 처리하면, 다른 사람의 이메일을 마음대로 등록할 수 있습니다.
그래서 반드시 확인 메일을 보낸 뒤, 사용자가 직접 확인 버튼을 눌렀을 때만 활성 구독자로 처리했습니다.

4. 메일 발송 서비스 연결

메일 발송은 외부 SMTP 서비스를 사용했습니다.

직접 메일 서버를 운영할 수도 있지만, SPF, DKIM, DMARC 같은 설정을 제대로 하지 않으면 메일이 스팸으로 분류될 가능성이 높습니다.

그래서 메일 발송 전용 서비스를 연결하고, 도메인 인증을 진행했습니다.

도메인 쪽에는 대략 아래와 같은 DNS 레코드가 필요했습니다.

1
2
3
4

DKIM
SPF
DMARC
MX

이 설정이 끝나면 내 도메인 이름으로 메일을 보낼 수 있습니다.

물론 실제 API key나 SMTP 비밀번호는 저장소에 넣지 않았습니다.
이런 값은 서버의 환경변수 파일에만 보관했습니다.

5. 구독 확인 메일 디자인

구독 확인 메일은 단순 텍스트로 보내도 되지만, 블로그에서 보이는 구독 모달과 분위기가 크게 다르면 조금 어색했습니다.

그래서 확인 메일과 구독 완료 페이지도 비슷한 톤으로 다듬었습니다.

메일에는 아래 내용만 간단히 담았습니다.

  • 블로그 구독 확인 안내
  • 구독 확인 버튼
  • 본인이 신청하지 않았다면 무시해도 된다는 문구

구독 완료 페이지에는 구독이 정상적으로 완료되었다는 메시지와 블로그로 돌아가는 버튼을 넣었습니다.

6. 새 글 알림 자동화

가장 중요한 부분은 새 글이 올라갔을 때 자동으로 메일이 가도록 만드는 것이었습니다.

이를 위해 GitHub Actions 배포 과정에 알림 스크립트를 추가했습니다.

흐름은 단순합니다.

1
2
3
4
5

1. GitHub Actions가 배포를 시작한다.
2. 이번 push에서 변경된 _posts 파일을 찾는다.
3. 새 글 또는 수정된 글이 있으면 제목과 URL을 정리한다.
4. 알림 API를 호출한다.
5. API 서버가 활성 구독자에게 메일을 보낸다.

알림 API는 아무나 호출하면 안 되기 때문에, 별도의 토큰을 사용했습니다.

GitHub 저장소에는 토큰 값을 직접 넣지 않고, GitHub Actions Secret에 저장했습니다.

1

SUBSCRIBE_NOTIFY_TOKEN

배포 스크립트는 이 값을 읽어서 서버 API를 호출합니다.

7. 현재 구독자 수 표시

마지막으로 사이드바 버튼에 현재 구독자 수를 표시했습니다.

페이지가 로드되면 브라우저에서 구독자 수 API를 호출합니다.

1

GET /api/subscribers/count

서버가 아래처럼 응답하면,

1
2
3

{
  "count": 2
}

버튼에는 아래처럼 표시됩니다.

1

Subscribe 2

구독자가 없거나 API 호출에 실패한 경우에는 숫자를 숨기도록 했습니다.
블로그 기능이 API 상태에 과하게 의존하지 않도록 하기 위해서입니다.

8. 구독 모달과 업데이트 메일 예시

구독 버튼을 누르면 아래와 같은 모달이 열립니다.
블로그에 실제로 붙여둔 구독 모달의 HTML 구조와 스타일을 그대로 사용한 예시입니다.

실제로 새 글이 발행되면 아래와 같은 형태의 메일을 받게 됩니다.
서버에서 사용하는 newsletter_shell() 템플릿을 바탕으로 만든 이미지 예시이며, 이 이미지를 글 썸네일로도 사용했습니다.

정리

이번 작업으로 GitHub Pages 블로그에 구독과 알림 기능을 붙일 수 있었습니다.

정리하면 구조는 이렇습니다.

1
2
3
4
5
6
7
8
9
10
11
12
13

Jekyll 블로그
  |
  |  구독 UI
  v
API 서버
  |
  |  구독자 저장 / 확인 / 취소 / 카운트
  v
SQLite
  |
  |  확인 메일 / 새 글 알림
  v
메일 발송 서비스

정적 블로그는 관리가 편하고 빠르다는 장점이 있지만, 댓글, 좋아요, 구독 같은 기능을 붙이려면 별도의 서버가 필요합니다.

이번에는 이미 사용 중이던 API 서버에 구독 기능을 하나 더 얹는 방식으로 해결했습니다.

앞으로는 단순히 새 글 알림뿐 아니라, Bioinformatics 논문 리뷰나 흥미로운 기술 동향도 함께 정리해서 보내볼 수 있을 것 같습니다.

아직 구독자가 많지는 않겠지만, 블로그가 조금 더 살아 있는 공간처럼 느껴지게 된 점이 가장 마음에 듭니다.

-2026.05.29 by Masanam-

Project
github-pages jekyll subscribe newsletter api oracle-cloud resend github-actions
이 기사는 저작권자의 CC BY 4.0 라이센스를 따릅니다.

댓글

내용에 대한 오류 수정 요청, 질문은 언제나 환영입니다. 자유롭게 댓글을 남겨주세요! (하지만 부적절한 댓글은 삭제될 수 있습니다)

비공개 문의

공개 댓글과 별도로 남기고 싶은 내용은 문의 페이지를 이용해 주세요.

비공개 문의하기