Markdown 들여쓰기: 중첩 목록, 문단, 코드

Markdown 하위 목록을 들여쓰려면 마커를 상위 항목 본문의 첫 글자 아래에 맞춥니다. - 상위 항목에는 공백 두 개, 1. 상위 항목에는 세 개가 필요합니다. 들여쓰기는 문서 구조를 제어하므로 일반 문단에 공백을 추가하는 일은 Word에서 문단의 시각적 들여쓰기를 바꾸는 것과 매우 다른 결과를 낼 수 있습니다.

Markdown 뷰어에서 다음 예제로 시작하세요.

- 프로젝트 문서
  - 설치 가이드
  - 릴리스 노트
- 검토 체크리스트

설치 가이드와 릴리스 노트는 프로젝트 문서 항목 아래에 표시되어야 합니다. 검토 체크리스트는 바깥 단계에 남아 있어야 합니다.

상위 항목의 본문 위치를 기준으로 세기

마커 뒤에 공백을 하나 넣는 일반 목록 항목에는 다음 정렬 기준을 사용하세요.

상위 항목의 시작	본문 앞 문자 수	하위 목록 들여쓰기
`-`	2	공백 2개
`1.`	3	공백 3개
`12.`	4	공백 4개
`100.`	5	공백 5개

따라서 "항상 공백 두 개를 사용한다"와 같은 일괄 규칙은 번호 목록에 맞지 않습니다. GitHub의 중첩 목록 문서는 더 긴 숫자 마커를 포함하여 상위 항목의 본문을 기준으로 정렬하는 방법을 보여 줍니다.

1. 릴리스 준비
   - 버전 번호를 확인합니다.
   - 변경 로그를 업데이트합니다.
2. 문서 게시

중첩 마커 앞에는 공백이 세 개 있습니다. 왼쪽 가장자리에서 시작하면 첫 번째 번호 단계에 속하지 않고 별도의 목록을 시작합니다.

오래된 Markdown 처리기를 사용한다면 해당 처리기에서도 파일을 미리 보세요. 이 글의 예제는 CommonMark 방식의 파싱과 GitHub Markdown을 대상으로 합니다. 이전 구현은 중첩 블록을 인식하는 방식이 다를 수 있습니다.

목록 항목 안에 문단 추가하기

긴 설명에 별도의 글머리 기호가 꼭 필요하지는 않습니다. 빈 줄을 넣고 새 문단을 항목 본문 아래에 맞춥니다.

1. 설치 가이드를 검토합니다.

   처음 읽는 사람이 내부 문서를 열지 않고도
   설정을 완료할 수 있는지 확인합니다.

2. 릴리스 노트를 승인합니다.

설명 문단은 첫 번째 단계에 속합니다. 명시적인 줄바꿈을 추가하지 않으면 두 소스 줄은 이어서 표시됩니다.

공백 세 개를 생략하면 번호 목록이 끝나고 설명이 일반 문단으로 바뀔 수 있습니다. 일부 편집 작업 흐름에서는 그 뒤의 목록 번호가 다시 시작되는 원인이 되기도 합니다.

글머리 기호 목록에서도 같은 형식을 사용할 수 있습니다.

- 설치 가이드

  사전 요구 사항, 설정 명령, 검증 단계를 포함합니다.
- 릴리스 노트

설명이 여러 문장으로 구성되면 별도의 문단을 사용하세요. 독자가 각각 훑어봐야 하는 구분된 항목이 들어 있으면 하위 목록을 사용합니다.

번호 단계 안에 코드 넣기

울타리 코드는 명령 예제의 경계를 눈에 보이게 만듭니다. 시작 울타리, 내용, 닫는 울타리를 모두 들여쓰기하여 블록을 목록 항목 안에 유지하세요.

1. 설치된 버전을 확인합니다.

   ```sh
   node --version
   ```

   결과를 검토 메모에 기록합니다.

2. 프로젝트 검사를 실행합니다.

여기서 울타리는 설치된의 첫 글자 아래에서 시작합니다. 울타리 뒤의 문단도 같은 정렬을 사용하므로 첫 번째 단계 안에 유지됩니다.

다음 번호 단계가 코드 블록의 일부가 된다면 닫는 울타리를 확인하세요. 코드가 목록 밖에 나타나면 울타리 앞의 공백을 확인합니다. 언어 라벨과 백틱을 문자 그대로 표시하는 방법은 코드 블록 가이드를 참고하세요.

공백 네 개가 텍스트를 코드로 바꾸는 이유

문서의 가장 바깥 단계에서 빈 줄 다음에 오는 줄 앞에 공백을 네 개 넣으면 들여쓰기 코드 블록이 만들어질 수 있습니다.

일반 문단입니다.

    이 줄은 코드로 표시됩니다.

이는 의도된 Markdown 문법이며, 들여쓰기 기능의 오류가 아닙니다. CommonMark 들여쓰기 코드 블록 참고 문서는 들여쓰기와 블록 경계의 역할을 설명합니다.

일반 문단 텍스트 바로 뒤에 오는 들여쓴 줄에는 다른 파싱 제약이 적용되므로, 공백을 넣는 것은 문단을 시각적으로 들여쓰는 확실한 방법이 아닙니다. 목록 안에서 필요한 공백 수는 해당 내용을 포함하는 항목을 기준으로도 결정됩니다.

인용문에는 인용 블록을 사용하세요. 최종 보고서에서 일반 본문의 첫 줄 들여쓰기가 필요하다면 Markdown은 일반 문단으로 유지하고, 내보낸 뒤 Word에서 문단 서식을 적용하세요. 이렇게 하면 내용의 의도된 의미를 보존할 수 있습니다.

문제를 점검할 때는 공백을 우선 사용하기

탭은 화면에서 여러 칸을 차지하며, 편집기마다 표시 너비가 다를 수 있습니다. 소스에서 목록이 정렬된 것처럼 보여도 렌더링이 잘못되면 편집기에서 공백 문자를 표시하고 행 앞의 탭을 필요한 수의 공백으로 바꾸세요.

코드 예제 안의 탭을 무조건 바꾸지는 마세요. 그곳의 공백은 예제 자체의 일부일 수 있습니다. 정리는 주변 목록 구조를 결정하는 Markdown 마커와 이어지는 내용의 들여쓰기로 한정하세요.

줄바꿈 없는 공백 엔터티를 반복하여 중첩 목록을 흉내 내지 마세요. 한 미리보기에서는 텍스트가 이동한 것처럼 보이더라도 기본 문서는 서로 관련 없는 문단으로 남을 수 있습니다.

Word 내보내기 전에 구조 검증하기

상위 항목, 하위 목록, 두 번째 문단, 울타리 코드 블록을 포함한 대표적인 절 하나를 검토하세요. Markdown을 HTML로 변환하는 도구에서 실제 중첩 목록은 상위 목록 항목 안에 들어 있습니다. 시각적인 위치 이동만으로는 그 관계가 성립하지 않습니다.

그런 다음 Markdown을 Word로 변환하는 도구를 사용하여 DOCX를 여세요. 번호가 의도대로 이어지는지, 명령이 해당 단계에 계속 연결되어 있는지 확인합니다. Word의 목록 스타일은 브라우저와 다른 시각적 간격을 사용할 수 있으므로 공유하기 전에 계층 구조와 최종 문서의 외관을 모두 확인하세요.