AI 요약 보고서

옵시디안 노트를 Quartz 4를 통해 웹사이트로 변환하는 과정을 단계별로 안내한다. 주요 내용은 다음과 같다. 먼저, Node.js v22 이상과 Git, 코드 에디터, 터미널 환경을 사전 준비하며, git clone 명령으로 Quartz 저장소를 클론 후 npm install로 패키지를 설치한다. 프로젝트 구조는 content/ 폴더(마크다운 파일 저장), quartz.config.ts(사이트 설정), quartz.layout.ts(레이아웃), public/(빌드 결과물)로 구성되어 있으며, 이를 이해하는 것이 중요하다.

옵시디안에서 publish 폴더(8.quartz)를 생성하고, 마크다운 노트들을 복사 또는 이동 후, 심볼릭 링크를 생성하여 Quartz와 연동한다. 이후 index.md를 만들어 홈페이지 내용을 작성하고, quartz.config.ts에서 사이트 제목, 언어, 제외 폴더 등을 커스터마이징한다. 빌드 명령어(node quartz/bootstrap-cli.mjs build --serve)를 실행하면 로컬 서버가 시작되며, 브라우저에서 http://localhost:8080으로 접속하여 결과를 확인한다.

실습 과정에서 자주 발생하는 문제로 YAML frontmatter 형식 오류, 포트 충돌, 외부 접근 문제, 방화벽 차단 등이 있으며, 이를 해결하는 방법도 상세히 설명한다. 마지막으로, 주요 기능(검색, 지식정원 링크, 그래프, 백링크, 다크모드, 반응형, Hot Reload)의 정상 작동 여부를 점검하며, 배포와 커스터마이징, 플러그인 활용 등 향후 확장 방향도 제시한다. 이 문서는 초급-중급 사용자를 대상으로 하며, 실습 완료 후 사이트 운영과 배포에 필요한 핵심 정보를 제공한다.

Quartz 4 설정 실습노트

📌 목표: 옵시디안 노트를 Quartz 4를 사용하여 웹사이트로 변환하기

⏱️ 예상 소요 시간: 30분

💻 난이도: 초급-중급

📋 사전 체크리스트

실습을 시작하기 전에 아래 항목을 확인하세요.

필수 도구

Node.js v22 이상 설치 완료
Git 설치 완료 (선택사항)
코드 에디터 (VSCode, 메모장 등)
터미널 접근 권한 (Windows: PowerShell 또는 CMD)

환경 확인

1. Node.js 버전 확인

node --version

예상 출력: v22.x.x 이상

2. npm 버전 확인

npm --version

예상 출력: 10.x.x 이상

3. Git 확인 (선택)

git --version

1. Quartz 4 설치

1-1. 작업 폴더로 이동

# 예시: Z 드라이브의 SynStudy 폴더로 이동
cd Z:\SynStudy
 
# 또는 본인의 작업 폴더로 이동
cd C:\Users\[사용자명]\Documents

작업 폴더로 이동 완료

💡 TIP: 옵시디안 볼트가 있는 폴더에서 작업하는 것을 추천합니다.

1-2. Quartz 저장소 클론

git clone https://github.com/jackyzha0/quartz.git

예상 출력:

Cloning into 'quartz'...
remote: Enumerating objects: ...

Git clone 완료

⚠️ Git이 없다면? → https://github.com/jackyzha0/quartz 에서 “Code” → “Download ZIP” 클릭 후 압축 해제

1-3. Quartz 폴더로 이동

cd quartz

quartz 폴더로 이동 완료

1-4. 패키지 설치

npm install

예상 소요 시간: 1-2분

예상 출력:

added 200+ packages in 1m

npm install 완료

🔍 확인 방법: node_modules 폴더가 생성되었는지 확인

2. 프로젝트 구조 이해

설치가 완료되면 다음과 같은 폴더 구조가 생성됩니다.

