Markdown 미리보기에서 데스크톱 화면이 깔끔하다는 사실만으로 문서가 완성되지는 않습니다. README의 긴 표, 코드블록, 링크, 체크박스는 작은 화면에서 가로로 밀리거나 줄바꿈이 어색해지기 쉽습니다. 원문을 작성하는 창과 렌더링된 결과를 나란히 보면서 독자가 휴대폰에서 실제로 읽는 순서를 확인해야 합니다.
이 도구는 입력 Markdown을 ReactMarkdown으로 렌더링하고 remarkGfm 플러그인을 연결해 GitHub Flavored Markdown 계열의 표·체크박스·취소선 같은 확장 문법을 처리합니다. 다만 이 미리보기의 CSS와 실제 GitHub·블로그의 CSS는 다를 수 있으므로, 여기서 통과한 결과를 최종 배포 화면과 동일하다고 간주하지 마세요.
렌더링 검수의 목표 화면을 먼저 고르기
모바일 검수는 모든 기기를 동시에 재현하는 일이 아니라, 실패 가능성이 큰 폭을 먼저 정하는 과정입니다. 320px 안팎의 좁은 화면, 일반적인 375px 화면, 태블릿이나 데스크톱의 넓은 화면을 대표값으로 두고 제목·표·코드·링크가 각각 어떻게 바뀌는지 기록하세요. 같은 문서를 세 폭에서 보면 한 줄 길이에 대한 가정이 드러납니다.
| 대표 폭 | 먼저 볼 블록 | 통과 질문 |
|---|---|---|
| 좁은 모바일 | 긴 제목·URL·표 | 가로 스크롤 없이 핵심이 보이는가 |
| 일반 모바일 | 문단·목록·코드 | 손가락으로 읽기 쉬운가 |
| 넓은 화면 | 편집창·미리보기 배치 | 두 패널의 흐름이 유지되는가 |
도구의 본문 편집 영역과 미리보기 영역은 중간 화면 이상에서 두 열로 배치되고, 미리보기에는 세로 스크롤이 생길 수 있습니다. 모바일에서는 한 열로 바뀌는 레이아웃을 예상하고, 입력창을 오래 스크롤한 뒤 결과의 같은 위치를 찾을 수 있는지 확인하세요. 화면 폭을 숫자로 남기면 나중에 CSS 변경 후 같은 실험을 반복할 수 있습니다.
제목 계층과 목록의 읽는 순서 확인하기
Markdown에서 `#`, `##`, `###`는 글자의 크기를 장식하는 표식이 아니라 문서의 계층을 나타냅니다. 문서 제목 하나 뒤에 주요 섹션을 H2로 두고, 세부 항목을 H3로 나누는 식으로 독자가 목차를 예측할 수 있게 하세요. 미리보기에서 크기만 확인하지 말고 제목만 이어 읽었을 때 내용의 흐름이 자연스러운지 점검합니다.
중첩 목록은 들여쓰기 하나가 의미를 바꿀 수 있습니다. 순서 목록 안에 하위 목록을 넣을 때 공백 수를 통일하고, 번호가 자동으로 표시되는지 확인하세요. 모바일에서는 긴 목록 항목이 여러 줄로 꺾이므로 각 항목의 첫 문장만 읽어도 행동이나 정보가 파악되는지 살피는 것이 좋습니다.
강조와 기울임은 중요한 단어를 표시하는 기능이지 문장 전체를 색칠하는 장치가 아닙니다. 미리보기에서 굵은 표현이 연속으로 붙어 있거나 링크가 본문과 구별되지 않으면 원문에서 강조 범위를 줄이세요. 화면의 대비와 링크 스타일은 도구의 현재 테마뿐 아니라 실제 게시처의 스타일에서도 다시 확인해야 합니다.
긴 표를 모바일 스트레스 테스트하기
표는 Markdown 문법이 맞아도 모바일에서 가장 쉽게 읽기 어려워지는 블록입니다. 열이 네 개 이상이거나 한 셀에 긴 URL·설명이 들어가면 화면 폭보다 내용의 최소 폭이 커질 수 있습니다. 미리보기에는 이름, 나이, 직업처럼 짧은 기본 표뿐 아니라 실제 문서의 가장 긴 열을 넣어 테스트해야 합니다.
| 시험 입력 | 왜 필요한가 | 관찰할 현상 |
|---|---|---|
| 열 2개 짧은 문장 | 기본 표 파싱 확인 | 머리글과 행 정렬 |
| 열 4개 긴 설명 | 폭 한계 확인 | 가로 넘침·줄바꿈 |
| 긴 영문 식별자 | 끊기지 않는 문자열 확인 | 컨테이너 밖으로 나감 |
| 빈 셀과 기호 | 실제 문서 예외 확인 | 행 높이·정렬 변화 |
표가 화면 밖으로 나가면 내용을 줄이거나 열을 세로 목록으로 바꾸는 선택지를 검토하세요. 무조건 CSS로 숨기면 모바일 독자가 중요한 값을 놓칠 수 있습니다. 원문과 미리보기 중 어느 쪽에서 문제가 생기는지 분리하고, 실제 게시 환경에서 가로 스크롤을 허용할지 문서 목적에 맞게 정해야 합니다.
코드블록과 링크가 끊기는 지점 찾기
코드블록은 긴 한 줄, 공백에 민감한 들여쓰기, 언어 표시가 결합되어 있어 작은 폭에서 문제가 드러납니다. 100자 안팎의 한 줄과 여러 줄의 짧은 코드를 각각 넣고, 줄바꿈으로 코드 의미가 변하지 않는지 확인하세요. 코드를 강제로 줄바꿈하면 복사해 실행할 때 다른 명령이 될 수 있으므로 읽기 편의와 실행 가능성을 분리해야 합니다.
현재 컴포넌트는 ReactMarkdown과 remarkGfm을 사용하지만 별도의 구문 강조 플러그인을 연결하지 않습니다. 따라서 코드블록이 렌더링되는 것과 JavaScript·Python 등의 문법 색상이 자동으로 입혀지는 것은 다른 기능입니다. 문서에서 색상 강조를 약속하려면 실제 배포 CSS와 렌더러를 별도로 확인해야 합니다.
긴 URL, 앵커 링크, 괄호가 들어간 링크는 모바일에서 주소가 잘리거나 클릭 영역을 알아보기 어렵게 만들 수 있습니다. 링크 텍스트는 목적을 설명하는 짧은 말로 두고, 주소 자체를 본문에 길게 노출할 필요가 있는지 검토하세요. 미리보기에서 링크가 클릭되는지뿐 아니라 링크 주변 문장이 무엇으로 이동하는지 알려 주는지도 확인합니다.
GFM 확장 문법을 실제 입력으로 시험하기
remarkGfm은 일반 Markdown보다 넓은 입력을 처리합니다. 표, 취소선, 작업 목록, 자동 링크처럼 GitHub 문서에서 자주 쓰는 문법을 각각 한 번 입력해 결과를 확인하세요. 문법이 렌더링되었다고 해서 모든 게시 플랫폼이 같은 방식으로 표시한다는 뜻은 아니며, 배포처의 Markdown 엔진이 다르면 다시 검수가 필요합니다.
- 제목과 강조 문법을 한 줄씩 입력합니다.
- 순서 목록과 중첩 목록의 들여쓰기를 확인합니다.
- 체크박스와 취소선의 상태가 의미를 보존하는지 봅니다.
- 표의 머리글·구분선·빈 셀을 시험합니다.
- 언어가 붙은 fenced code와 인라인 코드를 비교합니다.
문법 오류를 찾을 때는 여러 요소를 한 번에 넣지 마세요. 표가 깨졌다면 표만 남긴 최소 예제로 줄이고, 코드가 이상하면 코드블록만 분리합니다. 작동하는 최소 예제와 실제 문서의 긴 예제를 모두 보관하면 수정 후 어디서 문제가 재발했는지 쉽게 알 수 있습니다.
원문과 미리보기를 함께 비교하는 방법
왼쪽 입력창과 오른쪽 미리보기는 서로 다른 읽기 작업을 요구합니다. 원문에서는 공백, 백틱, 파이프, 대괄호를 보고 미리보기에서는 제목 계층, 줄 간격, 링크, 표 폭을 봅니다. 한쪽만 확인하면 문법은 맞지만 독자가 읽기 힘든 문서 또는 보기 좋지만 복사할 수 없는 문서를 놓칠 수 있습니다.
긴 표와 코드가 있는 README라면 문서의 첫 화면도 따로 확인하세요. 첫 제목과 첫 문단에서 문서의 목적이 전달되고, 첫 링크가 독자가 다음에 할 일을 안내해야 합니다. 미리보기는 입력 전체를 보여 주므로 문서의 첫 20초에 보이는 정보가 무엇인지 스크롤 없이 판단할 수 있어야 합니다.
현재 화면에는 Markdown 입력, 모두 지우기, 실시간 미리보기가 중심으로 제공됩니다. 작성 내용을 파일로 저장하는 기능이나 배포 저장소에 자동 반영하는 기능이 있는 것으로 가정하지 말고, 최종 원문은 별도 파일이나 버전 관리 시스템에 보관하세요. 테스트용 비공개 문서도 브라우저에 붙여 넣기 전 공유 범위를 확인하는 것이 안전합니다.
게시 전 모바일 QA 판정표
| 항목 | PASS 조건 | FAIL 때 수정 방향 |
|---|---|---|
| 제목 | 계층과 목적이 한눈에 보임 | H2·H3 순서 재배치 |
| 표 | 핵심 값이 잘리지 않음 | 열 축소 또는 목록화 |
| 코드 | 가로 넘침과 복사 의미를 확인함 | 짧은 예제·스크롤 방식 검토 |
| 링크 | 대상과 클릭 영역이 명확함 | 링크 텍스트와 주소 검토 |
| 데이터 | 비밀·개인정보가 없음 | 가상 값으로 교체 |
Markdown을 바로 시험하려면 Markdown 미리보기에 최소 예제와 실제 긴 블록을 차례로 넣어 보세요. 글자 제한과 문단 길이까지 함께 확인해야 한다면 글자수 세기에서 원문 분량을 측정할 수 있습니다. 기본 문법과 실제 문서 작성 규칙을 더 살펴보려면 Markdown 완벽 가이드를 이어서 읽어 보세요.