1. Github 블로그 만들기#

시작#

이전에도 깃허브 블로그를 만들어서 사용했던 적이 있었지만, 글을 작성하는 과정이 생각보다 너무 불편해서 뜸해지기 일쑤였다. 특히 마크다운 문법을 직접 관리하거나, 이미지를 따로 정리하고, 작성한 글을 다시 배포하는 흐름이 너무 번거롭게 느껴졌다.

그러다 보니 처음에는 의욕적으로 시작했다가도, 어느 순간 글을 쓰는 일보다 블로그를 유지하는 일이 더 커져버렸고 결국 자연스럽게 방치하게 되었다. 그러던 , 회사 프로젝트를 위해 웹서핑을 하던 도중 정말 빛과 같은 깃헙을 발견하게 되었다.

Notion-Hugo#

Notion은 이전부터 꾸준히 사용하고 있던 개인적으로 최고의 메모장이었다.

프로젝트 기록, 공부한 내용, 참고 자료를 정리하는 데에는 충분히 편했고, 글을 쓰는 방식도 익숙했다. 무료 사용에 대해서도 매우 관대한 정책도 주요했다.

다만 Notion에 쌓인 기록을 외부에 블로그처럼 보여주기에는 아쉬운 점이 있었다. 페이지를 공유할 수는 있지만, 글 목록을 정리하거나 프로젝트별로 분류하고, 개인 블로그 형태로 관리하기에는 한계가 있었다.

그래서 이번에는 글 작성 도구를 새로 찾기보다, 이미 사용하고 있는 Notion을 그대로 활용하면서 Github Pages 기반 블로그로 보여줄 수 있는 구조를 만들고 싶었다.

그러던 중 Notion 페이지를 Markdown으로 변환하고 Hugo 블로그로 배포할 수 있는 Notion-Hugo를 발견했다!

link preview https://github.com/HEIGE-PCloud/Notion-Hugo github.com

Notion도 물론 페이지를 외부에 공개할 수 있다. 하지만 내가 원했던 것은 단순한 페이지 공유가 아니라, Notion에 쌓아둔 기록을 개인 블로그처럼 정리해서 보여주는 구조였다.

Notion-Hugo의 가장 큰 장점은 글을 작성하는 과정과 블로그를 보여주는 과정을 분리할 수 있다는 점이다. 글을 쓸 때는 기존처럼 Notion을 사용하면 된다. 제목, 목록, 이미지, 코드 블록, 표 같은 요소를 마크다운 문법으로 일일이 신경 쓰지 않고 Notion의 블록 편집 방식으로 직관적으로 작성할 수 있다.

작성된 글은 Notion-Hugo를 통해 Markdown으로 변환되고, Hugo는 이 Markdown 파일을 기반으로 정적 사이트를 생성한다. 즉, Notion은 글을 작성하고 관리하는 공간으로 사용하고, Hugo는 블로그의 테마와 레이아웃, 배포 가능한 정적 페이지 생성을 담당한다.

이 방식 덕분에 글 작성 도구를 새로 익히거나 기존 기록을 다른 곳으로 옮길 필요가 없었다. 평소처럼 Notion에 글을 쓰고, 변환과 빌드 과정을 거쳐 GitHub Pages에 배포하면 된다. 자동화까지 구성하면 글을 수정한 뒤 블로그에 반영하는 과정도 훨씬 단순해진다.

flowchart LR
    A[Notion에서 글 작성] --> B[Notion-Hugo로 Markdown 변환]
    B --> C[Hugo 정적 사이트 빌드]
    C --> D[Github 저장소에 Push]
    D --> E[Github Pages로 블로그 배포]

이 구조를 사용하면 글 작성 도구와 블로그 배포 구조를 분리할 수 있다.

글을 쓸 때는 Notion만 신경 쓰고, 배포할 때는 변환된 Markdown과 Hugo 빌드 결과만 관리하면 되는 점도 정말 매력적으로 다가와서 바로 사용해보기로 했다.

2. Notion-Hugo 설치#

설치 과정은 https://github.com/HEIGE-PCloud/Notion-Hugo 설명을 그대로 따라 하면 된다.

2.1. GitHub 저장소 생성#

