README와 글을 게시하기 전에 Markdown을 안전하게 미리보기

문제 상황

Markdown은 평문이라 어디서나 같아 보이지만 렌더러마다 확장 문법과 경계 사례 처리가 다릅니다. GitHub, 문서 생성기, CMS, 이메일 편집기는 제목 ID, 작업 목록, 표, 원시 HTML, 각주, 수식, URL 정책을 서로 다르게 처리할 수 있습니다. 붙여넣은 문서에는 추적 이미지, 비공개 이슈 링크, 내부 호스트명, 코드 예시 속 토큰, 대상 서비스가 다시 해석할 HTML이 들어 있을 수도 있습니다. 로컬 미리보기는 이런 문제를 많이 드러낼 수 있지만 대상 렌더러, CSS, 보안 정책과 최종 검토를 대신할 수는 없습니다.

공식 출처와 표준

다음 공식 문서는 이 작업 흐름에서 다루는 형식과 보안 경계의 기준입니다. 도구별 실행 검증은 위에 별도로 기록합니다.

• CommonMark Specification

  CommonMark

이럴 때 사용하세요

• README나 변경 기록에 표, 작업 목록, 코드 펜스, 이미지, 각주가 있어 평문만으로 확인하기 어려울 때
• 기술 문서에 KaTeX 수식, 정의 목록, 접기 영역이 있어 게시 전에 시각 검토가 필요할 때
• Markdown을 CMS, 문서 사이트, 지식 저장소, 이메일 작업용 HTML로 변환할 때
• 복사한 문서에 원격 이미지, 원시 HTML, 비공개 링크, 내부 명칭, 민감한 예시 값이 있을 수 있을 때

단계

1. 1단계

   개인정보와 환경 전용 값을 먼저 제거합니다

   원문에서 접근 토큰, 쿠키, 이메일 주소, 계정 ID, 내부 호스트명, 비공개 저장소 링크, 고객명, 운영 로그 값을 찾으세요. 미리 보거나 공유하기 전에 의도적으로 만든 예시로 바꿉니다. 로컬 렌더링은 전송을 줄이지만 작업 사본, 클립보드 기록, 다운로드 파일과 최종 게시 대상에는 민감한 텍스트가 남을 수 있습니다.

2. 2단계

   게시 대상의 Markdown 규칙을 확인합니다

   대상이 GitHub Markdown, CommonMark, 정적 사이트 플러그인, CMS 파서 또는 미리 생성한 HTML 중 무엇을 사용하는지 확인하세요. 표 정렬, 작업 상태, 제목 앵커, 코드 언어명, 각주, 수식 구분자, 원시 HTML, 상대 경로처럼 중요한 기능을 적어 둡니다. 이 미리보기는 자주 쓰는 기능을 지원하지만 GitHub 자체 렌더러는 아닙니다.

3. 3단계

   모양보다 문서 구조를 먼저 봅니다

   문서를 불러와 논리적인 제목 계층, 목록 중첩, 표 머리글, 링크 문구, 이미지 대체 텍스트, 닫힌 코드 펜스, 각주 참조와 읽을 수 있는 대체 문구를 확인합니다. 큰 문서는 입력할 때마다 렌더링하지 않도록 수동 모드를 사용하세요. 코드 색상과 글꼴보다 올바른 구조를 먼저 검토합니다.

4. 4단계

   원격 이미지를 불러올지 명시적으로 결정합니다

   첫 검토에서는 원격 이미지를 끈 상태로 두세요. 상대 경로와 안전한 래스터 data 이미지는 확인할 수 있고 HTTP(S) 이미지 URL은 제거되어 경고로 표시됩니다. 모든 호스트를 신뢰하고 접속할 의도가 있을 때만 허용합니다. no-referrer 정책이 있어도 각 이미지는 IP 주소, 접속 시각, 사용자 에이전트 같은 정보를 호스트에 전달할 수 있습니다.

5. 5단계

   정제 결과와 HTML 조각을 함께 검사합니다

   렌더링 화면과 HTML 출력을 비교하세요. script, 이벤트 처리기, iframe, 삽입 미디어, form, 실행 가능한 URL 스킴, SVG data 이미지와 임의 스타일이 없는지 확인합니다. 안전한 details, 표, 작업 체크박스, 링크와 KaTeX 마크업은 남을 수 있습니다. 복사 결과는 테마가 포함된 완전한 문서가 아니라 콘텐츠 조각입니다.

6. 6단계

   실제 게시 시스템에서 다시 테스트합니다

   원본 Markdown 또는 HTML 조각을 대상 서비스의 초안, 스테이징 페이지, 임시 테스트 글에 넣으세요. 앵커, 상대 URL, 코드 스타일, 수식 자산, 표 가로 넘침, 다크 모드, 키보드 탐색과 모바일 너비를 다시 확인합니다. 대상 시스템이 이 도구의 정제 뒤에 마크업을 추가하거나 제거하거나 다시 쓸 수 있으므로 최종 네트워크 요청과 DOM도 검토하세요.

예시

# 버전 2.4 릴리스

- [x] 자동 테스트 실행
- [ ] 마이그레이션 안내 게시

| 영역 | 결과 |
| --- | ---: |
| 키보드 검토 | 통과 |
| 모바일 표 | 확인 필요 |

스테이징 기록을 확인하세요.[^review]

[^review]: 게시 전에 이 문구를 공개 검토 날짜로 바꾸세요.

h1 하나, 비활성 작업 체크박스, 표 머리글, 오른쪽 정렬 결과 셀, 연결된 각주, 비공개 스테이징 URL이 없음을 확인한 뒤 대상 렌더러에서 같은 검토를 반복합니다.

흔한 실수

자주 묻는 질문