시작하기

Notion 설정

Noxion은 Notion 데이터베이스에서 콘텐츠를 읽습니다. 이 페이지에서는 각 페이지 타입별 데이터베이스 설정 방법, 지원하는 스키마 속성, 페이지 ID를 가져오는 방법을 설명합니다.

데이터베이스 만들기

Notion에서 새 전체 페이지 데이터베이스를 만듭니다 (인라인 데이터베이스가 아님). 이 차이가 중요합니다: Noxion은 루트 페이지를 호출하여 모든 페이지를 열거하며, 인라인 데이터베이스는 해당 페이지의 블록 트리를 통해 동일한 방식으로 직접 접근할 수 없습니다.

전체 페이지 데이터베이스를 만들려면:

새 페이지를 만듭니다
/database를 입력하고 Table — Full page를 선택합니다

블로그 데이터베이스 스키마

필수 속성

속성 이름	타입	필수	설명
`Title`	제목	✅	포스트 제목. 모든 Notion 데이터베이스에 기본으로 포함됩니다.
`Public`	체크박스	✅	체크된 포스트만 페치되어 게시됩니다.

권장 속성

속성 이름	타입	설명
`Published`	날짜	발행일. 없으면 포스트가 마지막 수정 시간순으로 정렬됩니다.
`Tags`	다중 선택	포스트 태그. 태그 페이지(`/tag/[tag]`)와 `article:tag` OG 메타데이터에 사용됩니다.
`Category`	선택	포스트 카테고리. 브레드크럼과 `article:section` OG 메타데이터에 사용됩니다.
`Slug`	텍스트 (리치 텍스트)	커스텀 URL 슬러그 (예: `my-first-post`). 없으면 Notion 페이지 ID로 대체됩니다.
`Description`	텍스트 (리치 텍스트)	메타 설명. 160자로 잘립니다.
`Author`	텍스트 (리치 텍스트)	이 포스트의 작성자 이름. 사이트 레벨 `author`를 오버라이드합니다.

대소문자 구분 없는 매칭

Noxion은 속성 이름을 대소문자 구분 없이 매칭합니다. public, Public, PUBLIC 모두 작동합니다. 알 수 없는 추가 속성은 무시됩니다.

데이터베이스 예시

┌──────────────────────────────────────────────────────────────────────────┐
│ Title                    │ Public │ Published   │ Tags          │ Category │
├──────────────────────────────────────────────────────────────────────────┤
│ My First Blog Post       │ ✓      │ Jan 15 2025 │ react, next   │ Web Dev  │
│ Getting Started with Bun │ ✓      │ Feb 3 2025  │ bun, tooling  │ Tools    │
│ Draft: AI in 2025        │        │             │ ai            │          │
└──────────────────────────────────────────────────────────────────────────┘

문서 데이터베이스 스키마

문서 사이트에는 다음 속성을 사용하세요:

속성 이름	타입	필수	설명
`Title`	제목	✅	페이지 제목
`Public`	체크박스	✅	체크하면 게시
`Section`	선택	권장	사이드바에서 문서를 그룹화 (예: "시작하기", "API")
`Order`	숫자	권장	섹션 내 정렬 순서 (낮을수록 먼저)
`Slug`	텍스트	권장	커스텀 URL 슬러그
`Description`	텍스트	—	메타 설명
`Version`	텍스트	—	버전 태그 (예: "v2", "latest")

데이터베이스 예시

┌───────────────────────────────────────────────────────────────────────────┐
│ Title                 │ Public │ Section          │ Order │ Version       │
├───────────────────────────────────────────────────────────────────────────┤
│ Introduction          │ ✓      │ Getting Started  │ 1     │ latest        │
│ Installation          │ ✓      │ Getting Started  │ 2     │ latest        │
│ Configuration         │ ✓      │ API Reference    │ 1     │ latest        │
│ Plugin API            │ ✓      │ API Reference    │ 2     │ latest        │
└───────────────────────────────────────────────────────────────────────────┘

Section 속성은 사이드바 내비게이션에서 페이지를 그룹화하는 데 사용됩니다. 섹션 내 페이지는 Order로 정렬됩니다.

포트폴리오 데이터베이스 스키마

포트폴리오/프로젝트 사이트에는 다음 속성을 사용하세요:

속성 이름	타입	필수	설명
`Title`	제목	✅	프로젝트 이름
`Public`	체크박스	✅	체크하면 게시
`Technologies`	다중 선택	권장	기술 스택 (예: "React", "TypeScript", "Node.js")
`Project URL`	URL 또는 텍스트	—	라이브 프로젝트 링크
`Year`	텍스트	—	프로젝트 제작 연도
`Featured`	체크박스	—	프로젝트를 눈에 띄게 표시
`Slug`	텍스트	권장	커스텀 URL 슬러그
`Description`	텍스트	—	메타 설명

