Modeleaf - Keyboard-first PDF Reader for macOS

TL;DR

• 마우스 없이 PDF를 읽으려고 만든 macOS 전용 읽기 전용 뷰어
• j/k 스크롤, f 링크 힌트, : 커맨드 팔레트에 네이티브 탭과 tmux식 분할 지원
• 키맵과 읽기 동작은 ~/.config/modeleaf/config.toml 하나로 조정

---

글은 (내가 거의 쓰지는 않지만 ㅎ) 대부분 마크다운으로 쓴다
그래서 hwpx, docx 없이 마크다운으로 통일하고, 깔끔하게 공유할 도구로 pdf만 있으면 충분하다고 생각한다

하지만 pdf의 유일한 단점은 읽을 때 마우스에 손이 많이 간다는 점…?

최근에 회사에서 여러 개의 pdf를 읽을 일이 많았는데, 그때마다 마우스에 손이 가면서 업무 흐름이 끊기는 느낌이 있었다
그리고 크롬 브라우저에서 vimium을 사용하는데도 pdf에서는 키가 안 먹어서 결국 마우스로 손이 갔다

그래서 최근 다양한 도구를 찾아봤는데 각각 모두 아쉬운 점이 있었다

• pdf TUI: 당연히 키보드로 조작이 가능하다는 장점이 있지만 pdf 자체는 앱처럼 따로 띄워서 보는 것이 더 업무에 편할 것 같았다
• Sioyek, Sumatra 등: 단축키 감성은 좋았지만 너무 부가 기능이 많거나 크로스 플랫폼이 아니거나 단축키가 너무 많아서 vim과 느낌이 달라 뇌에 부하가 걸리는 느낌이었다

바이브 코딩의 장점은 이제 이런 것도 내 취향대로 만들 수 있다는 점!
최근 유용하게 활용하는 gajae-code를 사용해서 내 스타일의 pdf reader를 만들어보기로 했다

그래서 만든 게 Modeleaf라는 macOS 네이티브 PDF 뷰어다

---

1. 세 가지 포인트

• 읽기 전용
  • pdf에 필기를 하는 사람도 있지만 나는 오직 읽는 용도로 쓰기 때문에 주석, 편집 등 관련된 기능은 모두 뺐다
• 키보드 우선
  • 가장 중요한 요소로 기본 키는 모두 vim과 보편적인 TUI의 binding을 적용했다
  • 이 과정에서 Sioyek, SumatraPDF를 참고했으며 TUI 느낌은 마크다운 TUI Leaf에서 가져왔다
  • 링크를 마우스 없이 누르는 게 중요해서 vimium 같은 link hint 기능도 추가했다
  • tmux처럼 pane 기능을 넣긴 했으나 생각해보니 활용도가 얼마나 될까 싶어서 우선 2x2까지만 가능하게 구현했다
• 설정 가능
  • 일반적인 CLI, TUI처럼 ~/.config에서 대부분의 명령과 읽기 동작을 TOML 파일 하나로 설정 가능하도록 만들었다

---

2. 설치

설치는 Homebrew tap으로 간단하게 하면 되고, 애플 인증은 받지 않아서 (비싸던데…) 아래 설명되어 있듯이 초기에 설정에서 허용을 눌러줘야 한다.

brew tap DS-argus/tap
brew trust DS-argus/tap
brew install --cask modeleaf

macOS 14 (Sonoma) 이상이 필요하다. 업데이트는 아래처럼 한다.

brew upgrade --cask modeleaf

첫 실행: ad-hoc 서명 상태

• 현재 빌드는 ad-hoc 서명이고 Apple notarize를 받지 않았다
• 처음 실행하면 차단되므로 시스템 설정 → 개인정보 보호 및 보안 → 확인 없이 열기에서 허용해야 한다

---

3. 기본 키

동작	키
스크롤 / 큰 스크롤	h j k l / d u
이전 / 다음 페이지	p / n
처음 / 마지막 페이지	gg / G
페이지 이동	g, 숫자, Enter
뒤로 / 앞으로	Ctrl+o / Ctrl+i
목차 / 이동 / 점프	t / J K / 숫자
검색 / 다음 / 이전 결과	/ / Enter / Shift-Enter
링크 힌트 / 인디케이터 설정	f / I
너비 맞춤 / 페이지 맞춤	w / F
확대·축소 / 회전	= - / [ ]
열기 / 닫기 / 인쇄 / 종료	⌘o / ⌘w / ⌘p / ⌘q
이전 / 다음 탭	P / N
분할 / 포커스 이동	Ctrl-b | Ctrl-b - / Ctrl-h/j/k/l
테마 / 팔레트 / 도움말	T / : / ?

자주 쓰는 기능은 이렇다

• f 링크 힌트: 화면에 보이는 링크마다 라벨을 띄우고, 라벨을 입력하면 그 링크로 점프한다. 각주 번호나 상호 참조를 따라갈 때 쓴다
• 링크 힌트 indicator: 논문 같은 걸 읽으면 점프했을 때 어디로 갔는지 잘 안 보일 때가 있어서 짧은 시간 그 부근에 마크가 생기게 했다
• Ctrl+o / Ctrl+i: 점프하기 전 위치로 돌아오고 다시 앞으로 간다. vim의 점프 리스트와 같은 감각이다
• t 목차: PDF에 임베드된 outline을 읽어 띄운다. J/K로 항목을 옮기고 숫자로 바로 점프한다
• Ctrl-b 분할: prefix가 tmux와 같다. |로 좌우, -로 상하 분할하고 Ctrl-h/j/k/l로 포커스를 옮긴다. 같은 문서의 다른 페이지를 나란히 보거나 서로 다른 문서를 붙여 볼 때 쓴다
• : 커맨드 팔레트: 키를 외우지 않아도 이름으로 명령을 찾아 실행하고, 설정 파일 쓰기·리로드·초기화도 여기서 한다
• T 테마 설정: 기본 테마 7개를 넣어놨다

---

앱을 만들고 배포한 건 처음이라 재밌었고 일단 처음 생각했던 수준까지는 맘에 들게 나온 것 같아 만족스럽다

현재는 Windows용 modeleaf 작업을 메인으로 하고 있으며 기능은 생각날 때마다 붙일 계획이다