읽기 쉬운 마크다운 문서 구조: 제목·목록·표를 고르는 기준

첫 화면에서 문서의 목적이 보여야 합니다

읽기 쉬운 문서를 만들려면 제목을 꾸미기 전에 “누가 무엇을 결정하거나 실행할 것인가”부터 적으세요. 회의록이라면 결정 사항과 남은 질문, 작업 안내라면 준비물과 실행 순서가 중심입니다. 같은 자료라도 독자가 달라지면 앞에 둘 정보도 달라집니다.

예를 들어 이미지 제출 안내는 이미지 형식의 역사보다 허용 형식·최대 크기·제출 시점을 먼저 보여주는 편이 작업에 도움이 됩니다. 담당자가 결정한 내용과 작성자가 제안한 내용을 분리해야 후속 작업의 기준도 분명해집니다. 이 글에서는 가상의 문서를 구조화하는 사례로 방법을 설명하며, 특정 기관의 제출 조건을 제시하지 않습니다.

마크다운은 문장을 대신 작성하거나 사실을 확인하는 형식이 아닙니다. 제목·문단·목록·링크 같은 구조를 일반 텍스트에 표시하는 방법입니다. 기본 요소는 CommonMark 안내에서 확인할 수 있습니다. 문법을 많이 쓰는 것보다 독자가 필요한 부분을 찾고 이해할 수 있도록 배치하는 일이 먼저입니다.

제목은 글자 크기가 아니라 질문의 계층입니다

문서 제목 하나 아래에 결론, 준비 사항, 실행 순서, 확인 방법을 같은 단계로 놓는 식으로 구성합니다. 세부 단계가 필요할 때만 그 아래 제목을 추가하세요. 글자를 작게 보이게 하려는 이유로 ## 다음에 ####를 쓰면 정보의 관계가 흐려질 수 있습니다.

W3C의 제목 구조 안내는 제목의 계층이 문서 구성을 전달하고 보조 기술의 탐색에도 쓰인다고 설명합니다. 문서 안에서는 상위·하위 질문의 관계에 맞춰 단계를 정하세요. 사이트가 이미 글 제목을 H1으로 만들고 있다면 본문은 H2부터 시작하는 식으로 편집기와 게시 템플릿도 함께 확인해야 합니다.

이 글이 제안하는 간단한 작업 안내 구조는 다음과 같습니다. 내용은 구조를 설명하기 위한 자체 예시입니다.

# 사진 제출 안내

최종 파일 1개를 담당자에게 전달합니다.

## 제출 조건

- 파일 형식: JPG
- 파일 이름: 신청번호.jpg

## 준비 순서

1. 원본을 복사합니다.
2. 제출 조건에 맞춰 파일을 변환합니다.
3. 변환 파일을 열어 글자와 가장자리를 확인합니다.

## 확인 기록

| 항목 | 확인 결과 |
| --- | --- |
| 파일 열림 | 확인 |
| 신청번호 일치 | 확인 |

이 예시를 현재 프로젝트의 마크다운 파서로 변환해 H1 1개, H2 3개, 순서 없는 목록 1개, 번호 목록 1개, 표 1개가 생성되는 것을 확인했습니다. 이것은 구조 변환 검사입니다. 예시에 나온 JPG나 파일 이름이 모든 제출처에 맞는다는 뜻은 아닙니다.

목록과 표는 정보의 관계에 따라 선택하세요

모든 내용을 표에 넣으면 칸 안의 문장이 길어지고 작은 화면에서 읽기 어려워집니다. 반대로 같은 조건을 비교해야 하는데 각 대상을 긴 문단으로만 쓰면 독자가 항목을 기억하며 오가야 합니다. 다음 기준으로 골라 보세요.

표현	적합한 내용	이 예시에서의 용도
짧은 문단	결론, 이유, 적용 조건	왜 원본을 남겨야 하는지 설명
번호 목록	순서가 바뀌면 작업에 영향을 주는 단계	원본 복사 → 변환 → 확인
일반 목록	순서 없는 준비물·요건	파일 형식, 이름, 첨부 개수
표	여러 대상의 같은 속성 비교	형식별 투명도·용량·호환성 비교
코드 블록	공백·기호까지 보존할 예시	파일 이름 규칙이나 코드