quartz/
├── content/          ← 📝 여기에 마크다운 파일을 넣습니다!
├── quartz/           ← Quartz 코어 파일
├── public/           ← 빌드된 HTML 파일 (자동 생성)
├── quartz.config.ts  ← ⚙️ 설정 파일
├── quartz.layout.ts  ← 레이아웃 설정
└── package.json

중요 파일/폴더

파일/폴더	역할	수정 여부
`content/`	마크다운 파일 저장 위치	✅ 자주 수정
`quartz.config.ts`	사이트 설정 (제목, 테마 등)	✅ 자주 수정
`quartz.layout.ts`	레이아웃 컴포넌트 설정	🔄 필요시
`quartz/`	Quartz 엔진 코드	❌ 건드리지 않음
`public/`	빌드 결과물	❌ 자동 생성

프로젝트 구조 이해 완료

3. 옵시디안 폴더 설정

3-1. Publish용 폴더 생성

옵션 A: 옵시디안에서 생성

옵시디안 열기
볼트에 새 폴더 생성: 8.quartz (또는 원하는 이름)
폴더 생성 완료

옵션 B: 파일 탐색기에서 생성

# 옵시디안 볼트 위치로 이동
cd Z:\SynStudy
 
# 폴더 생성
mkdir 8.quartz

Publish용 폴더 생성 완료 (8.quartz 또는 다른 이름)

📝 내 폴더 이름: ___________________

3-2. 테스트 파일 준비

publish할 마크다운 파일을 8.quartz 폴더로 복사하거나 이동합니다.

방법 1: 기존 노트 복사

옵시디안 또는 파일 탐색기에서 2-3개 파일 복사
8.quartz 폴더에 붙여넣기

방법 2: 새 파일 생성 8.quartz/test.md 파일 생성:

---
title: 테스트 페이지
---
 
# 안녕하세요!
 
이것은 테스트 페이지입니다.
 
## 지식정원 링크 테스트
- 다른 페이지
- 파일명

테스트 파일 2-3개 준비 완료

✅ 확인: 8.quartz 폴더 안에 .md 파일이 있는지 확인

4. 심볼릭 링크 생성

4-1. 경로 확인

먼저 절대 경로를 확인합니다.

옵시디안 폴더 경로 (예시):

Z:\SynStudy\8.quartz

Quartz content 폴더 경로 (예시):

Z:\quartz\content

두 경로 확인 완료

📝 내 경로 메모:

옵시디안 폴더: ___________________
Quartz content: ___________________

4-2. 심볼릭 링크 생성

Linux/Mac/Git Bash:

ln -s ~/n8n/data/shared/syn/8.quartz ~/quartz/content

Windows PowerShell (관리자 권한):

New-Item -ItemType SymbolicLink -Path "Z:\SynStudy\quartz\content\notes" -Target "Z:\SynStudy\8.quartz"

Windows CMD (관리자 권한):

mklink /D "Z:\SynStudy\quartz\content\notes" "Z:\SynStudy\8.quartz"

⚠️ 주의: 경로를 본인의 환경에 맞게 수정하세요!

심볼릭 링크 생성 완료

4-3. 확인

# content 폴더로 이동
cd content
 
# 파일 목록 확인
ls -la notes/

예상 결과: 8.quartz에 있는 마크다운 파일들이 보여야 합니다.

심볼릭 링크 작동 확인 완료

❌ 실패했다면? → 트러블슈팅 섹션 참고

5. 홈페이지 만들기

5-1. index.md 파일 생성

quartz/content/index.md 파일을 생성합니다.

방법 1: 에디터 사용

VSCode 또는 메모장 열기
Z:\SynStudy\quartz\content\index.md 파일 생성

방법 2: 명령어 사용

cd content
touch index.md

index.md 파일 생성 완료

5-2. 홈페이지 내용 작성

아래 템플릿을 복사하여 index.md에 붙여넣고 수정하세요.

---
title: Welcome to My Digital Garden
---
 
# 환영합니다! 🌱
 
이곳은 제 학습 노트를 정리한 디지털 가든입니다.
 
