md-preview: 사이드 창에서 보는 Claude Code Markdown 미리보기

md-preview는 Hamza Zafar(hamzafer)가 만든 커뮤니티 모드로, 그의 claude-code-mods 컬렉션에 속해 있습니다. 이 모드는 Claude Code Markdown 미리보기를 제공합니다. Claude가 .md, .mdx 또는 .markdown 파일을 쓰거나 편집하면 README.md changed · /md to preview라는 토스트가 뜨고, /md를 실행하면 채팅 옆에 창이 열려 GitHub가 보여 주는 방식대로 렌더링된 파일을 보여 줍니다.

창에는 Prev, Next, Before, Render, Text, Browser, Close 버튼이 있고 각각 단축키(p, n, b, r, t, o, q)가 있습니다. n과 p 키로 이번 세션에서 변경된 Markdown 파일을 차례로 넘겨 볼 수 있습니다. b는 턴의 첫 편집 이전 상태의 파일을 현재 텍스트 옆에 보여 주며, 마지막 편집에서 바뀐 블록에는 초록색 막대가 표시됩니다. /md compare <a> <b>는 두 파일을 나란히 놓고, o 또는 /md open은 같은 페이지를 사용자의 브라우저에서 엽니다.

페이지를 그리는 방식은 환경에 따라 다릅니다. 이미지 터미널(Ghostty, iTerm2, WezTerm 또는 kitty, tmux를 거치지 않을 때)에 Chrome이나 Chromium이 설치되어 있으면 페이지를 PNG로 그려 창에 표시합니다. 그렇지 않으면 제목, 목록, 표, 코드 블록을 터미널 색으로 꾸민 텍스트 보기를 보여 줍니다. 매니페스트에는 최소 Claude Code 버전이 명시되어 있지 않습니다.

녹화 영상에서는 작은 데모 프로젝트에서 모드를 불러온 채 Claude Code를 시작하고 /md README.md를 실행합니다. 명령은 키 안내(n/p: next/previous · b: before | after · o: browser · r: render again · t: page/text · q: close)로 응답하고, 프롬프트 위에 테두리가 있는 창이 열립니다. 첫 줄에는 버튼이, 둘째 줄에는 README.md 1/1이 표시되고, 그 아래 텍스트 보기로 프로젝트의 README가 나타납니다. 제목 demo-app과 "A tiny demo app. Run it with npm start."라는 줄이 보이며, 코드 부분은 색으로 표시됩니다. 데모 터미널은 이미지를 표시할 수 없으므로 렌더링된 페이지 대신 텍스트 보기가 나옵니다.

설치 블록의 방법 중 아무것이나 사용하십시오. 모두 작성자 자신의 마켓플레이스에서 바로 설치합니다. 설치 후 /reload-plugins를 실행하거나 새 세션을 시작한 다음 /md를 사용하십시오.

모드는 함수 훅 모듈 하나(hooks/register.tsx)와 작은 Markdown 파서(hooks/md.ts), HTML 페이지 빌더(hooks/page.ts)로 이루어져 있습니다. tool.call 훅은 Markdown 경로에 대한 Write, Edit 또는 MultiEdit 호출 전에 파일을 읽고, 호출이 실행되도록 둔 뒤 결과를 그대로 반환합니다. hooks/register.tsx의 GitHub 렌더러는 다음과 같습니다.

const repo = await repoOf($, dir)
if (!repo) return null // not in a GitHub repo: the Markdown stays on this machine
const r = await $.process
  .run(['gh', 'api', '-X', 'POST', '/markdown', '--input', '-'], { stdin: JSON.stringify({ text: md, mode: 'markdown', context: repo }), timeoutMs: GH_TIMEOUT_MS })
  .catch(() => null)

repoOf는 git remote -v에서 GitHub 원격 저장소를 찾습니다. gh가 실패하면 GitHub 렌더링을 1분간 멈추고 내장 렌더러를 사용합니다. HTML은 $TMPDIR/md-preview/에 기록되고, 짧은 sh 스크립트를 통해 헤드리스 Chrome으로 한 번에 하나씩 그려지며, 그린 결과는 내용 기준으로 캐시됩니다. Claude가 편집한 파일은 턴이 끝나면 백그라운드에서 그려지므로, /md를 열면 대개 이미 그려진 페이지가 나옵니다.