데이터베이스 예시

┌────────────────────────────────────────────────────────────────────────────────┐
│ Title              │ Public │ Technologies         │ Year │ Featured │ URL     │
├────────────────────────────────────────────────────────────────────────────────┤
│ Noxion             │ ✓      │ TypeScript, React     │ 2026 │ ✓        │ nox.io  │
│ CLI Tool           │ ✓      │ Rust, CLI             │ 2025 │          │         │
│ Design System      │ ✓      │ React, Storybook      │ 2024 │ ✓        │ ds.io   │
└────────────────────────────────────────────────────────────────────────────────┘

스키마 매핑

Noxion은 페이지 타입별 규칙을 사용하여 Notion 데이터베이스 속성을 페이지 필드에 자동 매핑합니다. 위의 속성 이름을 따르면 별도 설정이 필요 없습니다.

Notion 데이터베이스가 다른 속성 이름을 사용하는 경우, noxion.config.ts에서 매핑을 오버라이드할 수 있습니다:

collections: [
  {
    databaseId: process.env.DOCS_NOTION_ID!,
    pageType: "docs",
    pathPrefix: "docs",
    schema: {
      section: "Department",    // Notion 속성 이름 → Noxion 필드
      order: "Sort Order",
      version: "Release",
    },
  },
],

페이지 ID 가져오기

페이지 ID는 데이터베이스 페이지를 고유하게 식별하는 32자 16진수 문자열입니다.

브라우저 URL에서

Notion 데이터베이스를 엽니다. URL이 다음과 같이 보입니다:

https://notion.so/yourworkspace/Blog-abc123def456789012345678901234
                                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                                      이것이 페이지 ID입니다 (32자)

ID가 하이픈이 있는 UUID 형식으로 나타날 수도 있습니다: abc123de-f456-7890-1234-567890123456. 두 형식 모두 동일합니다.

공유 메뉴에서

데이터베이스를 엽니다
오른쪽 상단의 공유를 클릭합니다
링크 복사를 클릭합니다
URL에서 32자 16진수 문자열을 추출합니다

ID 설정

단일 블로그의 경우:

# .env
NOTION_PAGE_ID=abc123def456789012345678901234

멀티 데이터베이스의 경우:

# .env
NOTION_PAGE_ID=abc123...           # 블로그 데이터베이스
DOCS_NOTION_ID=def456...           # 문서 데이터베이스
PORTFOLIO_NOTION_ID=ghi789...      # 포트폴리오 데이터베이스

비공개 페이지 (선택사항)

기본적으로 Noxion은 익명으로 Notion 페이지에 접근합니다 — Notion의 "웹에 공유" 기능과 동일한 방식입니다. 이를 위해 데이터베이스 페이지가 웹에 공유(공개)되어야 합니다.

비공개 페이지(웹에 공유되지 않은)의 경우 Notion 통합을 만들어야 합니다:

1단계: 통합 만들기

notion.so/my-integrations로 이동합니다
새 통합을 클릭합니다
이름을 지정합니다 (예: "Noxion")
연결된 워크스페이스를 본인의 워크스페이스로 설정합니다
기능에서 다음을 활성화합니다:
- ✅ 콘텐츠 읽기
- ❌ 콘텐츠 삽입 (불필요)
- ❌ 콘텐츠 업데이트 (불필요)
제출을 클릭합니다
내부 통합 토큰 (secret_xxx...)을 복사합니다

2단계: 데이터베이스에 통합 연결

Noxion이 접근할 각 Notion 데이터베이스를 엽니다
... 메뉴 (오른쪽 상단)를 클릭합니다
연결 추가를 클릭합니다
본인의 통합을 검색하여 선택합니다

3단계: 환경 변수에 추가

# .env
NOTION_TOKEN=secret_xxx...

토큰 보안

통합 토큰을 git에 커밋하지 마세요. create-noxion이 생성하는 .gitignore에 이미 .env가 제외되어 있습니다.

콘텐츠 작성

데이터베이스가 설정되면 새 콘텐츠를 만드는 것은 간단합니다:

Notion에서 데이터베이스를 엽니다
새로 만들기를 클릭하여 새 페이지를 만듭니다
Notion 에디터로 콘텐츠를 작성합니다 — 제목, 코드 블록, 이미지, 임베드, 콜아웃 등
데이터베이스 속성을 입력합니다 (Tags, Category, Description 등)
게시할 준비가 되면 Public 체크박스를 체크합니다

콘텐츠가 사이트에 나타나는 시점:

~1시간 (기본 ISR 재검증 간격)
즉시 온디맨드 재검증을 트리거하면

프론트매터 오버라이드

Noxion은 Notion 페이지 맨 처음에 있는 특별한 코드 블록 (첫 번째 콘텐츠 블록이어야 함)을 읽어 페이지별 메타데이터 오버라이드로 사용합니다.