## 📚 주요 내용
 
- [주제 1]
- [주제 2]
- [주제 3]
 
## 🔗 최근 노트
 
- 파일명1
- 파일명2
- 파일명3
 
## 📝 About
 
여기에 자기소개나 사이트 설명을 작성하세요.

💡 커스터마이징 포인트:

title: 사이트 타이틀
주제 1, 2, 3: 본인의 주요 주제로 변경
파일명1, 2, 3: 실제 파일명으로 변경 (.md 제외)
index.md 내용 작성 완료

6. 설정 파일 커스터마이징

6-1. quartz.config.ts 열기

# VSCode로 열기 (VSCode 설치된 경우)
code quartz.config.ts
 
# 또는 메모장으로 열기
notepad quartz.config.ts

6-2. 기본 설정 수정

아래 부분을 찾아서 수정합니다:

const config: QuartzConfig = {
  configuration: {
    pageTitle: "내 디지털 가든",  // ← 사이트 제목
    pageTitleSuffix: "",
    enableSPA: true,
    enablePopovers: true,
    analytics: {
      provider: "plausible",
    },
    locale: "ko-KR",  // ← 한국어로 변경
    baseUrl: "quartz.jzhao.xyz",  // ← 나중에 배포 시 변경
    ignorePatterns: ["private", "templates", ".obsidian"],  // ← 제외할 폴더
    // ...
  }
}

✏️ 수정할 항목:

설정	기본값	추천 값
`pageTitle`	”Quartz 4"	"내 디지털 가든”
`locale`	”en-US"	"ko-KR”
`ignorePatterns`	[…]	제외할 폴더 추가

기본 설정 수정 완료

6-3. WebSocket 포트 변경 (선택사항)

⚠️ 포트 3001이 이미 사용 중인 경우만 진행하세요.

quartz/cli/args.js 파일 열기:

code quartz/cli/args.js
# 또는
notepad c

91번째 줄 찾기:

wsPort: {
  number: true,
  default: 3001,  // ← 이 값을 변경
  describe: "port to use for WebSocket-based hot-reload notifications",
},

수정:

wsPort: {
  number: true,
  default: 3331,  // ← 다른 포트로 변경
  describe: "port to use for WebSocket-based hot-reload notifications",
},

포트 변경 완료 (또는 건너뛰기)

6-4. ignorePatterns 설정

제외하고 싶은 폴더/파일 패턴을 추가합니다.

ignorePatterns: [
  "private",       // private 폴더 제외
  "templates",     // templates 폴더 제외
  ".obsidian",     // 옵시디안 설정 폴더 제외
  "일기",          // 개인 폴더 제외
  "초안",          // 작업 중인 글 제외
  "**/*.draft.md", // .draft.md로 끝나는 파일 제외
],

ignorePatterns 설정 완료

7. 빌드 및 미리보기

7-1. 빌드 명령어 실행

quartz 폴더에서 아래 명령어 실행:

node quartz/bootstrap-cli.mjs build --serve

예상 출력:

 Quartz v4.5.2

Cleaned output directory `public` in 353ms
Found 4 input files from `content` in 50ms
Parsing input files using 1 threads
Parsed 4 Markdown files in 3s
Filtered out 0 files in 48μs
Emitting files
Emitted 22 files to `public` in 2s
Done processing 4 files in 6s
Started a Quartz server listening at http://localhost:8080

빌드 성공

⏱️ 예상 소요 시간: 5-10초

7-2. 빌드 명령어 실행 (백그라운드 실행)

원격접속을 종료해도 (터미널을 닫아도) 실행되려면 다음과같이 nohup을 활용

pm2 start "node quartz/bootstrap-cli.mjs build --serve --port 8081" --name quartz

7-2. 경고 메시지 확인

정상적인 경고 (무시해도 됨):

Warning: content/notes/파일명.md isn't yet tracked by git, dates will be inaccurate

→ Git으로 관리하지 않는 파일은 날짜가 부정확할 수 있다는 경고 (무시 가능)

