Quartz 4는 Obsidian의 Markdown 파일을 그대로 사용할 수 있는 정적 사이트 생성기로, 설치부터 GitHub 연동, Cloudflare Pages 배포, 커스텀 도메인 연결까지 완전 무료로 나만의 블로그를 만들 수 있습니다. 이번 가이드에서는 처음 접하는 분들도 따라할 수 있도록 전 과정을 단계별로 설명합니다.

Quartz 4란 무엇인가

Quartz는 Markdown 파일을 빠르고 아름다운 웹사이트로 변환해주는 정적 사이트 생성기입니다. 원래 Obsidian 사용자들이 자신의 노트를 웹에 공개하기 위해 많이 사용하지만, 일반 블로그나 개인 위키, 포트폴리오 사이트로도 훌륭하게 활용할 수 있습니다.

Quartz 4는 이전 버전과 달리 TypeScript 기반으로 완전히 재작성되었으며, 빠른 빌드 속도와 강력한 커스터마이징 기능을 제공합니다. 특히 아래와 같은 특징 덕분에 기술 블로그나 디지털 가든을 운영하려는 분들에게 인기가 높습니다.

완전 무료: 호스팅 비용 없이 Cloudflare Pages에 배포 가능
Obsidian 호환: Obsidian의 [[내부 링크]] 문법을 그대로 지원
그래프 뷰: 글들 사이의 연결 관계를 시각적으로 표현
전문 검색: 사이트 내 전체 텍스트 검색 기능 내장
다크 모드: 라이트/다크 모드 자동 전환 지원
빠른 로딩: 정적 파일 기반이라 서버 응답 속도가 매우 빠름

사전 준비

Quartz 4를 설치하기 전에 아래 두 가지 도구가 컴퓨터에 설치되어 있어야 합니다.

Node.js 설치

Quartz 4는 Node.js 위에서 동작합니다. Node.js 공식 사이트에서 LTS(Long Term Support) 버전을 내려받아 설치하시면 됩니다. LTS 버전은 안정 버전을 의미하며 많은 사람들이 사용하는 버전이라고 생각하시면 됩니다. 버전은 v20 이상을 권장합니다.

Node.js 공식사이트

설치가 완료되면 터미널(macOS/Linux) 또는 PowerShell(Windows)을 열고 아래 명령어로 설치 여부를 확인합니다.

node -v
npm -v

npm은 따로 설치하는 것이 아니고 node를 설치하면 같이 설치됩니다.

v24.x.x 형태의 버전 정보와 npm 버전이 출력되면 정상적으로 설치된 것입니다. (npm은 node보다는 낮은 버전의 숫자가 나옵니다)

Git 설치

Git은 코드 버전 관리 도구로, GitHub에 코드를 올리기 위해 필요합니다.

macOS: 터미널에서 git --version을 입력하면 자동으로 설치를 안내합니다. 또는 Homebrew로 설치합니다.

brew install git

Windows: Git 공식 사이트(git-scm.com)에서 설치 파일을 내려받아 실행합니다. 설치 옵션은 기본값으로 진행하면 됩니다.

Linux:

sudo apt install git

플랫폼에 맞는 Git을 설치하신 후 아래 명령어로 Git에 이름과 이메일을 등록합니다. 이 정보는 커밋을 할 때 기록에 표시됩니다.

git config --global user.name "이름"
git config --global user.email "이메일@example.com"

Quartz 4 설치

사전 준비가 끝났다면 이제 Quartz를 설치합니다. Quartz는 GitHub에서 직접 클론하는 방식으로 설치합니다.

git clone https://github.com/jackyzha0/quartz.git
cd quartz
npm i
npx quartz create

npx quartz create 명령어를 실행하면 아래와 같은 질문이 나타납니다.

? Choose how to initialize the content in your Quartz
> Empty Quartz
  Copy an existing folder

처음 시작하는 경우 Empty Quartz를 선택합니다. 기존에 작성한 Obsidian 볼트가 있다면 Copy an existing folder를 선택하고 폴더 경로를 지정하면 기존 노트들을 그대로 가져올 수 있습니다.

다음 질문에서는 링크를 어떻게 해석할지를 선택하는 옵션입니다.

? Choose how Quartz should resolve links in your content. This should match Obsidian's link format. You can
change this later in `quartz.config.ts`.
> Treat links as shortest path ((default))
  Treat links as absolute path
  Treat links as relative paths

