Notion To Github Blog

노션으로 Github Page를 통한 블로그를 생성하는 법을 소개합니다.

• Updated:
정보 블로그

구글에 _Github Blog 만들기_를 검색하면 블로거들의 열의 아홉은 Jekyll 저장소를 포크하라고 안내합니다. 모든 사람들이 Jekyll이 편리한 정적 페이지 생성기라고는 하지만, 익숙하지 않는 사용자에게는 아래와 같은 어려움이 존재합니다.

  • Ruby. 대부분의 초보 프로그래머들은 Ruby를 다루는 방법을 알지 못합니다. 또한 블로그를 하나 운영하기 위해 새로운 프로그래밍언어를 습득하는 것은 많은 오버헤드를 유발합니다.
  • 뿐만 아니라 Ruby 프로젝트를 로컬에서 실행하려면 프로그램을 덕지덕지 깔아야 합니다. 블로그 하나 때문에 수 기가바이트짜리 프로그램을 설치하는 것은 좋은 방법은 아닙니다.
  • 마지막으로, Jekyll 테마들은 제작자들의 개성과 차별점을 드러내기 위해 복잡하고 가독성이 떨어지는 경우가 대부분이며, 오래되었습니다.

위와 같은 이유들로 인해 github.io로 시작하는 블로그는 저의 로망이었지만, 바쁜 일들로 수 년째 미뤄지고 있었습니다. 시간을 흘러, 그 로망을 실현할 수 있는 여유가 생기게 되었습니다.

학업이 마무리되어 가던 도중 유튜브에서 우연히 본 자동화 툴인 n8n사용법을 익히던 저는 Notion API를 자연스럽게 접하게 되었고, Notion에서 마크다운 파일을 다운받을 수 있는 notion-to-md라는 라이브러리도 알게 되었습니다. 이를 잘 조합하면, (1)Notion Page를 마크다운으로 변경하고, (2)마크다운을 HTML 정적 페이지로 생성할 수 있을 것 같았습니다. 다행히 Antigravity와 Github Action을 이용해서 어렵지 않게 구현할 수 있었습니다.

( 구현 끝자락에서 다시 생각해 보니, 노션에서 바로 HTML파일을 다운받을 수 있는 기능을 사용할 경우, 중간의 한 과정을 생략할 수 있을 것 같습니다. )

기본적인 작동 방식을 다이어그램으로 표시하면 아래와 같습니다.

flowchart TD
    GHA[Github Action] --1️⃣ Notion API
    ( API Key, Database ID )--> ND[Notion Database]
    ND --2️⃣ Notion Pages--> GHA

    GHA --3️⃣ notion-to-md--> MD[Page.md]
    MD --4️⃣ eleventy--> HTML
    HTML --> C[Github Pages]

사용법

Github Page설정하는 법

Github에서 노션의 글을 가져올 수 있도록 가져올 수 있는 권한(API Key)과 가져올 데이터베이스(ID)를 제공해 주어야 합니다. 이 장에서는 해당 방법을 안내합니다.

1. Database ID

노션을 이용하여 블로그의 글을 저장하고, Github에 글 목록을 공유할 데이터베이스를 생성합니다. 데이터베이스는 아래 그림과 같으며, 아래 표와 같은 속성들을 가져야 합니다.

image
속성명 유형(타입) 설명
이름 TItle (필수) 글 제목. 해당 페이지에 글을 쓰면 해당 글이 포스팅으로 올라갑니다.
작성상태 Status 작성 완료(띄어쓰기 주의) 상태인 글만 발행됩니다.
연동일시 Date 글 발행 일자 (비어있으면 페이지 새성일 사용)
요약 Text 썸네일과 함께 글 목록에 표시될 짧을 설명. 메타데이터로도 사용됩니다.
태그 Multi-select 태그 목록
카테고리 Select (필수) 카테고리
썸네일 URL 글 목록에 표시될 이미지의 주소. 없을 경우 기본 이미지

아래 링크는 데이터베이스의 템플릿입니다. 아래 데이터베이스와 동일하게 속성을 설정해야 합니다.

노션 데이터베이스 페이지

이후 Github에게 내 블로그 글이 존재하는 위치를 알려주기 위해 데이터베이스의 아이디를 획득하여 Github Action에 등록해야 합니다.

image

  1. 데이터베이스 블록을 클릭하고 링크 [복사 버튼]을 누르거나 데이터베이스 페이지에서 좌상단의 [공유] 버튿을 눌러 [링크 복사]버튼을 누를 경우 클립보드에 아래와 같은 형식의 url이 복사됩니다.

    https://www.notion.so/minmunui/2d97d2447d0180459bfbe4639be07f90?v=2d97d2447d01807288d1000ca62f7f04&source=copy_link

  2. 위와 같은 형식에서 본인의 id 바로 다음에 오는 값이 데이터베이스의 ID입니다. https://www.notion.so/minmuni/{database-id}?v={view-id} 형태

  3. 획득한 Database ID를 기억합니다.

2. 노션 API Key 획득