단계 하나에 이유가 길게 따라붙는다면 각 단계를 짧게 두고 설명 문단을 따로 둡니다. 표의 한 셀에 여러 문단이나 또 다른 목록을 넣어야 한다면 표를 나누거나 소제목 구조로 바꿀 신호입니다. 모바일에서 가로로 넘겨야 하는 표에는 비교에 꼭 필요한 열만 남기세요.

표와 줄바꿈은 옮길 곳에서 다시 확인하세요

파이프 기호로 만든 표는 GFM의 확장 기능입니다. GitHub의 표 명세에 따르면 헤더 행과 구분 행이 필요하며, 셀 안에는 블록 수준 요소를 넣을 수 없습니다. 마크다운을 받는 서비스라고 해서 모두 같은 표·체크박스·HTML 기능을 지원하는 것은 아닙니다.

표를 지원하지 않는 곳에 전달해야 한다면 “항목: 값”의 목록으로 풀어 쓰는 대안을 준비하세요. 셀 안의 |를 데이터로 보여 주려면 이스케이프 규칙도 확인합니다. 링크 주소가 상대 경로라면 원래 폴더에서는 열려도 다른 서비스로 옮긴 문서에서는 다른 위치를 가리킬 수 있습니다. 문서를 옮길 때는 본문 파일뿐 아니라 이미지와 링크의 기준 위치도 확인해야 합니다.

편집 화면에서 Enter를 한 번 눌렀다는 사실과 게시 화면에서 줄이 바뀐다는 사실도 같지 않을 수 있습니다. 새 문단은 빈 줄로 분리하고, 꼭 필요한 줄바꿈은 목적지의 문법에 맞춰 표현하세요. 정렬을 위해 스페이스를 여러 개 넣는 방식은 피하고 표나 목록처럼 의도가 드러나는 구조를 씁니다.

원문·인용·판단을 구분해 남기세요

다른 문서를 요약하는 업무라면 “원문에서 확인한 사실”, “작성자가 해석한 내용”, “추가 확인할 질문”이 섞이지 않게 정리하세요. 출처가 있는 수치 옆에는 단위·대상 기간·원문 링크를 함께 남깁니다. 원문에 없는 결론을 제목으로 단정하면 문서가 깔끔해져도 정확성은 떨어집니다.

코드 블록에 적힌 문장도 검증된 사실이라는 뜻은 아닙니다. 예시 입력인지 실제 결과인지 표시하세요. 회의에서 제안만 한 날짜를 확정 일정처럼 목록에 옮기거나, 비어 있는 표 칸을 0으로 바꾸는 일은 피해야 합니다. 이런 의미의 변화는 마크다운 파서가 알아서 찾아 주지 않습니다.

문서를 변환해 가져왔다면 문서·표 데이터를 정리하는 전체 흐름에 따라 원본을 먼저 보관합니다. 표나 목록이 깨졌을 때는 문서에서 마크다운으로 변환한 결과의 확인 방법에서 구조별 검수 항목을 살펴보세요.

미리보기에서 구조와 목적지를 차례로 검수하세요

Tooliv의 마크다운 → HTML 도구는 입력을 파싱한 뒤 DOMPurify로 HTML을 정리합니다. 현재 구현은 style 태그와 스타일 속성을 제거하므로 색·글자 크기를 인라인 스타일로 지정한 결과까지 그대로 보존하는 도구는 아닙니다. 문서의 핵심을 스타일에만 의존하지 않게 작성하는 편이 전달에 유리합니다.

먼저 제목만 차례로 읽어 전체 흐름이 이해되는지 확인하세요. 다음으로 목록의 순서와 표의 열, 코드 블록의 기호가 원문과 같은지 봅니다. 마지막에는 실제로 전달할 서비스에서 링크·이미지·표가 열리는지 확인합니다. Tooliv 미리보기가 정상이라는 사실만으로 다른 서비스의 렌더링이나 접근 권한까지 확인된 것은 아닙니다.

검수 기록에는 사용한 파일, 확인한 목적지, 수정한 조건을 남겨 두세요. 이후 문서를 고칠 때는 전체를 다시 꾸미기보다 변경된 사실과 영향을 받는 설명을 함께 갱신할 수 있습니다.