목표
시행착오를 기록할 블로그를 써보고 싶었어요. 선택지가 몇 가지 있었는데요
- velog / Tistory — 편하긴 한데, 데이터가 플랫폼에 묶이고 글을 쓸 때마다 사이트에 들어가서 관리해야 함
GitHub Pages 쓰고, Obsidian에서 글만 쓰면 알아서 블로그에 올라갔으면 좋겠다
- Jekyll — GitHub Pages랑 궁합은 좋은데, Obsidian 문법을 그대로 쓰기 어려움
- Quartz — Obsidian 문법(위키링크, 콜아웃, Mermaid)을 그대로 렌더링해주는 정적 사이트 생성기
노트를 이미 Obsidian으로 쓰고 있었으니까 Quartz를 골랐습니다.
graph LR A[Obsidian 글 작성] --> B[Git Push] B --> C[GitHub Actions] C --> E[GitHub Pages 배포]
블로그 구조
Blog/ ← Quartz 프로젝트
├── content/ ← 이 폴더만 Obsidian vault로 열어서 씀
│ ├── troubleshooting/
│ ├── cs/
│ ├── dev/
│ ├── etc/ㅣ
│ └── attachments/ ← 이미지 붙여넣기 저장 위치
├── quartz.config.yaml
└── .github/workflows/deploy.yml
구조 의도는 content/만 Obsidian vault로 열어서 쓰면 되게 하는거였습니다. 블로그 엔진이랑 글이 한 repo에 있긴 한데, 글 쓸 때는 글만 보여서 편하거든요. 이미지를 붙여넣으면 attachments/로 들어가고, 빌드할 때 같이 포함됩니다.
main에 push하면 github actions가 돌고,
거기서 의존성 설치 -> Quartz로 HTML 빌드 -> artifact 올린 뒤 Pages에 공개하는 식으로 짰어요.
여기까지는 순조로웠습니다.
삽질 1 — SSH Permission
세팅 다 하고 git push 하는 순간 막혔습니다.
git@github.com: Permission denied.
fatal: Could not read from remote repository.키는 분명히 있고, 다른 repo는 잘 되는데 왜…??
원인은 ~/.ssh/config였어요. 개인 계정이랑 회사 계정을 나눠 쓰느라 host alias로 설정해 둔 걸 까먹고 있었더라고요.
Host github.com-personal
HostName github.com
IdentityFile ~/.ssh/personal
User git
Host github.com-work
HostName github.com
IdentityFile ~/.ssh/work
User git위 설정에서는 github.com이라는 호스트에 매핑된 키가 없어요. remote URL이 git@github.com:...이면 어느 키도 선택되지 않아서 인증이 실패합니다. remote를 alias 쪽으로 바꿔서 해결했습니다.
git remote set-url origin git@github.com-personal:won-N-only/blog.git삽질 2 — shallow clone은 push할 수 없다
굳이 history까지 가져오고 싶지 않아서 Quartz repo를 --depth 1로 얕게 clone했더니 push할 때 문제가 됐어요.
git fetch --unshallow upstream로 전체 히스토리를 받아온 뒤에야 push가 가능했습니다. repo history가 좀 지저분해지긴 했는데 어쩔 수 없는 것 같더라고요 ㅎㅎ;
삽질 3 — macOS 파일시스템은 대소문자를 구분하지 않는다
폴더 구조를 Troubleshooting/ → troubleshooting/으로 바꾸는 과정에서 사고가 났어요.
mkdir troubleshooting # 새 폴더 생성
rm -rf Troubleshooting # 옛 폴더 삭제... 인 줄 알았는데macOS 기본 파일시스템은 case-insensitive라서 Troubleshooting이랑 troubleshooting이 같은 폴더예요. 방금 만든 새 폴더가 같이 지워졌습니다…
교훈: macOS에서 대소문자만 다른 rename은 git mv로 해야 해요. folder 대소문자 변경을 처음 해봐서 몰랐네요. windows나 linux 같은데서는 다른가??
삽질 4 — clone한 프로젝트의 잔재
Quartz repo를 그대로 clone했더니 원본 프로젝트 운영용 파일이 다 딸려왔어요. push하자마자 Dependabot이 의존성 업데이트 PR을 만들기 시작하더라고요.
fork도 아닌데 원본이랑 엮이는 게 싫어서 정리했습니다.
.github/dependabot.yml— 삭제.github/FUNDING.yml, issue/PR 템플릿,CODE_OF_CONDUCT.md— 삭제- 원본 workflow들 — 삭제하고 배포용 하나만 새로 작성
upstreamremote — 제거 (업데이트 받고 싶어지면 다시 추가하면 됨)
혹시 저작권 문제가 있을까 봐 찾아봤는데, Quartz는 MIT 라이선스라 LICENSE.txt만 남기면 수정해도 되더라구요. 다행이었습니다.
삽질 5 — IDE 터미널에선 되는데 Obsidian에선 안 된다
Obsidian에서 명령 팔레트로 push했는데, 삽질 1에서 고친 SSH가 또 막혔어요. 이상한 건 같은 컴퓨터의 IDE 터미널에서는 멀쩡히 된다는 점…
원인은 ~/.zshrc였어요.
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/won-N-only.zshrc에 위처럼 설정해뒀었는데 위 처럼 설정하면 터미널을 열 때마다 새 ssh-agent를 띄우고, 그 프로세스에만 SSH_AUTH_SOCK 환경변수를 심어요. IDE 터미널은 .zshrc를 읽으니까 agent가 있고 인증이 됩니다.
반면 Obsidian은 터미널으로 동작하는게 아닌 GUI 앱이라 .zshrc를 아예 안 읽어요. agent 자체가 없으니 키를 못 씁니다.
macOS는 사실 로그인 세션 전체에 쓰는 시스템 전역 SSH agent를 이미 제공하더라구요. .zshrc에서 셸별 agent 스폰을 걷어내고, 키체인에 등록하는 쪽으로 바꿨습니다.
# .zshrc — 이 줄만 남김
ssh-add --apple-use-keychain ~/.ssh/won-N-only &>/dev/null
ssh-add --apple-use-keychain ~/.ssh/susimdal &>/dev/null교훈: 멀티 계정 SSH 세팅에서 eval "$(ssh-agent -s)"처럼 셸마다 agent를 새로 띄우는 방식은 별로 좋은 방식이 아닌 것 같아요. macOS라면 시스템 agent + 키체인 조합이 더 낫더라고요. IDE에서만 쓰다가 GUI 앱을 같이 쓰면서 발견한 문제였습니다.
삽질 6 — 404: There isn’t a GitHub Pages site here
배포 workflow가 돌았는데 deploy 단계에서 실패했어요.
Error: Failed to create deployment (status: 404)
Ensure GitHub Pages has been enabledrepo Settings → Pages → Source를 “GitHub Actions”로 선택하는 걸 빼먹었습니다. 추가해뒀고 바로 배포되는 것 확인했습니당
삽질 7 — 한글 URL이랑 최신순 정렬
글 올리고 나서 주소창에 한글 슬러그가 길게 뜨더라고요. 그게 좀 싫었습니다.
Quartz는 URL을 파일 이름로 만들거든요. uri에 제목이 뜨는건 바라지 않아서 파일명을 001.md, 002.md처럼 숫자로 바꿨습니다.
그다음에 탐색기 정렬이 또 걸렸어요. date 기준으로 최신이 위로 오게 하려면 Quartz가 contentIndex에서 date를 지워 버려서 배포 시점에 플러그인 소스를 패치하는 .sh가 더 필요하더라고요. 배포마다 다시 심어야 하고 예쁘지 않아보여서 포기했습니다.
숫자 파일명으로 바꾼 김에, 탐색기는 파일명 숫자 내림차순으로 정렬하게 했어요. 새 글은 003, 004… 숫자만 올리면 최신이 위로 갑니다. date 패치보다 단순해서 이게 낫더라고요.
결과
지금 이 글이 그 결과물이에요. Obsidian에서 쓰고, git push 한 번이면 몇 분 뒤에 사이트에 올라갑니다. 굿~