일반적으로 개인 노션 페이지는 외부에서 조회할 수 없습니다. 그러나 API Key를 발급받을 경우, 해당 Key를 통해 공개되지 않은 노션 페이지를 열람, 편집할 수 있습니다. 본 절에서는 API Key 발급과 권한 설정에 대해서 소개합니다.

아래 주소로 들어가 notion 계정으로 로그인합니다.

Notion – The all-in-one workspace for your notes, tasks, wikis, and databases.

A tool that connects everyday work into one space. It gives you and your teams AI tools—search, writing, note-taking—inside an all-in-one, flexible workspace.

Notion
Notion – The all-in-one workspace for your notes, tasks, wikis, and databases.

  1. 새 API 통합 버튼을 클릭합니다. 모든 API Key는 API 통합 단위로 관리되며, 각 Key를 가지고 있는 사용자가 어떤 데이터베이스에서 어떤 기능을 사용할 수 있는지를 사용할 수 있습니다.

    image

  2. 아래의 폼을 입력합니다.

    API통합 이름 : 아무 이름이나 지정

    관련 워크스페이스 : 위에서 만든 데이터베이스가 포함된 워크스페이스를 선택

    유형 : 프라이빗

  3. 이후 저장 버튼을 클릭하여 폼을 저장합니다.

    image

  4. 생성한 API통합에 마우스 커서를 갖다대면(Hover) 나타나는 설정 변경 버튼을 클릭합니다.

  5. 설정 버튼을 누르면 아래와 같이 API통합 시크릿이 드러나게 됩니다. [표시하기]버튼을 누르면 Key값을 얻을 수 있으며, 복사 버튼을 통해 클립보드에 복사할 수 있습니다.

    image

  6. 방금 생성한 API 통합 편집의 [사용 권한]탭에서 [편집 권한] 버튼을 클릭한 후, 이전에 생성했던 블로그 Database를 체크하고 [저장하기] 버튼을 클릭하여. 복사한 API키를 가진 사용하가 블로그 글을 열람하여 Github에 게시할 수 있도록 합니다.

    image

3. Github 저장소 설정하기

Github 저장소를 설정하여 Github블로그를 포스팅하는 법을 소개합니다.

Github Page는 Github 저장소에 업로드된 코드를 바탕으로 정적 페이지(HTML)을 생성하여 인터넷에 호스팅합니다. 때문에 Github Page를 이용한 블로그를 생성하기 위해서는 정적 페이지 생성에 필요한 코드들을 저장소에 불러와야 합니다.

Github의 Fork기능을 이용하면 다른 사람의 저장소를 본인의 계정 저장소로 복제할 수 있습니다.

  1. 아래 페이지에 접속하여 Star를 누르고, 저장소를 Fork합니다. Fork할 이름은 blog로 설정해야 오류를 피할 수 있습니다. 저장소를 포크하면 본인의 계정에 해당 저장소가 복제됩니다.

    https://github.com/minmunui/blog

  2. 복제한 저장소에는 Github 내부에서 특정 작업을 진행하도록 하는 Github Action이 설정되어 있습니다. 이 저장소의 Action은 (1)노션에서 마크다운 파일을 다운로드하고, (2)다운로드한 파일을 HTML파일로 변환하는 작업을 수행합니다.

    1. 저장소에 등록된 Action을 수행하게끔 설정하기 위해 저장소 페이지에서 [Settings]-[Pages]-[Build and deployment]에서 Source 항복ㅇ르 Github Actions로 변경합니다. (Beta 또는 일반 옵션)

  3. 저장소 페이지의 Actions 탭으로 이동하여 Deploy Eleventy Blog 워크플로우를 클릭합니다.

  4. 우측의 Run Workflow 버튼 > Run Workflow 를 클릭하여 수동으로 배포를 시작합니다. 코드를 수정하여 main 브랜치에 푸시하는 경우에도 배포가 시작됩니다.

  5. 배포가 성공하면 https://[내 아이디].github.io.blog에서 블로그를 확인할 수 있습니다.

글 발행 및 배포 자동화

Notion에 글을 쓰고 매번 Github에 들어가지 않아도, 원격으로 배포 버튼을 누르거나 자동으로 배포되게 할 수 있습니다.

1. 자동 배포 (매일 자정)

Github Action 동작에 스케줄러를 등록해 두었습니다. 이제 **매일 자정(UTC 00:00, 한국시간 오전 9:00)**에 자동으로 글을 가져와 배포합니다. 급하지 않은 수정사항은 기다리면 반영됩니다.

2. 수동 원격 배포 (단축어/외부 호출)

즉시 배포가 필요할 때, Github 웹사이트 접속 없이 URL 호출만으로 배포를 시작할 수 있습니다.

준비물

  1. Github Personal Access Token (PAT) 생성

호출 방법 (Curl / 단축어 / n8n)

아래 정보를 사용하여 POST 요청을 보내면 배포가 시작됩니다.

  • URL: https://api.github.com/repos/[Github아이디]/[저장소이름]/dispatches
  • Method: POST
  • Body:
  • Headers:
Previous VS Code + overleaf를 이용한 논문 작성 방법
Next 시작