/config에는 옵션이 없습니다. 모든 것은 명령과 창의 키로 합니다. /md는 최근 파일을, /md <path>는 임의의 Markdown 파일을 열고, /md compare <a> <b>는 두 파일을 비교하며, /md open은 브라우저를 엽니다. 다른 명령이 /md라는 이름을 쓰고 있으면 모드는 대신 /mdview를 등록합니다. Chrome 경로 목록(CHROMES), 보관하는 파일 수(MAX_FILES), 캐시 크기(CACHE_SIZE) 같은 한도를 바꾸려면 register.tsx 맨 위의 상수를 수정하십시오.

저희는 실행하기 전에 플러그인이 실행할 수 있는 모든 파일을 읽었습니다. plugin.json, hooks/hooks.json, hooks/register.tsx, hooks/md.ts, hooks/page.ts, 타입 선언, 테스트입니다. package.json, 설치 스크립트, 바이너리, 번들된 코드는 없으며, 숨겨진 문자나 폭이 0인 문자도 발견되지 않았습니다.

• 네트워크: 직접 요청은 없습니다. GitHub 원격 저장소가 있고 gh에 로그인되어 있으면, 별도의 동의 절차 없이 Markdown 텍스트가 gh api를 통해 GitHub의 /markdown API로 전송됩니다(register.tsx:592-594). 약 390 KB를 넘는 파일은 로컬에서 렌더링됩니다. 렌더링된 페이지는 모든 호스트의 이미지를 허용하는 Content-Security-Policy(page.ts:97)로 헤드리스 Chrome에서 불러오므로, Markdown 파일 안의 원격 이미지는 페이지를 그릴 때 가져옵니다. Markdown 안의 스크립트는 실행될 수 없습니다.
• 프로세스: git ls-files와 git remote -v(register.tsx:386, 607), gh api(593), 헤드리스 Chrome을 시작하고 자신이 시작한 Chrome만 종료하는 고정 스크립트를 실행하는 sh -c(49-67, 675), 브라우저 버튼용 open 또는 xdg-open(788)입니다.
• 파일 쓰기: $TMPDIR/md-preview/(페이지 HTML, PNG 조각, 일회용 Chrome 프로필)에만 씁니다. ~/.claude, 설정, 셸 파일, LaunchAgents, git 훅 아래에는 아무것도 쓰지 않습니다.
• 파일 읽기: Claude가 편집하는 Markdown 파일, 사용자가 지정한 파일, 그리고 턴의 첫 셸 명령 전에 git ls-files로 얻은 저장소의 Markdown 파일 최대 200개입니다.
• 환경 변수: HOME, TMPDIR, TMUX, TERM_PROGRAM, TERM입니다. 어디로도 전송되지 않습니다.
• 데몬, 텔레메트리, 프롬프트 주입: 없습니다. 프롬프트나 도구 결과에 텍스트를 추가하지 않습니다.
• 게이팅: tool.call 훅은 관찰자입니다. 호출을 기다렸다가 결과를 그대로 반환합니다. validate는 이를 .catch가 없는 게이팅 훅으로 표시합니다. 턴의 첫 셸 호출은 Markdown 스냅샷을 기다리며, 이 스냅샷은 파일을 읽기만 합니다.
• 외부 요구 사항: 렌더링된 보기를 위한 Chrome, Chromium, Edge 또는 Brave, 이미지 지원 터미널, 그리고 선택적으로 gh입니다. 모두 선택 사항이며, 텍스트 보기가 대체 수단입니다.
• 라이선스: MIT이며, 저장소 루트에 LICENSE 파일이 있습니다.

claude plugin validate는 오류나 경고를 보고하지 않았고, 작성자의 테스트 26개가 Claude Code 2.1.291에서 모두 통과했습니다.

macOS에서 Claude Code 2.1.291로 확인했습니다(validate, 테스트, 녹화). 창이 예상과 다르면 다음을 확인하십시오.

• /md를 알 수 없다고 나오면 /plugin에 md-preview가 로드되어 있는지 확인하거나 /mdview를 시도하십시오.
• 페이지 대신 텍스트가 보이면 터미널이 이미지를 표시할 수 없거나, tmux 안에 있거나, Chrome을 찾지 못한 것입니다. 문제를 해결한 뒤 r을 누르거나, t를 눌러 보기를 전환하십시오.
• "Chrome could not draw the page"가 나오면 r을 눌러 다시 시도하십시오. 모드는 스스로 재시도하지 않습니다.
• 파일을 변경해도 토스트가 뜨지 않으면, Markdown 경로만 추적되며 셸로 쓴 내용은 git 저장소에서만 감지된다는 점을 확인하십시오.
• 창에 GitHub 대신 built-in이 표시되면 파일이 GitHub 저장소에 없거나, gh가 로그아웃되어 있거나, 파일이 약 390 KB보다 큰 것입니다.