문서 작업 가이드
HTML 본문을 GFM Markdown으로 옮기고 게시 전에 검증하는 방법
HTML 본문을 분리해 GFM으로 변환하고, 손실 및 보안 경고를 해결하고, 자산을 옮긴 뒤 실제 게시 환경에서 검증하는 실전 절차입니다.
작성 및 검수 SimpleWebUtils게시일: 검토일:
이 작업 흐름을 검증한 방법
가이드 입력을 바꾸지 않은 채 마크업 변환 워크벤치에서 다음 예제를 재현했습니다: “추적 스크립트를 제거하고 상대 링크를 고쳐 릴리스 노트 옮기기”. 정상 절차는 “변환 전 원본 기준을 남깁니다”, “자산을 옮기고 대상 경로를 모두 고칩니다”; 경계 검토는 “내보낸 페이지 전체를 그대로 붙여넣기”, “미리보기가 괜찮다는 이유로 원시 HTML 무시하기”로 분리해 결과를 확정했습니다.
변환 결과는 제목과 표를 유지하고 /docs/setup을 지정한 기준 URL로 해석했으며, 실행 가능한 마크업은 Markdown에 옮기지 않고 제거했습니다.
문제 상황
CMS 내보내기 파일과 저장된 웹페이지에는 필요한 글뿐 아니라 내비게이션, 메타데이터, 추적 스크립트, 폼, 상대 경로 자산, Markdown으로 정확히 표현할 수 없는 HTML 구조가 섞여 있습니다. 변환 결과가 읽기 좋아도 헤더 없는 표가 달라지거나, 컨트롤이 사라지거나, 위험한 URL이 남거나, 이전 사이트에서만 작동하는 링크가 유지될 수 있습니다. 원본 범위, 변환 경고, 대상 경로, 렌더러 동작, 최종 게시 결과를 모두 확인해야 마이그레이션이 끝난 것입니다.
이럴 때 사용하세요
- 검토를 마친 CMS 본문이나 지식 문서를 Git 저장소, 정적 사이트 생성기, 위키, 문서 플랫폼으로 옮겨야 할 때
- 제목, 코드, 표, 링크, 작업 항목이 포함된 HTML 릴리스 노트를 편집 가능한 GFM으로 바꿀 때
- 저장한 HTML 조각을 읽기 쉬운 보관본으로 만들면서 변환하지 못한 구조의 흔적도 남겨야 할 때
- 여러 본문을 스크립트, 페이지 장식, 깨진 상대 자산 없이 반복해서 옮기는 검토 절차가 필요할 때
단계
- 1단계
본문 범위를 분리하고 의존성을 기록합니다
그 자체로 의미가 있는 가장 작은 본문, 문서 섹션, 릴리스 노트를 선택합니다. 사이트 내비게이션, 쿠키 배너, 관련 콘텐츠 패널, 푸터 링크, 문서 메타데이터는 제외합니다. 원본에 영향을 주는 이미지, 다운로드, 앵커, 임베디드 미디어, 표, 폼, 스타일시트를 모두 기록합니다. HTML을 마이그레이션 자료에 넣기 전에 비밀값, 공개 전 고객 정보, 내부 호스트명, 분석 식별자를 제거합니다.
- 2단계
변환 전 원본 기준을 남깁니다
원본 본문을 열고 제목 순서, 단락 구분, 목록, 인용문, 코드 언어 표시, 표 헤더, 링크 대상, 이미지 설명, 대체 텍스트, 상호작용 동작을 체크리스트로 남깁니다. 데스크톱과 좁은 화면을 모두 확인합니다. 이 기준이 있어야 의도한 Markdown 단순화와 실수로 생긴 데이터 손실을 구분하고 구체적으로 검토할 수 있습니다.
- 3단계
분리한 조각을 변환하고 모든 경고를 읽습니다
마크업 변환 워크벤치에서 HTML → Markdown 탭을 열어 분리한 조각을 변환합니다. 결과를 원본과 대조한 뒤 제거된 script와 style, 제외된 문서 메타데이터, 인라인 이벤트 핸들러, 활성 URL 스킴, Markdown 대응 형식이 없는 컨트롤과 미디어, 보존된 원시 HTML, 노드 제한, 깊은 중첩 경고를 확인합니다. 글이 눈으로 보기에 맞는다는 이유만으로 경고를 끝내지 않습니다.
- 4단계
Markdown으로 옮길 수 없는 구조를 해결합니다
폼, 버튼, iframe, canvas, SVG, audio, video는 게시 대상의 전용 컴포넌트로 다시 만들거나 의미 있는 링크와 설명으로 바꿉니다. details, kbd, mark, sub, sup, 헤더 없는 표를 대상 정책상 원시 HTML로 유지해도 되는지 결정합니다. rowspan과 colspan이 있는 표는 단순한 헤더 행 표, 목록, 여러 섹션으로 다시 구성합니다.
- 5단계
자산을 옮기고 대상 경로를 모두 고칩니다
승인된 이미지와 다운로드 파일을 최종 저장소나 미디어 위치로 복사하고 라이선스와 설명 가능한 파일명을 유지합니다. 상대 href와 src 값을 다시 쓰고, 조각 링크와 리디렉션을 확인하고, javascript 또는 문서형 data URL을 교체하고, 원시 HTML에 남은 이벤트 속성을 제거합니다. 원격 이미지가 사설 호스트를 노출하거나 만료되는 CMS 세션에 의존하지 않는지도 확인합니다.
- 6단계
실제 렌더러에서 미리 보고 검토된 변경으로 게시합니다
실제로 게시할 GitHub, 위키, 문서 엔진, 정적 사이트 빌드로 Markdown을 렌더링합니다. 링크, 이미지, 코드 펜스, 작업 목록 표시, 표, 원시 HTML 정책, 제목 탐색, 키보드 접근성, 390px 모바일 레이아웃을 시험합니다. 대상의 포매터, 린터, 링크 검사, 접근성 검사, 프로덕션 빌드를 실행하고 원본과 출력의 차이를 최종 검토한 뒤 병합하거나 게시합니다.
예시
추적 스크립트를 제거하고 상대 링크를 고쳐 릴리스 노트 옮기기
입력
<article><h1>릴리스 노트</h1><p><a href="/docs/setup">설정 가이드</a>를 읽으세요.</p><table><tr><th>버전</th><th>상태</th></tr><tr><td>2.4</td><td>준비</td></tr></table><script>trackDraft()</script></article>출력
# 릴리스 노트
[설정 가이드](https://docs.example.com/docs/setup)를 읽으세요.
| 버전 | 상태 |
| --- | --- |
| 2.4 | 준비 |
검토 기록에서 script 제거 경고를 해결하고, 상대 링크를 대상 주소로 바꾸고, 실제 렌더러에서 표를 확인합니다.흔한 실수
내보낸 페이지 전체를 그대로 붙여넣기
메뉴, 배너, 메타데이터, 스크립트, 무관한 패널이 불필요한 경고를 만들고 잘못된 본문 텍스트가 될 수 있습니다. 먼저 본문을 분리하고 페이지 수준 동작은 별도로 옮깁니다.
변환을 콘텐츠 정화로 간주하기
script 요소를 제거해도 남은 URL이나 원시 HTML이 승인되는 것은 아닙니다. 완전히 신뢰할 수 없는 콘텐츠에는 대상 신뢰 경계에서 명확한 URL 정책과 정화 도구를 적용합니다.
미리보기가 괜찮다는 이유로 원시 HTML 무시하기
한 렌더러는 details나 헤더 없는 표를 허용하지만 다른 렌더러는 제거하거나 속성을 다르게 처리할 수 있습니다. 보존된 원시 구조를 모두 목록화하고 프로덕션 정책에서 시험합니다.
상대 자산을 옮기기 전에 게시하기
로컬 미리보기는 이전 페이지나 개발 서버를 기준으로 경로를 해석할 수 있습니다. 최종 공개 URL에서 이미지, 다운로드, 링크, 조각 주소를 각각 확인하고 파일 누락 동작도 시험합니다.
글만 확인하고 코드, 표, 모바일 레이아웃은 놓치기
이스케이프, 코드 펜스 길이, 긴 표 셀, 줄바꿈 없는 URL이 문서 의미를 바꾸거나 가로 넘침을 만들 수 있습니다. 데스크톱과 모바일에서 해당 구조를 따로 대조합니다.
자주 묻는 질문
HTML 문서 전체를 한 번에 변환하면 안 되나요?
Markdown 본문은 문서 메타데이터, 애플리케이션 내비게이션, 분석 코드, 전역 스크립트를 소유하지 않습니다. 필요한 조각만 변환해야 제거 내용, 의존성, 구조 변화를 검토할 수 있습니다.
변환한 파일을 바로 게시해도 되나요?
안 됩니다. 모든 경고를 해결하고 자산과 URL을 고치고 원시 HTML 정책을 확인한 뒤 실제 대상 빌드로 렌더링해야 합니다.
헤더 행이 없는 표는 어떻게 해야 하나요?
표 데이터라면 의미 있는 헤더를 추가하고, 레이아웃용 마크업이라면 목록이나 섹션으로 바꿉니다. 대상이 명시적으로 허용할 때만 검토된 원시 HTML로 유지합니다.
로컬 변환이면 네트워크 요청이 전혀 없나요?
변환 자체는 연결된 페이지나 이미지를 가져오지 않습니다. 이후 미리보기나 게시된 Markdown 렌더러는 원격 자산을 요청할 수 있으므로 그 환경은 별도로 검사해야 합니다.
마이그레이션 완료를 증명하는 자료는 무엇인가요?
원본 기준과 최종 차이가 일치하고, 모든 경고의 해결 내역이 있으며, 공개 경로에서 링크와 자산 검사가 통과하고, 대상 빌드와 접근성, 모바일, 보안 검사가 깨끗해야 합니다.