첫번째 default 옵션을 선택합니다. 각 옵션의 설명은 다음과 같습니다.

Treat links as shortest path (기본) : Obsidian 스타일에 최적화 되며, 자동으로 짧은 경로를 찾습니다. 만약 Obsidian을 이용해서 글을 작성한다면 이 옵션이 가장 적합합니다.
Treat links as absolute path : 절대 경로를 사용할때 사용되는 옵션입니다. 큰 프로젝트라면 이 옵션이 좋습니다.
Treat links as relative paths : 상대경로 스타일로 사용됩니다. Hugo나 다른 블로그에서 글을 가져오는 경우라면 이 경우일 가능성이 높습니다.

설치가 완료되면 아래와 같은 디렉토리 구조가 생성됩니다.

quartz/
├── content/         ← 블로그 글을 작성하는 곳
├── quartz/          ← Quartz 내부 소스 코드
├── quartz.config.ts ← 사이트 전체 설정 파일
├── quartz.layout.ts ← 레이아웃 설정 파일
└── package.json

아마도 설치한 버전과 상황에 따라 더 많은 디렉토리와 파일이 생성될 수도 있습니다.

content: 이 폴더에 Markdown 파일을 넣으면 블로그 글이 됩니다.
quartz.config.ts: 사이트 이름, 언어, 플러그인 등 전체 설정을 관리합니다.
quartz.layout.ts: 헤더, 사이드바, 푸터 등 레이아웃을 설정합니다.

quartz.config.ts 기본 설정

quartz.config.ts 파일을 에디터로 열면 사이트의 모든 설정을 관리할 수 있습니다. 우선 파일을 열어보면 기본적인 설정값들이 보이는데 대부분 그대로 사용합니다.

기본 정보 설정

파일 상단에서 사이트 기본 정보를 설정합니다.

