마크다운 리스트 마스터하기: CommonMark 및 GitHub Flavored Markdown (GFM) 들여쓰기 표준
마크다운 리스트 렌더링의 기술적 기반
마크다운은 현대 소프트웨어 문서화, 기술 사양서, 개인 지식 베이스 및 개발자 간의 소통을 위한 표준 마크업 언어로 자리 잡았습니다. 단일 레벨 불릿 리스트(- 항목)와 번호 리스트(1. 항목)는 단순해 보이지만, 깊이 중첩된 다중 계층 개요를 작성할 때는 상당한 서식 복잡성이 발생합니다. CommonMark, GitHub Flavored Markdown (GFM), Python-Markdown, Pandoc과 같은 다양한 마크다운 파서는 리스트 기호 선택, 탭 대 공백 비율, 하위 블록 들여쓰기에 대해 엄격하고 미묘한 규칙을 적용합니다.
VS Code, Sublime Text, Xcode, Apple Notes, Microsoft Word와 같이 서로 다른 텍스트 에디터 간에 리스트를 붙여넣을 때 눈에 띄지 않는 들여쓰기 오류가 자주 발생합니다. 하위 항목에서 공백이 하나만 누락되어도 마크다운 컴파일러는 중첩된 자식 노드를 최상위 항목이나 독립된 단락 블록으로 잘못 해석하게 됩니다. Utiliome의 중첩 리스트 및 들여쓰기 정렬기는 입력 텍스트 구조의 AST(추상 구문 트리)를 파싱하고 표준 사양에 부합하는 마크다운을 재생성하여 이러한 파싱 오류를 완벽하게 제거합니다.
들여쓰기 규칙: 2공백 vs. 4공백 가이드라인
기술 문서 디자인에서 가장 자주 논의되는 주제 중 하나는 하위 리스트를 계층당 2공백으로 들여쓸 것인가, 아니면 4공백으로 들여쓸 것인가 하는 점입니다. 선택은 대상 마크다운 파서 사양에 따라 달라집니다.
2공백 들여쓰기 규칙 (표준 GFM 및 Prettier): GitHub, Docusaurus, Nextra, Obsidian과 같은 최신 웹 문서 생태계에서는 계층당 2공백이 표준으로 인식됩니다. 2공백 규칙은 자식 콘텐츠를 부모 항목의 텍스트 시작 위치에 깔끔하게 맞춥니다.
- 최상위 항목 1 - 중첩된 자식 항목 1.1 - 중첩된 자식 항목 1.2 - 깊이 중첩된 손자 항목 1.2.1 - 최상위 항목 24공백 들여쓰기 규칙 (엄격한 CommonMark 및 Python-Markdown): 엄격한 CommonMark 구현체에서는 번호 리스트 내부의 자식 블록, 코드 스니펫 및 중첩 리스트가 부모 블록에 올바르게 포함되도록 4공백(또는 1탭) 들여쓰기를 요구합니다.
1. 워크플로우의 첫 번째 단계 - 연관된 하위 불릿 A - 연관된 하위 불릿 B 2. 워크플로우의 두 번째 단계탭과 공백 혼용의 함정: 탭 문자(
\t)와 ASCII 공백 문자(\x20)를 혼용하는 것은 마크다운 문서 렌더링이 깨지는 가장 큰 원인입니다. 웹 렌더링 엔진은 탭을 불일치하게 해석하여(보통 4개 또는 8개 디스플레이 열로 처리) 중첩된 항목이 시각적으로 크게 어긋나게 만듭니다. Utiliome은 사용자의 설정에 따라 모든 탭 문자를 균일한 공백 문자열로 자동 변환합니다.
불릿 기호 표준화 및 순서 번호 수정
마크다운은 순서 없는 리스트를 위해 하이픈(-), 별표(*), 플러스 기호(+)의 세 가지 불릿 기호를 지원합니다. 세 가지 모두 유효한 HTML 순서 없는 리스트 요소(<ul>)를 생성하지만, 동일한 문서 내에서 기호를 혼용하면 시각적으로 산만해지고 markdownlint(예: 규칙 MD004)와 같은 자동 린터 검사를 통과하지 못합니다.
또한, 순서 있는 리스트 번호는 편집 과정에서 자주 깨집니다. 작성자가 번호 순서 중간에 항목을 붙여넣거나 1. 구문을 반복해서 사용하는 경우 발생합니다.
<!-- 서식이 깨진 입력 예시 -->
* 기능 A
- 기능 B
+ 기능 C
1. 첫 번째 단계
1. 두 번째 단계 (초안에서 복사됨)
4. 순서가 깨진 단계
Utiliome 정렬기는 모든 순서 없는 불릿 기호를 선택한 통일된 문자(예: 모든 항목을 -로 통일)로 표준화하고, 순서 있는 시퀀스를 순차적인 번호(1., 2., 3.)로 재구성하거나 팀의 코드 리뷰 가이드라인에 맞추어 깔끔하게 정렬합니다.