프론트매터 추가 방법

Notion에서 페이지를 엽니다
페이지 본문 맨 위를 클릭합니다 (텍스트 전)
/code를 입력하고 Enter를 눌러 코드 블록을 삽입합니다
key: value 쌍을 입력합니다

예시:

cleanUrl: /my-custom-slug
title: A Better SEO Title | My Site
description: A hand-written meta description optimized for click-through rates.

지원 키

키	타입	설명
`cleanUrl`	string	URL 슬러그 오버라이드. 예: `/my-post` → 슬러그가 `my-post`가 됨
`slug`	string	`cleanUrl`의 별칭 (앞의 `/` 없이)
`title`	string	`<title>` 태그 오버라이드
`description`	string	`<meta description>` 콘텐츠 오버라이드
`date`	string	발행일 오버라이드 (`YYYY-MM-DD`)
`category`	string	카테고리 오버라이드
`tags`	string	태그 오버라이드 (쉼표 구분: `react, typescript, web`)
`coverImage` / `cover`	string	커버 이미지 URL 오버라이드

그 외의 키는 page.frontmatter에 Record<string, string>으로 보존되어 앱에서 커스텀 용도로 사용할 수 있습니다.

프론트매터 코드 블록은 Notion 페이지에서 보이지만 렌더링된 출력에서는 숨겨집니다.

지원하는 Notion 블록 타입

Noxion은 자체 블록 렌더러(@noxion/notion-renderer)를 사용하여 30개 이상의 Notion 블록 타입을 지원합니다:

블록 타입	렌더링 결과
문단	`<p>` (볼드, 이탤릭, 코드, 컬러, 링크, 멘션 등 리치 텍스트 지원)
제목 1/2/3	`<h1>` / `<h2>` / `<h3>` (앵커 링크 포함)
글머리 기호 목록	`<ul><li>` (중첩 지원)
번호 매기기 목록	`<ol><li>` (중첩 지원)
할 일 목록	체크/미체크 상태의 체크박스 목록
토글	`<details><summary>` (애니메이션 펼침/접기)
인용	`<blockquote>`
콜아웃	이모지/아이콘이 포함된 스타일 콜아웃 상자
코드 블록	Shiki 기반 구문 강조 (38개 언어, 라이트/다크 듀얼 테마)
이미지	`notion.so/image/` 프록시 URL로 최적화
구분선	`<hr>`
테이블	HTML `<table>` (헤더 행 지원)
컬럼 레이아웃	다중 컬럼 flex 레이아웃
임베드	iFrame 임베드
비디오	HTML5 `<video>` 또는 YouTube/Vimeo 임베드
오디오	HTML5 `<audio>` 플레이어
PDF	임베드 PDF 뷰어
파일	파일 메타데이터가 포함된 다운로드 링크
북마크	제목, 설명, 아이콘이 포함된 리치 링크 카드
수식 (블록)	서버 사이드 KaTeX 렌더링 (클라이언트 JS 불필요)
수식 (인라인)	리치 텍스트 내 인라인 KaTeX
멘션	페이지, 사용자, 날짜, 데이터베이스 멘션
동기화 블록	소스 콘텐츠로 인라인 렌더링
목차	페이지 제목에서 자동 생성

인라인 데이터베이스

인라인 데이터베이스(컬렉션 뷰)는 현재 플레이스홀더로 렌더링됩니다. 전체 컬렉션 뷰 지원은 향후 릴리스에서 계획 중입니다.

데이터베이스 만들기​

블로그 데이터베이스 스키마​

필수 속성​

권장 속성​

데이터베이스 예시​

문서 데이터베이스 스키마​

데이터베이스 예시​

포트폴리오 데이터베이스 스키마​

데이터베이스 예시​

스키마 매핑​

페이지 ID 가져오기​

브라우저 URL에서​

공유 메뉴에서​

ID 설정​

비공개 페이지 (선택사항)​

1단계: 통합 만들기​

2단계: 데이터베이스에 통합 연결​

3단계: 환경 변수에 추가​

콘텐츠 작성​

프론트매터 오버라이드​

프론트매터 추가 방법​

지원 키​

지원하는 Notion 블록 타입​

데이터베이스 만들기

블로그 데이터베이스 스키마

필수 속성

권장 속성

데이터베이스 예시

문서 데이터베이스 스키마

데이터베이스 예시

포트폴리오 데이터베이스 스키마

데이터베이스 예시

스키마 매핑

페이지 ID 가져오기

브라우저 URL에서

공유 메뉴에서

ID 설정

비공개 페이지 (선택사항)

1단계: 통합 만들기

2단계: 데이터베이스에 통합 연결

3단계: 환경 변수에 추가

콘텐츠 작성

프론트매터 오버라이드

프론트매터 추가 방법

지원 키

지원하는 Notion 블록 타입