Glow 사용법: 터미널에서 Markdown 문서를 읽기 좋게

Glow는 Markdown 문서를 브라우저로 열지 않고 터미널에서 읽기 좋게 렌더링하는 오픈소스 도구입니다. 저장소를 살펴보거나 원격 서버에서 운영 안내서를 읽을 때, 원문 기호를 그대로 훑는 대신 제목·목록·코드의 구조를 빠르게 구별하는 데 적합합니다. 공식 GitHub 저장소 charmbracelet/glow는 2026년 10월 27일 조회 기준 스타 27,825개이며 보관 상태가 아닙니다. 스타는 관심도의 지표일 뿐 품질이나 안전성의 보증은 아닙니다.

문서 읽기에 집중

Glow의 핵심은 문서를 만드는 편집기가 아니라 읽는 인터페이스입니다. 단일 Markdown 파일을 렌더링하거나 현재 폴더와 하위 경로의 문서를 탐색하는 TUI를 열 수 있습니다. Git 저장소 안에서는 저장소 문서를 찾아 읽는 흐름도 지원합니다. README와 배포 안내서를 자주 오가는 개발자에게 잘 맞지만, 브라우저의 모든 확장 문법이나 웹페이지 동작까지 동일하게 재현하는 도구로 기대해서는 안 됩니다.

설치 전에 확인

아래는 공식 README의 현재 사용법을 기준으로 정리한 예제이며 직접 설치·실행한 검증은 아닙니다. 당일 조회한 최신 GitHub 릴리스는 v3.0.0으로 2026년 8월 11일 공개됐고, 저장소 최근 push는 10월 5일로 확인했습니다. 새 릴리스가 매일 나오는 프로젝트라는 뜻은 아니지만 현재 보관 처리되지 않았고 최근 활동이 확인됩니다. 실제 설치 패키지의 버전은 패키지 관리자별로 다를 수 있습니다.

macOS 또는 Linux에 Homebrew가 이미 준비돼 있다면 다음 경로가 간단합니다. Windows는 공식 README에 WinGet·Scoop·Chocolatey 경로가 따로 있으므로 macOS 명령을 그대로 실행하지 마세요. 이 글에서는 시스템 저장소를 추가하는 Linux 관리자 설치 대신 기존 Homebrew 경로만 다룹니다.

brew install glow
glow --version
glow --help

실행 파일을 찾지 못하면 Homebrew 실행 경로와 설치 결과부터 확인합니다. Go 설치 경로도 있지만 현재 README의 설치 모듈과 빌드 전제조건이 버전별로 바뀔 수 있으므로, 패키지 설치와 소스 빌드 설명을 섞지 않는 편이 좋습니다. 운영 서버에 바로 추가하기보다 개인 개발 환경이나 시험 컨테이너에서 먼저 표시 결과를 살펴보세요.

최소 실행 예제

다음 명령은 현재 폴더에 새 시험 디렉터리를 만들고 간단한 운영 문서를 저장합니다. 같은 이름의 문서가 이미 있다면 다른 디렉터리 이름을 사용해 기존 파일을 덮어쓰지 마세요. 예제의 문서는 실제 운영 명령을 실행하지 않는 텍스트입니다.

mkdir glow-demo
cd glow-demo
cat > runbook.md <<'EOF'
# 배포 전 확인

- 테스트 결과를 확인한다.
- 변경 사항을 검토한다.

## 복구 기준

오류율이 기준을 넘으면 담당자에게 보고한다.
EOF
glow runbook.md

제목과 목록의 계층이 터미널에서 구별돼 보이면 기본 렌더링이 된 것입니다. 이 명령은 문서에 적힌 배포나 복구를 실행하지 않습니다. 원문과 출력이 다르게 보이는 것은 렌더링의 목적이며, 파일이 실제로 변경됐다는 의미도 아닙니다. 원문을 수정하려면 별도 편집기를 사용해야 합니다.

실무 문서 탐색

프로젝트의 docs 폴더로 이동해 인자 없이 glow를 실행하면 TUI에서 Markdown 파일을 찾아볼 수 있습니다. 키 안내는 물음표 키로 확인합니다. 모든 터미널과 버전에서 단축키가 같다고 가정하지 말고 현재 도움말을 기준으로 사용하세요.

glow
glow -p -w 80 runbook.md
printf '# 점검 결과

- 준비 완료
' | glow -

