Summary
- 심볼릭 링크는 Quartz 프로젝트의
content폴더가 실제로는 옵시디언 Vault를 가리키도록 만드는 주소표다.- 링크를 걸기 전에 기존
content폴더와 Git 캐시를 정리해야 한다..gitignore에서public제외 설정을 풀어야 한다.ln -s실행 시 경로는 큰따옴표로 감싸고 원본 경로 끝에 슬래시를 붙이지 않는다.
실습 환경
이 시리즈는 macOS 기준이다. 이 글은 Quartz v5 기준이다.
들어가며
Quartz 프로젝트의 content 폴더를 Vault의 블로그 폴더에 연결하면 파일을 복사하지 않고 글을 작성할 수 있다. 이 글에서는 연결 전 Git 정리부터 연결 확인까지 진행한다.
심볼릭 링크란
심볼릭 링크는 실제 파일 대신 파일이나 폴더의 위치를 가리키는 주소표다. Quartz 프로젝트의 content 폴더를 Vault의 00-Blog/content에 연결하면 옵시디언에서 수정한 내용이 Quartz에 즉시 반영된다.
- 원본 폴더:
/Users/haejun/Documents/obsidian/00-Blog/content - 블로그 폴더:
/Users/haejun/Developer/haejunhyun.com/content
Git 연동과 초기화
레포 준비와 캐시 제거
심볼릭 링크를 걸기 전에 Git 쪽 정리를 먼저 끝내야 한다. content를 GitHub에 올린 적이 있다면 Git 캐시에서도 기존 추적 정보를 제거해야 한다.
- GitHub에서 Quartz 레포를 템플릿으로 가져와 저장소를 만든다.
- 로컬
Developer폴더에 저장소를 클론한다. - 저장소 폴더에서 의존성을 설치한다.
- 기존
content폴더를 제거한다. - Git 캐시에서도
content를 제거한다.
레포 생성
저장소 클론과 의존성 설치
cd ~/Developer
git clone https://github.com/haden-hyun/<blog-repo-name>
cd <blog-repo-name>
npm install
npx quartz plugin install
content가 없다는 오류
pathspec 'content' did not match any files가 뜬다면 Git이 기억하는 과거가 없다는 뜻일 수 있다. 이 경우 다음 단계로 넘어간다.
기존 content 제거와 Git 캐시 정리
rm -rf content
git rm -rf --cached content.gitignore 수정
public 폴더가 GitHub에 올라갈 수 있도록 .gitignore를 수정한다. 프로젝트 루트에서 public 또는 public/을 무시하는 줄을 삭제하거나 주석 처리한다.
링크 생성
ln -s 명령어 자체는 단순하지만 경로 오타가 구조 전체를 망가뜨릴 수 있다.
경로 표기 주의
경로 양끝은 큰따옴표로 감싼다. 원본 경로 끝에는
/를 붙이지 않는다.
cd ~/Developer/haejunhyun.com
ln -s "/Users/haejun/Documents/obsidian/00-Blog/content" content성공 여부 확인
심볼릭 링크가 올바른 대상을 가리키는지 확인한다.
ls -F content/- 성공: Vault의 마크다운 파일과 폴더 목록이 출력된다.
- 실패:
No such file or directory가 뜨거나 아무것도 나오지 않으면 경로를 확인하고rm content후 링크를 다시 만든다.
GitHub에서의 정상적인 모습
심볼릭 링크로 연동한 content를 GitHub에 업로드하면 GitHub에는 파일 목록이 아니라 링크가 가리키는 경로 텍스트가 보인다.
git add content
git commit
git push
파일 목록 대신 경로 텍스트가 보이는 경우
GitHub에서
content를 열었을 때/Users/haejun/Documents/...같은 경로 텍스트 한 줄만 보여도 정상이다. 실제 배포는 로컬에서 빌드한public폴더가 담당한다.
빌드는 로컬에서만 가능하다는 성질이 로컬 빌드 전략의 전제다.
마치며
Git 캐시를 비우고 .gitignore에서 public을 풀고 심볼릭 링크를 연결하면 Quartz와 Vault의 통로가 완성된다. 다음 글에서는 Cloudflare Pages 설정을 다룬다.
Reference