const config: QuartzConfig = {
  configuration: {
    pageTitle: "하마지식창고",           // 브라우저 탭과 헤더에 표시되는 제목
    pageTitleSuffix: "",
    enableSPA: true,
    enablePopovers: true,
    analytics: {
      provider: "plausible",         // 방문자 분석 도구 (없으면 null)
    },
    locale: "ko-KR",                 // 한국어 설정
    baseUrl: "blog.hamadocs.com",    // 실제 도메인 (배포 후 변경)
    ignorePatterns: ["private", "templates", ".obsidian"],
    defaultDateType: "created",
    theme: {
      fontOrigin: "googleFonts",
      cdnCaching: true,
      typography: {
        header: "Schibsted Grotesk",
        body: "Source Sans Pro",
        code: "IBM Plex Mono",
      },
      colors: {
        lightMode: {
          light: "#faf8f8",
          lightgray: "#e5e5e5",
          gray: "#b8b8b8",
          darkgray: "#4e4e4e",
          dark: "#2b2b2b",
          secondary: "#284b63",
          tertiary: "#84a98c",
          highlight: "rgba(143, 159, 169, 0.15)",
          textHighlight: "#fff23688",
        },
        darkMode: {
          light: "#161618",
          lightgray: "#393639",
          gray: "#646464",
          darkgray: "#d4d4d4",
          dark: "#ebebec",
          secondary: "#7b97aa",
          tertiary: "#84a98c",
          highlight: "rgba(143, 159, 169, 0.15)",
          textHighlight: "#b3aa0288",
        },
      },
    },
  },

locale: "ko-KR" 설정을 추가하면 날짜 형식 등이 한국어로 표시됩니다. baseUrl은 나중에 실제 도메인을 연결한 뒤 변경합니다.

플러그인 설정

Quartz의 기능은 플러그인으로 제어됩니다. quartz.config.ts의 plugins 섹션에서 활성화할 기능들을 선택할 수 있습니다. 기본적으로 대부분의 유용한 플러그인이 이미 활성화되어 있으므로 처음에는 기본 설정을 그대로 사용하는 것을 권장합니다.

첫 번째 글 작성

Quartz에서 글을 작성하는 방법은 매우 간단합니다. content 폴더 안에 Markdown 파일을 생성하면 됩니다.

Front Matter 작성

Markdown 파일의 맨 위에 아래와 같은 Front Matter를 작성합니다. Front Matter는 글의 메타 정보를 담는 영역입니다.

---
title: 첫 번째 글
date: 2026-04-22
tags:
  - 블로그
  - 시작
description: 첫 번째 글입니다.
draft: false
---
 
여기부터 본문을 작성합니다.

title: 글 제목입니다.
date: 작성 날짜입니다.
tags: 글의 태그를 지정합니다. 태그별 모아보기 페이지가 자동으로 생성됩니다.
description: 검색 결과나 미리보기에 표시되는 글 요약입니다.
draft: true로 설정하면 배포 시 글이 공개되지 않습니다.

내부 링크 사용

Quartz의 큰 장점 중 하나는 Obsidian의 내부 링크 문법을 지원한다는 점입니다. 다른 글로 링크를 걸 때 파일 전체 경로 대신 파일 이름만으로 간편하게 연결할 수 있습니다.

이 글은 [[두 번째 글]]과 연결되어 있습니다.

이렇게 내부 링크로 연결된 글들은 그래프 뷰에서 시각적으로 연결 관계가 표시됩니다.

로컬에서 미리보기

글 작성 후 실제로 어떻게 보이는지 로컬에서 확인할 수 있습니다.

npx quartz build --serve

명령어를 실행하면 http://localhost:8080 주소로 브라우저에서 사이트를 확인할 수 있습니다. 파일을 수정하면 브라우저가 자동으로 새로고침됩니다. 글을 추가하거나 수정하면서 실시간으로 결과를 확인하고 만족스러우면 다음 단계로 넘어갑니다.

GitHub 레포지터리 생성 및 연결

로컬에서 사이트가 정상적으로 확인되었다면 이제 GitHub에 코드를 올릴 차례입니다. GitHub에 올라간 코드는 Cloudflare Pages와 연동되어 자동으로 배포됩니다.

GitHub 레포지터리 생성

GitHub에 로그인한 뒤 오른쪽 상단의 + 버튼을 클릭하고 New repository를 선택합니다.
Repository name에 원하는 이름을 입력합니다. 예: my-blog
Public 또는 Private 중 선택합니다. Cloudflare Pages는 두 경우 모두 연동 가능합니다.
README, .gitignore, license 추가 체크를 모두 해제한 뒤 Create repository를 클릭합니다.

기존 Git 설정 제거 및 새 레포지터리 연결

Quartz를 클론한 경우 원본 Quartz 레포지터리를 가리키는 remote 설정이 남아 있습니다. 이를 제거하고 본인의 레포지터리로 변경해야 합니다.

# 기존 origin 제거
git remote remove origin
 
# 내 레포지터리로 변경
git remote add origin https://github.com/yourusername/my-blog.git
 
# 첫 커밋 및 푸시
git add .
git commit -m "Initial commit"
git branch -M main
git push -u origin main

yourusername과 my-blog는 본인의 GitHub 사용자 이름과 레포지터리 이름으로 변경합니다.

.gitignore 확인

Quartz 클론 시 .gitignore 파일이 이미 포함되어 있습니다. 기본적으로 node_modules/와 빌드 결과물인 public/이 제외 목록에 포함되어 있어 별도로 수정할 필요가 없습니다. 혹시 빠져 있다면 아래 내용이 포함되어 있는지 확인합니다.

node_modules/
public/
.quartz-cache/

이후 글 업데이트 방법

글을 작성하거나 수정한 뒤에는 아래 명령어로 GitHub에 올리면 됩니다. 이후에는 이 세 줄이 블로그 업데이트의 전부입니다.

git add .
git commit -m "새 글 추가"
git push

Cloudflare Pages 배포

GitHub에 코드가 올라갔다면 이제 Cloudflare Pages를 이용해 무료로 배포할 수 있습니다. Cloudflare Pages는 GitHub 레포지터리와 연동하여 코드가 push될 때마다 자동으로 빌드하고 전 세계 CDN에 배포해주는 서비스입니다.

Cloudflare 계정 및 Pages 진입

Cloudflare 홈페이지(cloudflare.com)에서 무료 계정을 생성하거나 로그인합니다.
왼쪽 메뉴에서 Compute 메뉴를 선택하고 Workers & Pages를 클릭합니다.
Create application 버튼을 클릭한 뒤 하단에서 Pages? Get started를 선택합니다.
Import an existing Git repository의 Get started 버튼을 클릭합니다.

GitHub 연동

Connect GitHub를 클릭하면 GitHub 인증 화면이 나타납니다.
깃허브 계정을 선택한 후 Cloudflare가 접근할 레포지터리를 선택합니다.
좀 전에 깃허브에서 생성한 레포지터리를 선택하면 됩니다.

빌드 설정

레포지터리를 선택하면 빌드 설정 화면이 나타납니다. Quartz에 맞게 아래와 같이 설정합니다.

Project name: 원하는 프로젝트 이름 입력 (배포 URL인 프로젝트명.pages.dev에 사용됨)
Production branch: main
Framework preset: None 선택 (Quartz는 목록에 없으므로 직접 입력)
Build command: npx quartz build
Build output directory: public

환경 변수 설정

Node.js 버전을 명시하지 않으면 Cloudflare Pages가 구버전을 사용할 수 있습니다. Environment variables 섹션에서 아래 항목을 추가합니다.

Variable name: NODE_VERSION
Value: 20

설정을 마친 뒤 Save and Deploy 버튼을 클릭합니다. 첫 빌드는 2~3분 정도 소요됩니다. 빌드가 완료되면 프로젝트명.pages.dev 형태의 URL로 블로그에 접속할 수 있습니다.

자동 배포 확인

이후 GitHub의 main 브랜치에 코드를 push할 때마다 Cloudflare Pages가 자동으로 빌드하고 배포합니다. 새 글을 쓰고 git push만 하면 수 분 내에 블로그에 반영됩니다. 배포 진행 상황은 Cloudflare Pages 대시보드의 Deployments 탭에서 실시간으로 확인할 수 있습니다.

커스텀 도메인 연결

Cloudflare Pages에서 제공하는 기본 도메인(*.pages.dev)도 충분히 사용할 수 있지만, 직접 구매한 도메인을 연결하면 훨씬 신뢰감 있는 블로그를 운영할 수 있습니다.

도메인 준비

도메인이 없다면 Cloudflare Registrar, Namecheap, GoDaddy 등 도메인 등록 업체에서 구매할 수 있습니다. Cloudflare에서 직접 도메인을 구매하면 추가 설정 없이 Pages와 바로 연동되어 가장 편리합니다. 도메인 가격은 종류에 따라 다르지만 일반적인 .com 도메인은 연간 약 10~15달러 수준입니다.

Cloudflare Pages에 커스텀 도메인 추가

Cloudflare Pages 대시보드에서 본인의 프로젝트를 클릭합니다.
Custom domains 탭을 클릭합니다.
Set up a custom domain 버튼을 클릭합니다.
연결할 도메인 주소를 입력합니다. 예: myblog.com 또는 서브도메인인 경우 blog.myblog.com

도메인 DNS 설정

도메인이 Cloudflare에 등록된 경우와 외부 업체에 등록된 경우의 설정 방법이 다릅니다.

Cloudflare에 등록된 도메인인 경우:

Cloudflare가 자동으로 CNAME 레코드를 추가해줍니다. 확인 버튼을 클릭하면 바로 적용됩니다.

외부 업체에 등록된 도메인인 경우:

도메인 등록 업체의 DNS 관리 페이지에서 아래 레코드를 추가합니다.

루트 도메인 사용 시 (예: myblog.com):
- Type: CNAME
- Name: @ 또는 도메인 이름
- Value: 프로젝트명.pages.dev
서브도메인 사용 시 (예: blog.myblog.com):
- Type: CNAME
- Name: blog
- Value: 프로젝트명.pages.dev

일부 DNS 제공업체는 루트 도메인에 CNAME 레코드를 허용하지 않습니다. 이 경우 Cloudflare로 네임서버를 이전하면 CNAME Flattening 기능 덕분에 루트 도메인에도 CNAME을 설정할 수 있습니다.

Cloudflare로 네임서버 이전 (권장)

외부에서 구매한 도메인이라도 Cloudflare로 네임서버를 이전하면 CDN 가속, DDoS 방어, 무료 SSL 인증서 등 Cloudflare의 다양한 기능을 모두 활용할 수 있습니다.

Cloudflare 대시보드 왼쪽 메뉴에서 Websites를 클릭합니다.
Add a site를 클릭하고 도메인 주소를 입력합니다.
무료 플랜을 선택합니다.
Cloudflare가 기존 DNS 레코드를 자동으로 감지하여 표시합니다. 확인 후 Continue를 클릭합니다.
Cloudflare에서 제공하는 네임서버 주소 두 개를 복사합니다. 예: aria.ns.cloudflare.com, bob.ns.cloudflare.com
도메인 등록 업체 관리 페이지에서 네임서버를 Cloudflare가 제공한 주소로 변경합니다.
네임서버 변경은 전파되는 데 최대 48시간이 소요될 수 있습니다. 보통은 1~2시간 내에 적용됩니다.

네임서버 이전이 완료되면 Cloudflare Pages의 Custom domains 설정에서 도메인을 추가할 때 DNS 레코드가 자동으로 생성됩니다.

SSL 인증서 및 baseUrl 업데이트

Cloudflare Pages는 커스텀 도메인에 자동으로 무료 SSL 인증서를 발급합니다. 도메인 연결 후 https://로 접속되는지 확인합니다. SSL 인증서 발급에는 수 분에서 최대 24시간이 소요될 수 있습니다.

도메인 연결이 확인되면 quartz.config.ts의 baseUrl을 실제 도메인으로 업데이트합니다.

baseUrl: "myblog.com",

변경 후 GitHub에 push하면 Cloudflare Pages가 자동으로 재빌드 및 재배포합니다.

Quartz 주요 기능 활용

Quartz 4는 블로그 운영에 유용한 기능들을 기본으로 제공합니다. 자주 활용되는 기능들을 소개합니다.

그래프 뷰

Quartz의 가장 독특한 기능 중 하나입니다. 글들 사이의 [[내부 링크]] 연결 관계를 인터랙티브한 그래프로 시각화해줍니다. 독자가 관련 글을 탐색하는 데 도움이 되며, 지식 네트워크를 구성하는 느낌을 줍니다. 별도 설정 없이 내부 링크를 사용하는 것만으로 자동으로 그래프가 생성됩니다.

폴더 구조로 카테고리 관리

content 폴더 안에 하위 폴더를 만들면 자동으로 카테고리가 생성됩니다.

content/
├── index.md          ← 홈 페이지
├── posts/
│   ├── 글1.md
│   └── 글2.md
└── projects/
    └── 프로젝트1.md

각 폴더에 index.md 파일을 만들어 폴더 소개 페이지를 추가할 수도 있습니다.

태그 시스템

Front Matter에 tags를 추가하면 태그별 모아보기 페이지가 자동으로 생성됩니다. /tags/ 경로로 접속하면 전체 태그 목록을 확인할 수 있습니다.

홈 페이지 설정

content/index.md 파일이 블로그의 홈 페이지가 됩니다. 이 파일에 자기소개나 블로그 안내 글을 작성합니다.

---
title: 안녕하세요
---
 
블로그에 오신 것을 환영합니다. 여기에 소개 글을 작성합니다.

사이드바 커스터마이징

quartz.layout.ts 파일에서 사이드바에 표시할 컴포넌트를 조정할 수 있습니다. 최근 글 목록, 태그 클라우드, 그래프 뷰 등을 원하는 위치에 배치할 수 있습니다.

글 업데이트 워크플로

Quartz 블로그를 운영하면서 새 글을 발행하는 기본적인 흐름입니다.

content 폴더 안에 새 Markdown 파일을 생성합니다.
Front Matter에 제목, 날짜, 태그를 입력하고 본문을 작성합니다.
npx quartz build --serve 명령어로 로컬에서 미리보기를 확인합니다.
git add . → git commit -m "새 글 추가" → git push 명령어로 GitHub에 올립니다.
Cloudflare Pages가 자동으로 빌드하고 배포합니다. 수 분 내에 블로그에 반영됩니다.

마치며

Quartz 4, GitHub, Cloudflare Pages의 조합은 완전 무료로 고품질의 블로그나 지식 창고를 운영할 수 있는 최고의 방법 중 하나입니다. 특히 Obsidian을 이미 사용하고 있다면 별도의 변환 작업 없이 기존 노트를 그대로 웹에 공개할 수 있어 활용 범위가 매우 넓습니다.

처음 설정하는 데 약간의 시간이 걸리지만, 한 번 구축해 두면 이후에는 Markdown 파일 작성과 git push 두 가지 작업만으로 블로그를 운영할 수 있습니다. 서버 관리나 플러그인 업데이트 걱정 없이 오로지 글쓰기에만 집중할 수 있다는 것이 정적 사이트 생성기 방식의 가장 큰 장점입니다.

하마창고

블로그

Quartz 4로 블로그 만들기 완벽 가이드