먼저 Notion-Hugo 저장소에서 Use this template 버튼을 눌러 GitHub 저장소를 생성한다.

Notion-Hugo는 패키지만 설치해 사용하는 방식이 아니라, 제공되는 템플릿 저장소를 기반으로 블로그 저장소를 만드는 방식으로 시작한다. 저장소 공개 범위는 공식 설명에 따라 public으로 설정한다.

이렇게 생성한 저장소에는 Notion 페이지를 가져와 Markdown으로 변환하는 코드와 Hugo 사이트 구성이 함께 포함되어 있다.

2.2. Notion Integration 생성#

Notion-Hugo가 Notion 페이지의 내용을 가져오려면 Notion API 접근 권한이 필요하다.

이를 위해 Notion의 My integrations 페이지에서 새 내부 연결을 생성해주자.

연결 생성 과정에서 권한은 읽기 및 다음 항목을 포함해서 생성해야 한다

Read Content 권한은 Notion-Hugo가 Notion 페이지 내용을 읽어오기 위해 필요하다.

Read user information including email address 권한은 글의 front matter에 작성자 정보를 채우는 데 사용된다.

Integration 생성을 완료한 뒤에는 발급된 노션 엑세스 토큰을 복사해주자.

이 토큰은 이후 Notion-Hugo가 Notion API에 접근할 때 사용된다.

2.3. GitHub Action Secret 등록#

복사한 Internal Integration Token은 GitHub 저장소의 Secret으로 등록한다.

방금 생성한 GitHub 저장소로 이동한 뒤, 다음 메뉴로 들어가주자

Settings > Secrets and variables > Actions

이후 New repository secret 버튼을 누르고, 아래 이름으로 Secret을 추가한다.

NOTION_TOKEN

값에는 앞에서 복사한 Notion Internal Integration Token을 붙여넣는다.

토큰은 Notion API 접근 권한을 가진 값이므로 코드나 설정 파일에 직접 작성하지 않고, GitHub Actions Secret으로 관리한다.

2.4. Notion Template 복제#

다음으로 Notion-Hugo에서 제공하는 노션 템플릿 (Notion Template )을 Notion 워크스페이스로 복제해주자. 이 템플릿은 Notion-Hugo가 읽어올 콘텐츠 구조의 기준이 된다. 즉, 블로그 글과 페이지를 관리할 Notion 공간을 먼저 준비하는 단계다.

2.5. Notion Page에 Integration 연결#

복제한 Notion 페이지로 이동한 뒤, 우측 상단의 … 메뉴에서 앞에서 만든 연결 해당 페이지에 연결해주자

Integration을 생성했다고 해서 모든 Notion 페이지에 자동으로 접근할 수 있는 것은 아니다.

실제로 Notion-Hugo가 읽어야 하는 페이지에 Integration을 직접 연결해야 한다.

이 연결이 완료되어야 Notion-Hugo가 해당 Notion 페이지의 내용을 가져와 Markdown으로 변환할 수 있다.

2.6. Hugo 사이트 설정#

연결 설정이 끝나면, 해당 Notion 페이지의 공유 링크를 복사한다음, GitHub 저장소로 돌아가 루트의 notion-hugo.config.ts 파일을 열고, page_url 값을 복사한 Notion 페이지 링크로 변경해주자

page_url: "복사한_Notion_페이지_URL"

수정이 끝나면 GitHub에서 변경 사항을 commit해주자. 이 설정을 통해 Notion-Hugo는 어떤 Notion 페이지를 기준으로 콘텐츠를 가져올지 알 수 있다.

2.7. Cloudflare Pages 배포#

Notion-Hugo 공식 설명에서는 Cloudflare Pages를 이용한 배포 방식을 안내한다.

Cloudflare Pages 대시보드에서 Workers & Pages 메뉴로 이동한 뒤, 새 Pages 프로젝트를 생성한다.

이후 GitHub 저장소를 연결하고, 앞에서 만든 Notion-Hugo 저장소를 선택한다.

빌드 설정과 환경 변수는 다음과 같이 추가해주자

NOTION_TOKEN에는 앞에서 복사한 Notion Integration Token을 입력한다.

설정을 마친 뒤 Save and Deploy 버튼을 누르면 배포가 시작된다.

