시스템 · 파일 관리

sbarex QLMarkdown

sbarex QLMarkdown은 macOS의 Quick Look에서 Markdown 문서를 서식이 적용된 상태로 미리 보는 확장 앱입니다.

어떤 사용자에게 필요한가

Finder에서 README, 업무 메모, 개발 문서를 자주 확인하는 Mac 사용자에게 적합하다. 문서를 작성하는 편집기보다는 파일 내용을 빠르게 읽기 위한 보조 도구다. 설정 창에 시험용 편집 영역이 있지만 공식 문서는 독립적인 Markdown 편집기나 뷰어 용도로 설계한 앱이 아니라고 설명한다.

실무에서는 프로젝트 인수인계 폴더의 README를 미리 보며 설치 설명과 작업 목록을 확인하고, 수정할 문서만 편집기로 여는 방식으로 활용할 수 있다.

문서 표현과 지원 범위

표, 코드, 로컬 이미지, 수식, Mermaid 도식을 한 문서에서 확인할 수 있다. 필요한 확장은 설정에서 활성화한다. .rmd와 .mdx도 미리 보지만 R 코드를 실행하거나 JSX를 렌더링하지 않는다.

수식·도식용 라이브러리는 웹 연결 또는 HTML에 포함하는 방식을 선택할 수 있다. 웹 연결 방식은 인터넷이 필요하며, 포함 방식은 출력 파일 크기가 커진다. GitHub와 코드 강조 엔진이 달라 색상과 언어 토큰 표현이 같지는 않을 수 있다.

설치와 첫 미리 보기

공식 GitHub Releases에서 배포 앱을 받는다. README에는 Homebrew 명령 brew install --cask qlmarkdown도 안내되어 있다. 설치 후 앱을 한 번 실행해야 시스템이 확장을 발견한다.

앱의 안내 버튼으로 Quick Look 설정을 열어 활성화 여부를 확인한다. 테마와 확장 설정을 저장한 뒤 Finder에서 .md 파일을 선택하고 스페이스바로 미리 보기를 연다. 코드 강조를 확인할 때는 코드 블록에 언어 이름을 지정한다.

비용과 기능상 제약

공식 배포 파일을 별도 결제 없이 받을 수 있는 공개 소스 프로젝트이며, 저장소에는 GPL-3.0 라이선스와 자발적 후원 링크가 있다. 확인한 자료에는 유료 등급이나 체험 기간, 무료판 사용량 제한이 제시되어 있지 않다.

단축어 확장은 실험적 기능이다. CLI는 앱 및 Quick Look과 설정을 공유하지 않으므로 자동 변환 작업에는 옵션을 따로 지정해야 한다. 1.5.0 변경 기록에는 기존 설정 초기화와 CLI 인자 변경도 명시되어 있어 오래된 사용 예제를 그대로 적용하기 전에 확인할 필요가 있다.

미리 보기가 안 될 때 확인 순서

먼저 앱을 한 번 실행했는지, 시스템 설정의 일반 → 로그인 항목 및 확장 프로그램 → Quick Look에서 활성화했는지 확인한다. 확장이 켜져 있는데도 .md가 표시되지 않으면 다른 Quick Look 확장과의 충돌을 점검한다. 공식 FAQ는 다른 확장을 잠시 끄고 하나씩 다시 켜는 순서를 안내한다.

이미지가 빠지면 로컬 이미지 확장과 파일 경로를 확인한다. 수식이나 도식만 빠지면 해당 확장 및 라이브러리 연결 방식을 점검한다. 최신 1.5.7은 각주와 위첨자 확장의 충돌, 표 셀 안의 아래첨자·위첨자·강조·수식 렌더링을 수정한 버전이다.

다른 도구와 선택 기준, 유지보수 검토

파일을 고쳐 가며 결과를 확인하려면 Markdown 편집과 나란히 미리 보기를 지원하는 Visual Studio Code가 선택지가 된다. Finder에서 읽는 작업이 중심이면 QLMarkdown, 여러 파일의 HTML 변환이 목적이면 포함된 CLI를 검토할 수 있다.

2026-10-07 확인 시 공식 최신 배포는 1.5.7이다. 지원 종료 제품이라는 공식 근거는 확인되지 않았다. 과거 Homebrew 중단 예정 경고가 있었지만 개발자는 이후 1.5.0의 코드 서명과 공증을 안내했다. 과거 경고만으로 현재 지원 종료를 단정하면 안 되며, Homebrew의 현재 배포 상태는 별도 확인이 필요하다.