문제가 있는 경고:

Error: listen EADDRINUSE: address already in use :::8080

→ 8080 포트가 이미 사용 중 (트러블슈팅 참고)

경고 메시지 확인 완료

8. 결과 확인

8-1. 브라우저에서 열기

웹 브라우저를 열고 아래 주소 입력:

http://localhost:8080

브라우저에서 사이트 열기 완료

8-2. 주요 기능 체크리스트

각 기능을 하나씩 테스트하고 체크하세요.

✅ 홈페이지

index.md 내용이 정상적으로 표시됨
제목과 내용이 올바르게 렌더링됨

✅ 검색 기능

상단 검색 바 클릭
키워드 입력 시 결과 표시
검색 결과 클릭 시 페이지 이동

✅ 지식정원 링크

파일명 형식의 링크가 클릭 가능
링크 클릭 시 해당 페이지로 이동
존재하지 않는 링크는 회색으로 표시

✅ 그래프 뷰

우측 상단 그래프 아이콘 클릭
노드 간 연결 관계 표시
노드 클릭 시 페이지 이동

✅ 백링크

페이지 하단에 백링크 섹션 표시
“이 페이지를 참조하는 페이지” 목록 확인

✅ 목차 (TOC)

우측 사이드바에 목차 표시
헤딩(#, , ) 기반 목차 생성
목차 클릭 시 해당 섹션으로 스크롤

✅ 다크모드

다크모드 토글 버튼 확인
라이트/다크 모드 전환 작동

✅ 반응형 디자인

브라우저 창 크기 조절 시 레이아웃 자동 조정
모바일 뷰 확인 (개발자 도구 F12 → 모바일 모드)

8-3. 실시간 수정 테스트 (Hot Reload)

테스트 절차:

브라우저와 옵시디안(또는 에디터)을 나란히 배치
8.quartz 폴더의 마크다운 파일 하나 열기
내용 수정 (예: 텍스트 추가, 제목 변경)
저장 (Ctrl+S)
브라우저 확인 (자동 새로고침 됨)

실시간 수정 반영 확인 완료

💡 TIP: 약 1-2초 후 자동으로 반영됩니다.

8-4 문제 발생시

pm2 stop quartz; pm2 delete quartz

cd /home/tw/quartz/quartz  # bootstrap-cli.mjs 있는 곳

pm2 start "node bootstrap-cli.mjs build --serve --port 8081" --name quartz

🎉 실습 완료!

모든 체크리스트를 완료하셨다면 축하드립니다! 🎊

다음 단계

더 많은 노트 추가하기
테마 커스터마이징
GitHub Pages로 배포 준비
커스텀 도메인 연결 (선택)

📚 트러블슈팅

자주 발생하는 문제와 해결 방법입니다.

❌ Frontmatter YAML 파싱 오류 (중요!)

에러 메시지:

Failed to process markdown `content/index.md`: Cannot create property 'title' on string 'title:값'

원인: YAML frontmatter에서 콜론(:) 뒤에 공백이 없음

잘못된 예시:

---
title:일하는ai의 지식정원
tags:quartz,obsidian
---

올바른 예시:

---
title: 일하는ai의 지식정원
tags:
  - quartz
  - obsidian
---

⚠️ 중요: YAML에서는 콜론(:) 뒤에 반드시 공백 하나가 필요합니다!

빠른 체크리스트:

모든 frontmatter 키 뒤에 콜론과 공백 확인 (예: title: ✅)
여러 값은 배열 형식 사용 (들여쓰기 + -)
따옴표 필요한 경우: 특수문자 포함 시 "값" 형식 사용

❌ “command not found: npx” 또는 “quartz not found”

원인: npx 명령어를 사용할 수 없는 환경

해결 방법:

# npx quartz 대신 아래 명령어 사용
node quartz/bootstrap-cli.mjs build --serve

❌ 포트 충돌

에러 메시지:

Error: listen EADDRINUSE: address already in use :::8080

해결 방법 1: 다른 포트 사용

node quartz/bootstrap-cli.mjs build --serve --port 8081

해결 방법 2: 기존 프로세스 종료

# Windows
netstat -ano | findstr :8080
taskkill /PID [프로세스ID] /F
 
# Mac/Linux
lsof -ti:8080 | xargs kill

❌ 심볼릭 링크 생성 실패 (Windows)

에러 메시지:

A required privilege is not held by the client

해결 방법:

PowerShell을 관리자 권한으로 실행
다시 심볼릭 링크 생성 명령어 실행

대안: 개발자 모드 활성화

Windows 설정 → 업데이트 및 보안 → 개발자용
“개발자 모드” 켜기
PowerShell 재시작 후 다시 시도

❌ 한글 파일명이 깨짐

원인: 인코딩 문제

해결 방법:

파일을 UTF-8 인코딩으로 저장
VSCode: 우측 하단 인코딩 클릭 → “UTF-8 with BOM”으로 저장

❌ 그래프 뷰에 노드가 안 보임

원인: 페이지 간 링크가 없음

해결 방법:

지식정원 링크 파일명 형식으로 페이지 간 연결 생성
최소 2개 이상의 페이지가 서로 링크되어야 그래프에 표시됨

❌ 이미지가 표시되지 않음

원인: 이미지 경로 문제

해결 방법:

이미지를 public/ 폴더 또는 content/ 폴더에 저장
마크다운에서 상대 경로로 참조

!image.png

❌ 수식(LaTeX)이 렌더링되지 않음

확인 사항:

quartz.config.ts에서 Latex 플러그인이 활성화되어 있는지 확인

transformers: [
  // ...
  Plugin.Latex({ renderEngine: "katex" }),  // ← 이 줄 확인
],

사용 예시:

인라인 수식: $E = mc^2$
 
블록 수식:
$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

❌ 외부 네트워크에서 접근 불가 (192.168.x.x로 접근 안됨)

증상: localhost:8080은 접속되지만 192.168.0.21:8080으로 접속이 안됨

원인: 서버가 localhost(127.0.0.1)에만 바인딩되어 있음

해결 방법: handlers.js 파일 수정

quartz/cli/handlers.js 파일 열기
약 456번째 줄 찾기:

server.listen(argv.port)
const wss = new WebSocketServer({ port: argv.wsPort })

다음과 같이 수정:

server.listen(argv.port, '0.0.0.0')
const wss = new WebSocketServer({ port: argv.wsPort, host: '0.0.0.0' })

서버 재시작 후 http://0.0.0.0:8080에서 listening 확인

추가 설정: 리눅스 서버의 경우 방화벽(UFW) 포트 개방 필요

# UFW 상태 확인
sudo ufw status
 
# 포트 허용 (예: 8081 포트)
sudo ufw allow 8081/tcp
 
# 변경사항 확인
sudo ufw status

포트 닫기 (나중에 필요시):

sudo ufw delete allow 8081/tcp

확인 방법:

같은 네트워크의 다른 기기에서 http://[서버IP]:8081 접속 테스트
스마트폰에서 접속해보기

❌ 빌드는 성공했는데 변경사항이 반영 안됨

해결 방법:

브라우저 캐시 삭제 (Ctrl + Shift + R)
빌드 프로세스 중단 후 재시작
public 폴더 삭제 후 다시 빌드

# Ctrl+C로 서버 중단
rm -rf public
node quartz/bootstrap-cli.mjs build --serve

📖 추가 학습 자료

공식 문서

커뮤니티

💾 체크리스트 요약

실습을 완료했는지 최종 확인하세요!

필수 단계

주요 기능 확인

선택 단계

WebSocket 포트 변경 (필요한 경우)
ignorePatterns 설정
테마 색상 커스터마이징
추가 플러그인 설정

📝 실습 노트

자유롭게 메모하세요!

실제 발생한 주요 문제들 (2026-01-05 실습 기록):

Frontmatter YAML 형식 오류 ⭐ 가장 흔한 실수
- title:값 (X) → title: 값 (O)
- 콜론 뒤 공백 필수!
포트 8080 충돌
- 해결: --port 8081 옵션으로 다른 포트 사용
외부 네트워크 접근 불가
- localhost만 접속 가능, 192.168.x.x로 접근 불가
- 해결: handlers.js에서 '0.0.0.0' 바인딩 추가
방화벽 차단
- Linux/Ubuntu에서 UFW로 포트 차단됨
- 해결: sudo ufw allow 8081/tcp

어려웠던 점:

배운 점:

다음에 해보고 싶은 것:

질문/문제점:

🎓 다음 실습 예고

GitHub Pages 배포: Quartz 사이트를 무료로 온라인에 배포하기
커스텀 도메인 연결: yourname.com으로 접속 가능하게 만들기
테마 커스터마이징: CSS 수정으로 나만의 디자인 적용
플러그인 활용: 댓글, 방문자 통계 등 추가 기능 설정

💬 피드백 환영: 이 실습노트에 대한 의견이나 개선 사항이 있다면 알려주세요!

📧 연락처: [aieeiee030303@gmail.com]

⭐ 도움이 되었다면 GitHub 저장소에 Star를 눌러주세요!

마지막 업데이트: 2026-01-05 버전: 1.1 (트러블슈팅 추가: Frontmatter 오류, 외부 네트워크 접근, UFW 방화벽) 작성자: [작성자명]

일하는 ai

탐색기

4_Quartz 4 옵시디안 지식정원

Quartz 4 설정 실습노트

📋 사전 체크리스트

필수 도구

환경 확인

🎯 실습 목차

1. Quartz 4 설치

1-1. 작업 폴더로 이동

1-2. Quartz 저장소 클론

1-3. Quartz 폴더로 이동

1-4. 패키지 설치

2. 프로젝트 구조 이해

중요 파일/폴더

3. 옵시디안 폴더 설정

3-1. Publish용 폴더 생성

3-2. 테스트 파일 준비

4. 심볼릭 링크 생성

4-1. 경로 확인

4-2. 심볼릭 링크 생성

4-3. 확인

5. 홈페이지 만들기

5-1. index.md 파일 생성

5-2. 홈페이지 내용 작성

6. 설정 파일 커스터마이징

6-1. quartz.config.ts 열기

6-2. 기본 설정 수정

6-3. WebSocket 포트 변경 (선택사항)

6-4. ignorePatterns 설정

7. 빌드 및 미리보기

7-1. 빌드 명령어 실행

7-2. 빌드 명령어 실행 (백그라운드 실행)

7-2. 경고 메시지 확인

8. 결과 확인

8-1. 브라우저에서 열기

8-2. 주요 기능 체크리스트

✅ 홈페이지

✅ 검색 기능

✅ 지식정원 링크

✅ 그래프 뷰

✅ 백링크

✅ 목차 (TOC)

✅ 다크모드

✅ 반응형 디자인

8-3. 실시간 수정 테스트 (Hot Reload)

8-4 문제 발생시

🎉 실습 완료!

다음 단계

📚 트러블슈팅

❌ Frontmatter YAML 파싱 오류 (중요!)

❌ “command not found: npx” 또는 “quartz not found”

❌ 포트 충돌

❌ 심볼릭 링크 생성 실패 (Windows)

❌ 한글 파일명이 깨짐

❌ 그래프 뷰에 노드가 안 보임

❌ 이미지가 표시되지 않음

❌ 수식(LaTeX)이 렌더링되지 않음

❌ 외부 네트워크에서 접근 불가 (192.168.x.x로 접근 안됨)

❌ 빌드는 성공했는데 변경사항이 반영 안됨

📖 추가 학습 자료

공식 문서

커뮤니티

관련 개념

💾 체크리스트 요약

필수 단계

주요 기능 확인

선택 단계

📝 실습 노트

🎓 다음 실습 예고

그래프 뷰

목차

백링크