노션·README로 웹페이지를 옮길 때 표와 링크를 보존하는 방법

웹페이지 전체 HTML을 그대로 변환하면 안 되는 이유

페이지에는 메뉴, 쿠키 배너, 광고, 추천 글, 숨은 접근성 텍스트가 함께 들어 있습니다. 전체 문서를 변환하면 본문보다 주변 링크가 더 많아질 수 있습니다. 개발자 도구나 읽기 모드로 실제 article·main 영역을 먼저 특정하는 편이 좋습니다.

표와 체크리스트가 환경마다 달라지는 이유

CommonMark 기본에는 표와 작업 목록이 없고 GitHub Flavored Markdown이 확장으로 제공합니다. README는 GFM 표를 지원하지만 다른 문서 도구는 HTML 표를 그대로 두거나 가져오기 과정에서 열 정렬을 잃을 수 있습니다. 대상 렌더러의 문법을 먼저 확인하세요.

상대 링크와 이미지 주소를 고치는 방법

HTML의 /guide/image.png 같은 상대 주소는 원래 사이트 기준 URL이 없으면 깨집니다. 연결 도구에는 base URL 입력 기능이 없으므로 변환 결과에서 링크와 이미지 src를 절대 주소로 직접 바꿔야 합니다. data-src 같은 lazy-load 속성만 있는 이미지도 실제 주소로 교체하세요.

변환 뒤 원문과 대조해야 할 항목

제목 계층, 링크 목적지, 코드의 꺾쇠괄호, 표 셀의 파이프, 이미지 대체 텍스트를 확인합니다. script·style·iframe과 추적 매개변수는 문서 목적에 필요하지 않다면 제거합니다. 저작권과 재게시 권한도 별도로 확인해야 합니다.

단계별로 확인하는 방법

1. 본문 HTML만 선택하기

   페이지의 article 또는 main 영역에서 실제 문서 내용만 가져옵니다.

2. 대상 마크다운 방언 정하기

   GitHub README인지 노션 가져오기인지 확인해 표·체크리스트 지원 범위를 정합니다.

3. HTML을 마크다운으로 변환하기

   본문 HTML을 변환한 뒤 상대 링크와 이미지가 남았는지 찾아 원래 사이트의 절대 URL로 직접 고칩니다.

4. 원문과 렌더 결과 대조하기

   제목 계층, 링크, 이미지, 표, 코드가 대상 화면에서 올바르게 보이는지 확인합니다.

함께 보면 좋은 글

• 웹페이지 HTML을 마크다운으로 옮기기
• 마크다운 표의 파이프와 줄바꿈 오류 고치기

노션과 GitHub README가 같은 마크다운을 쓰나요?

기본 문법은 겹치지만 표, 체크리스트, HTML 처리와 가져오기 동작이 다를 수 있습니다. 최종 대상에서 렌더링을 확인하세요.

웹페이지 표가 일반 문장으로 바뀌는 이유는 무엇인가요?

변환기가 표를 지원하지 않거나 대상이 GFM 표 문법을 해석하지 않을 수 있습니다. HTML 표 보존 또는 GFM 변환을 선택하세요.

상대 이미지가 README에서 깨지는 이유는 무엇인가요?

README는 원래 웹사이트의 기준 URL을 알지 못합니다. src를 완전한 HTTPS 주소로 바꾸거나 저장소에 이미지를 함께 넣어야 합니다.

웹페이지의 CSS 스타일도 마크다운으로 옮겨지나요?

마크다운은 문서 구조 중심이라 대부분의 CSS 스타일은 보존되지 않습니다. 중요한 표현은 제목, 강조, 표, 코드 같은 의미 구조로 바꾸세요.