📚 개발자 서고

2) Obsidian, Quartz 연동하기

8 min read

해당 글부턴 실제 프로젝트를 생성하며 진행합니다. Obsidian, Node.js, Git 을 사용해본적이 있다는 전제하에 글을 작성했습니다.

Obsidian Vault 생성

이미 사용중인 Vault가 있다면 생략합니다.

Vault 생성

옵시디언_생성

위 새 보관함 생성의 생성 버튼을 눌러 Vault를 새로 생성해주세요.

옵시디언_생성2 예제 진행을 위해 sample 이라는 이름으로 /Users/lim(홈 경로)에 생성하겠습니다.

그러면 현재 Vault의 위치는 /Users/lim/sample입니다.

그리고 가벼운 글 하나를 작성해보겠습니다.

  • 해당 마크다운의 제목엔 index를 작성해주세요
    • 해당 파일이 블로그의 대문이 됩니다.
  • 실제 글 제목은 title속성에 작성해주세요.

문서_생성 이제 해당 Vault를 기준으로 Quartz 프로젝트를 생성해 볼까요?

Quartz 프로젝트 생성 및 프리뷰

개발환경 세팅

모든 예제는 Apple Silicon 기반 MacBook(sequoia 15.3)에서 진행한 예제입니다.

  • git
  • Node.js v20 이상
  • npm v9.3.1 이상

예제

# git 다운로드 및 설치
brew install git
# 위 과정후에 아래 명령어 입력 후 버전이 나온다면 문제 없습니다.
git -v
 
# nvm 다운로드 및 설치(2025/02/16 기준)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
# Node.js 다운로드 및 설치
nvm install 22
 
# 위 과정후에 아래 버전이 20.0.0 이상으로 나오면 문제 없습니다.
node -v 
nvm current 
# 위 과정후에 아래 버전이 9.3.1 이상으로 나오면 문제 없습니다.
npm -v

Quartz 프로젝트 클론

공식 홈페이지에서는 아래와 같이 프로젝트를 시작할 것을 추천하고있습니다.

# 원하는 경로로 가서 프로젝트 클론
git clone https://github.com/jackyzha0/quartz.git
 
# 별도로 clone 경로를 입력 안할시에는 quartz라는 이름으로 프로젝트가 생성됩니다.
cd quartz
 
# 해당 프로젝트 경로로 들어가 프로젝트의 node_modules를 설치합니다.
npm i
 
# 그리고 아래 명령어를 사용하여 quartz 프로젝트를 세팅합니다.
npx quartz create
 
 
# quartz는 마크다운 파일들을 참조하여 그것들을 포함한 정적 사이트를 빌드합니다.
# content
┌   Quartz v4.4.0
│
◆  Choose how to initialize the content in `~/quartz/content`
│  ○ Empty Quartz
│  ○ Copy an existing folder
│  ● Symlink an existing folder # 우리는 외부에 있는 Vault를 대상으로 할 것이기에 해당 폴더에 대한 심볼릭 링크를 생성해주는 옵션을 선택합니다.
└
 
# 이제 대상이 되는 Vault 경로를 입력해줍시다.
◇  Enter the full path to existing content folder
│  /Users/lim/sample # 해당 부분에 위에서 생성한 Vault 또는 사용하고 있는 Vault 경로를 작성해주세요.
 
# 백링크를 어떻게 처리할지에 대한 질문인데 추후에 토막글로 관련 내용 작성 예정입니다.
# 보통의 경우 default 값인 shortest path를 선택합니다.
◆  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
 
# 세팅이 끝났습니다!
└  You are all set! Not sure what to do next? Try:
  • Customizing Quartz a bit more by editing `quartz.config.ts`
  • Running `npx quartz build --serve` to preview your Quartz locally
  • Hosting your Quartz online (see: https://quartz.jzhao.xyz/hosting)

이러면 quartz.config.ts 에 대한 세팅은 끝났습니다.

한번 빌드 후 구동하여 프리뷰 페이지를 볼까요?

# 아래 명령어를 입력하세요!
❯ npx quartz build --serve # --serve 옵션을 추가하면 빌드 후 프리뷰 서버까지 자동으로 실행됩니다.
 
# 그러면 아래와 같은 내용이 출력됩니다.
 Quartz v4.4.0 # 사용 중인 Quartz 버전에 따라 숫자가 다를 수 있습니다.
 
# 빌드 결과물(정적 파일)은 프로젝트의 `public` 폴더에 저장됩니다.
Cleaned output directory `public` in 5ms # 빌드 전 기존 public 폴더의 내용을 비웁니다.
Found 5 input files from `content` in 5ms # Vault에서 5개의 파일을 찾았습니다.
Parsed 5 Markdown files in 156ms # 찾은 5개의 마크다운 파일을 HTML로 변환합니다.
Filtered out 0 files in 23μs # 필터링할 파일을 찾는 과정인데, 현재는 따로 필터링된 파일이 없습니다.
Emitted 28 files to `public` in 95ms # 총 28개의 파일이 `public` 폴더에 생성되었습니다. (HTML, CSS, 이미지 등 포함)
Done processing 5 files in 263ms # 5개의 콘텐츠 파일 변환 작업이 완료되었습니다.
 
# 아래 메시지가 나오면 서버가 실행된 상태이며, http://localhost:8080 에 접속할 수 있습니다.
Started a Quartz server listening at http://localhost:8080
hint: exit with ctrl+c # 프리뷰 서버를 종료하려면 ctrl+c를 누르세요.

결과물 확인

이제 http://localhost:8080 으로 접근해봅시다!

빌드_결과물 깔끔하게 잘 나왔네요.

개선점

하지만 아직 개인의 블로그라고 할 수 없는 부분이 있습니다.

1. 블로그 이름

Quartz 4.0 이라고 기본 이름으로 세팅되어있습니다.

2. 레이아웃

메뉴를 좌, 우가 아닌 상, 하에 두고싶을 수도 있습니다.

3. 테마

저는 이런 색상을 원하지 않아요!

4. 배포의 불편함

글을 작성할 때마다 매번 제가 이런 과정을 거쳐야 하나요?

1,2,3번 부분들은 quartz.config.ts, quartz.layout.ts 파일을 통해 수정이 가능합니다.

4번은 추후 Git, Github 와 Github Action을 사용해 자동화 해보겠습니다!

그래프 뷰