Syshin0116 홈
프로젝트 목록

개인

Nuartz - Obsidian → Next.js 오픈소스 라이브러리

Obsidian 볼트를 Next.js 웹사이트로 퍼블리싱하는 headless 라이브러리

기간
2026.01 ~ 진행 중2026.01 첫 커밋, 2026.03 npm 첫 배포 이후 지속 개발
역할
1인 개발 / npm 패키지 배포
팀
개인 오픈소스 프로젝트
상태
진행 중
Nuartz 데모 사이트 스크린샷

배경

Obsidian 볼트를 Next.js 웹사이트로 서빙하기 위한 headless 데이터 레이어 라이브러리. Quartz의 한계(커스텀 UI 불가, AI 연동 어려움)를 해결하기 위해 직접 개발. npm 패키지로 배포하여 누구나 자신의 Next.js 앱에 Obsidian 기능을 통합 가능.

한 일

주요 기능

Obsidian 호환 마크다운 렌더링

  • 위키링크 ([[note]], [[note|alias]]) 파싱 및 라우팅
  • 양방향 백링크 인덱스 자동 생성
  • 콜아웃 블록 (> [!note], > [!warning] 등)
  • 하이라이트 (==text==), 코멘트 (%%text%%), 화살표 (->)
  • LaTeX 수식 렌더링 ($...$, $$...$$)

콘텐츠 유틸리티

  • 재귀적 마크다운 파일 탐색 및 드래프트 필터링
  • 폴더 기반 파일 트리 생성 (사이드바용)
  • Pagefind 기반 정적 전문 검색 인덱스
  • 그래프 뷰 데이터 생성 (노트-태그 관계)

headless 아키텍처

  • UI 없이 데이터 레이어만 제공, 어떤 디자인이든 적용 가능
  • nuartz.config.ts로 설정 (title, baseUrl, nav 등)
  • 정적 생성(SSG) 기반 페이지 빌드
  • GitHub Pages 정적 배포 지원

참고 웹앱 (apps/web)

  • shadcn/ui + Tailwind v4 기반 모던 UI
  • 다크모드, 반응형 레이아웃
  • 그래프뷰 (D3.js), 목차, 검색 (cmdk)
  • OG 이미지 자동 생성, RSS 피드

문제와 해결

Quartz 플러그인 시스템 재해석
Quartz의 Preact 기반 정적 사이트 생성기를 Next.js의 unified 파이프라인으로 재설계. remark/rehype 플러그인으로 위키링크, 콜아웃 등을 직접 구현
CJK 검색 최적화
초기 검색 엔진이던 FlexSearch의 기본 토크나이저가 한국어를 제대로 분리하지 못하는 문제. CJK 전용 토크나이저 설정으로 대응했고, 이후 검색은 Pagefind로 전환
CSS 변수 호환성
Tailwind v4의 oklch 색상 체계와 D3.js SVG 렌더링 간 호환 문제. hsl() 래퍼 제거하고 CSS 변수 직접 참조로 해결

결과

  • npm 패키지 배포 (nuartz@0.5.0)
  • Quartz 핵심 기능을 Next.js 생태계로 포팅
  • Vercel + GitHub Pages 양쪽 배포 지원
  • 개인 블로그로 실사용 중 (syshin0116.dev)

배운 점

  • unified 생태계 깊이 이해: remark/rehype 플러그인 직접 작성
  • npm 패키지 배포 및 버전 관리 실무 경험
  • 모노레포 구조 설계: packages/nuartz (라이브러리) + apps/web (참고 앱)
  • headless 라이브러리 설계 철학: UI와 데이터 레이어의 분리
  • 오픈소스 프로젝트 운영: README, CHANGELOG, 문서화의 중요성

기술 스택

코어
TypeScript
unified (remark/rehype)
기능 라이브러리
remark-math
rehype-katex
rehype-pretty-code
Pagefind
D3.js
참고 웹앱
Next.js 16
Tailwind CSS v4
shadcn/ui
next-themes
빌드
Bun
tsc
배포
npm registry
Vercel
GitHub Pages

관련 글