두 번째 명령은 출력 폭을 80열로 제한하고 페이저를 사용합니다. 긴 운영 문서를 작은 터미널에서 읽을 때 줄바꿈을 제어하는 예제입니다. 세 번째는 표준입력의 Markdown을 렌더링합니다. 로그를 Markdown으로 조합하는 스크립트와 연결할 수 있지만, 원본 로그의 내용을 자동으로 정확하게 요약하거나 검증해 주는 기능은 아닙니다.

색상과 설정

-s dark 또는 -s light는 배경색에 맞는 스타일을 고릅니다. 기본적으로는 터미널 배경을 감지해 선택하므로 대비가 약하면 명시적으로 지정해 비교하세요. -w는 줄바꿈 폭, -p는 페이저 사용을 제어합니다. PAGER를 지정하지 않으면 공식 문서상 ANSI를 이해하는 less -r가 기본입니다. 호스트의 페이저 설치 여부와 터미널 색상 지원에 따라 결과가 달라질 수 있습니다.

반복 옵션은 glow config로 설정 파일을 열어 관리할 수 있습니다. 플랫폼별 기본 경로는 glow --help에서 확인합니다. 기존 설정을 백업한 뒤 width·style 같은 필요한 키만 바꾸세요. README의 설정 예제에는 숨김·무시 파일 표시를 제어하는 all과 TUI의 행 번호 설정도 있습니다. 편의를 위해 숨김 파일을 무조건 노출하기보다 문서 범위를 좁히는 편이 안전합니다.

권한과 네트워크

로컬 파일 렌더링은 파일을 읽을 수 있는 운영체제 권한이 필요합니다. 권한 오류를 해결하려고 무조건 관리자 권한으로 올리면 문서 탐색 범위가 불필요하게 넓어집니다. 공개 README나 HTTP Markdown을 URL로 읽는 기능도 있으므로 URL 입력은 네트워크 요청을 발생시킨다는 점을 구분하세요. 신뢰하지 않는 링크를 문서에서 발견했다고 그대로 가져올 필요는 없습니다.

Glow 자체는 MIT 라이선스로 배포됩니다. 사내 재배포 시에는 라이선스와 저작권 고지 조건을 확인해야 합니다. 구독료가 필요한 호스팅 서비스는 아니지만 설치·업데이트·보안 검토의 운영 비용은 남습니다. 비밀 문서를 터미널에 표시하면 화면 공유나 터미널 기록에 내용이 남을 수 있으므로 로컬 도구라는 이유만으로 유출 위험이 사라지지는 않습니다.

오류와 복구

색상이 흐리면 밝은·어두운 스타일을 바꿔 보고 터미널 배경과 대비를 점검합니다. 긴 문서가 한꺼번에 흘러가면 -p를 사용하되 페이저가 없는 환경에서는 먼저 단일 파일의 짧은 출력으로 시험합니다. 문서가 탐색 목록에 없으면 현재 경로와 파일 확장자, 숨김·무시 상태를 확인하고 glow runbook.md처럼 명시적인 파일 경로로 좁혀 진단합니다.

URL 문서가 열리지 않는 문제는 로컬 렌더링과 나눠 봐야 합니다. 네트워크, 인증, 응답 형식 문제일 수 있으며 개인 토큰을 URL에 붙여 명령 기록에 남기지 마세요. 브라우저 전용 요소가 다르게 보일 때도 먼저 원본 Markdown이 무엇인지 확인하고 ‘렌더링 성공’을 ‘웹사이트와 완전히 같은 표시’로 오해하지 않는 것이 좋습니다.

제거와 되돌리기

이 가이드의 시험은 원본 프로젝트를 수정하지 않습니다. 만든 runbook.md와 glow-demo 폴더만 확인 후 정리하면 됩니다. 설정을 바꿨다면 백업과 비교해 변경한 키만 원래 값으로 돌리고, Homebrew 설치를 제거하려면 brew uninstall glow를 사용합니다. 문서 원본과 개인 설정을 함께 지우는 일괄 삭제 명령은 필요하지 않습니다.

Glow의 장점은 터미널에서 문서를 읽는 작은 불편을 줄인다는 데 있습니다. 설치부터 모든 문서 흐름을 바꾸기보다 자주 보는 운영 안내서 한 개로 폭·스타일·페이저를 정하고, 원문을 편집하는 도구와 읽는 도구의 역할을 구분하면 부담 없이 도입할 수 있습니다.

출처