배포 성공!

2.8. Cloudflare KV Namespace 설정#

KV Namespace는 Cloudflare에서 제공하는 Key-Value 저장소이다.

Notion-Hugo는 Cloudflare Pages Functions를 사용한다.

이 Functions는 Notion 파일이나 이미지 정보를 요청할 때, 받아온 결과를 KV에 캐시해둘 수 있다.

즉, 매번 Notion API에 직접 요청하지 않고 Cloudflare 쪽 캐시를 먼저 확인하게 된다.

이렇게 하면 다음과 같은 장점이 있다.

Notion API 요청 횟수를 줄일 수 있다.
이미지나 파일 응답 속도가 빨라질 수 있다.
Notion 파일 URL이 만료되더라도 Functions가 다시 받아와 캐시를 갱신할 수 있다.
Cloudflare Pages의 정적 사이트에 필요한 작은 서버 기능을 붙일 수 있다.

먼저 Cloudflare 대시보드에서 KV Namespace를 생성한다.

Storage & Database > KV

새 KV Namespace를 생성한 뒤, Pages 프로젝트 설정으로 이동한다.

Workers & Pages > 프로젝트 > Settings > Bindings

여기에서 새 KV Namespace binding을 추가하고, 변수 이름은 다음과 같이 설정한다.


Type: KV namespace
Variable name: KV
KV namespace: notion-hugo-cache

여기서 변수 이름을 KV로 설정하는 이유는 코드에서 이 이름으로 접근하기 때문이다.

context.env.KV

Cloudflare 화면에서는 바인딩 이름이 context.env.KV처럼 표시된다.

이는 실제로 context.env.KV 코드로 접근할 수 있다는 의미이며, 정상적인 표시이다.

설정을 저장하면 Pages Functions가 notion-hugo-cache KV Namespace를 사용할 수 있게 된다

생성한 KV Namespace를 연결한 뒤 저장하자

바인딩 완료

2.9. baseURL 설정#

마지막으로 배포된 사이트의 도메인을 확인한 뒤, GitHub 저장소의 설정 파일에 반영한다.

먼저 Cloudflare Pages의 Deployments 탭에서 배포된 사이트 주소를 확인한다.

그다음 GitHub 저장소에서 notion-hugo.config.ts 파일의 base_url 값을 해당 도메인으로 변경한다.

또한 Hugo 설정 파일인 config/_default/config.toml의 baseURL 값도 같은 주소로 수정한다.

baseURL = "배포된_사이트_주소"

수정 후 commit하면 사이트 주소 기준으로 링크와 정적 리소스 경로가 올바르게 정리된다.

2.10. 동기화 방식#

Notion-Hugo는 기본적으로 매일 자정에 Notion과 동기화된다.

동기화 스케줄은 .github/workflows/cd.yml 파일에서 변경할 수 있다.

name: CD
on:
  schedule:
    - cron: '0 0 * * *'

수동으로 동기화하고 싶을 때는 GitHub 저장소의 Actions 탭으로 이동한 뒤, CD workflow를 선택하고 Run workflow를 실행하면 된다.

3. 배포 확인#

Notion에서 테스트 글을 작성

연동한 Notion 데이터베이스에 새 페이지를 하나 만들어보자

About 페이지를 만들어봤다

변경 내용을 저장소에 반영

로컬 프로젝트에서 Notion 내용을 가져온 뒤 Hugo 사이트를 빌드한다.

Vscode의 터미널에서 npm start 를 실행

Github에 변경내용을 Push

생성된 파일과 설정 변경 사항을 Github 저장소에 올린다

git add .
git commit -m "Update blog content"
git push

Cloudflare Pages 배포 상태를 확인

Cloudflare 대시보드에서 다음 경로로 이동해서 배포를 확인해보자

`Workers & Pages > 프로젝트 선택 > Deployments`

가장 최근 배포가 Success 상태가 될 때까지 기다린다.

배포된 사이트에 접속

Cloudflare가 할당해준 Pages 주소로 접속해보자

새로 작성한 글이 목록에 보이고, 글 페이지도 정상적으로 열리면 배포가 완료된 것이다.

Github 블로그 생성(1) - 시작