개인
Nuartz - Obsidian → Next.js 오픈소스 라이브러리
Obsidian 볼트를 Next.js 웹사이트로 퍼블리싱하는 headless 라이브러리
- 기간
- 2026.01 ~ 진행 중2026.01 첫 커밋, 2026.03 npm 첫 배포 이후 지속 개발
- 역할
- 1인 개발 / npm 패키지 배포
- 팀
- 개인 오픈소스 프로젝트
- 상태
- 진행 중

배경
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, 문서화의 중요성
기술 스택
- 코어
- TypeScriptunified (remark/rehype)
- 기능 라이브러리
- remark-mathrehype-katexrehype-pretty-codePagefindD3.js
- 참고 웹앱
- Next.js 16Tailwind CSS v4shadcn/uinext-themes
- 빌드
- Buntsc
- 배포
- npm registryVercelGitHub Pages
관련 글
- Nuartz: Obsidian을 Next.js 블로그로2026-03-01
- Nuartz: Quartz를 Next.js로 다시 만들기까지의 여정2026-03-01
- Quartz 플러그인 해부: 무엇을 재사용할 수 있나2026-03-01
- Nuartz 첫 배포: 구현 내용과 Vercel에서 만난 것들2026-03-06
- Nuartz를 headless 라이브러리로: 설계 방향과 레포 생태계2026-03-06
- Nuartz npm 배포: 버전 관리와 자동화2026-03-06
- FlexSearch에서 Pagefind로: nuartz 검색 엔진 마이그레이션2026-03-26