같은 마크다운이 GitHub·브라우저·변환기에서 다르게 보이는 이유

문법·확장 기능·디자인·보안 정책을 따로 봐야 합니다

같은 원문을 세 화면에서 비교하면 원인을 빠르게 찾을 수 있습니다

1. 1

   문제가 보이는 MD 원본에서 제목, 한 줄 줄바꿈, 표, 체크박스, 상대 경로 이미지, HTML이 있는 짧은 구간을 찾습니다.

2. 2

   원문을 텍스트로 확인해 문법 자체가 같은지 먼저 봅니다. 자동 저장이나 복사 과정에서 공백과 빈 줄이 바뀌지 않았는지도 확인합니다.

3. 3

   GitHub 또는 원래 작성한 서비스, 일반 마크다운 뷰어, 최종 변환 결과에서 같은 구간을 나란히 비교합니다.

4. 4

   차이를 문법 해석, 확장 기능, CSS 디자인, 링크 기준 위치, 보안 차단 가운데 하나로 분류합니다.

5. 5

   받는 사람이 사용할 최종 환경을 기준으로 문법을 단순화하거나 이미지 경로를 정리하고 다시 미리 봅니다.

CommonMark는 공통 문법의 기준이고 GFM은 기능을 더합니다

초기의 Markdown 설명만으로는 구현마다 애매하게 해석되는 부분이 생겼고, CommonMark는 제목·문단·목록·링크·코드 같은 핵심 문법을 더 명확하게 정의합니다. 하지만 모든 서비스가 같은 버전과 같은 옵션을 사용하는 것은 아닙니다.

GitHub Flavored Markdown(GFM)은 CommonMark를 바탕으로 표, 작업 목록, 취소선, 확장 자동 링크 같은 기능을 추가합니다. GitHub에서 멀쩡한 표가 단순한 렌더러에서 | 기호가 섞인 글자로 보인다면 파일 손상보다 확장 기능 지원 차이를 먼저 의심해야 합니다.

Enter 한 번은 문단 안의 줄바꿈일 수 있습니다

CommonMark에서 문단 안의 일반적인 줄 끝은 ‘부드러운 줄바꿈’입니다. 렌더러는 이를 화면에서 공백처럼 이어 보이게 할 수 있습니다. 그래서 원문에서 Enter를 한 번 눌렀는데 읽기 화면에서는 같은 문장처럼 이어질 수 있습니다.

확실한 새 문단은 빈 줄로 나누는 편이 가장 이해하기 쉽습니다. 문단 안에서 반드시 줄을 바꾸려면 줄 끝에 두 칸을 넣거나 백슬래시를 쓰는 CommonMark 방식이 있지만, 눈에 보이지 않는 두 칸은 편집 과정에서 사라질 수 있어 문서 규칙을 함께 정해 두는 편이 좋습니다.

• 새 문단: 문장 사이에 빈 줄 하나
• 같은 문단 안의 강제 줄바꿈: 줄 끝 공백 두 칸 또는 백슬래시
• 서비스 옵션: 일반 줄바꿈을 모두 강제 줄바꿈처럼 표시할 수도 있어 결과가 달라질 수 있음

Markdown은 구조를 저장하고 CSS가 겉모양을 결정합니다

MD 원문에는 보통 ‘이 문장은 28px 글꼴, 본문은 760px 너비’ 같은 화면 디자인 정보가 없습니다. 렌더러가 제목을 h1, 문단을 p, 코드를 pre 같은 문서 구조로 바꾼 뒤 각 서비스의 CSS가 글꼴, 크기, 줄 간격, 배경색과 최대 너비를 정합니다.

따라서 GitHub에서는 좁고 회색인 코드 블록이 다른 뷰어에서는 넓고 어둡게 보일 수 있습니다. 제목의 크기나 표 테두리가 달라도 제목·표라는 의미가 유지됐다면 내용이 변한 것은 아닙니다. 인쇄나 제출처럼 외형 고정이 목적이라면 최종 환경에서 PDF로 확정하는 것이 더 적합합니다.

상대 경로는 ‘현재 문서가 어디에 있는가’에 따라 달라집니다

은 사진 데이터를 MD 안에 넣은 것이 아니라 현재 문서 위치에서 images/photo.png를 찾으라는 지시입니다. GitHub 저장소에서는 현재 브랜치와 파일 위치를 기준으로 경로를 바꿔 주지만, MD 파일 하나만 받은 웹 뷰어는 옆 폴더의 파일에 접근할 수 없습니다.

GitHub는 저장소 안의 다른 파일과 이미지를 연결할 때 상대 경로를 권장합니다. 반대로 메일로 MD 파일 하나만 보내거나 HTML·PDF 한 파일로 전달할 때는 이미지 자산을 함께 묶거나, 접근 가능한 전체 URL을 사용하거나, 결과 파일에 이미지가 실제로 포함됐는지 확인해야 합니다. 어느 방식이 옳은지는 배포 단위에 따라 달라집니다.

HTML이 문법상 가능해도 그대로 실행된다는 뜻은 아닙니다

CommonMark는 일부 원시 HTML을 문법으로 다룹니다. 그러나 실제 서비스는 보안을 위해 script, iframe, 이벤트 속성, 입력 폼이나 특정 태그를 제거하거나 글자로만 보여줄 수 있습니다. 이는 마크다운 해석 오류가 아니라 해당 서비스의 보안 결정일 수 있습니다.

외부 웹 이미지도 비슷합니다. 이미지를 표시하면 문서를 연 사용자의 브라우저가 이미지 서버에 요청을 보내므로, 개인정보 보호를 우선하는 뷰어는 기본적으로 차단할 수 있습니다. 다른 사람에게 전달할 문서는 위험한 HTML에 의존하지 않고, 외부 자원이 없어도 핵심 의미를 이해할 수 있게 작성하는 편이 안전합니다.

여러 환경에서 잘 보이는 마크다운을 만드는 판단 기준

호환성을 높이려면 가장 기본적인 제목·문단·목록·링크·코드 블록을 중심으로 쓰고, 표와 체크박스처럼 확장 기능이 필요한 부분에는 일반 문장으로도 뜻이 전달되게 만드세요. 원시 HTML로 여백이나 색상을 맞추는 방식은 특정 서비스에 묶이기 쉽습니다.

완전히 같은 픽셀을 목표로 하기보다 제목 계층, 문단 순서, 목록 항목, 링크 대상, 코드 내용과 이미지 설명이 유지되는지를 확인하세요. 최종 결과가 중요한 제출 문서라면 목표 서비스나 변환 결과를 직접 미리 보는 것이 유일하게 확실한 확인 방법입니다.

• 필수 내용은 CommonMark의 기본 구조로 작성
• GFM 표·체크박스·취소선은 대상 서비스 지원 여부 확인
• 상대 이미지는 MD와 자산 폴더를 함께 배포
• 원시 HTML과 외부 자원 없이도 핵심 뜻이 남도록 작성
• 최종 전달 환경에서 가장 넓은 표와 긴 코드 줄까지 미리보기