숏컷 코드

- 상위 항목
  - 하위 항목
  - 하위 항목

1. 단계
   1. 세부 단계
   2. 세부 단계

문법

CommonMark는 들여쓰기 칸 수를 정밀하게 계산하기 때문에 일관성이 핵심이다

CommonMark 규격에서 bullet 목록의 중첩은 상위 마커 이후 콘텐츠 시작 위치를 기준으로 판단한다. - 이후 텍스트가 시작되는 열이 기준점이므로, 하위 항목은 그 열 이상으로 들여써야 중첩으로 인식된다. 일반적으로 공백 2칸 또는 4칸으로 통일하는 관행이 있지만, 번호 목록에서는 마커 폭이 다르기 때문에 1. 이후 콘텐츠 위치(보통 3칸)를 맞춰야 한다. 탭과 공백을 섞으면 렌더러마다 탭 폭 해석이 달라 의도하지 않은 결과가 나온다.

- 항목 A
  - 하위 A1 (공백 2칸)
  - 하위 A2

1. 1단계
   1. 세부 1-1 (공백 3칸, '1. ' 이후 위치 맞춤)
   2. 세부 1-2

목록 항목 아래에 코드 블록이나 문단을 넣으려면 들여쓰기가 이어져야 한다

목록 항목과 연결된 코드 블록이나 추가 문단을 같은 항목의 콘텐츠로 인식시키려면, 해당 블록도 목록 콘텐츠 시작 위치만큼 들여써야 한다. 들여쓰기가 부족하면 목록이 끝나고 새 코드 블록이나 문단이 시작된 것으로 파싱되어 목록 구조가 끊어진다. 이 규칙은 특히 단계별 설치 가이드처럼 각 단계 아래 코드 예시가 따라오는 문서에서 자주 틀리는 부분이다.

1. 저장소를 클론합니다.

   ```bash
   git clone https://github.com/example/repo.git

2. 의존성을 설치합니다.

   bash

   npm install

### 중첩이 3단계를 넘어가면 제목으로 분리하는 편이 더 읽기 쉽다

목록 중첩은 포함 관계를 표현하는 데 적합하지만, 3단계 이상 깊어지면 시각적으로 복잡해지고 들여쓰기 칸 수 계산도 어려워진다. 독자 입장에서도 어느 레벨의 항목인지 한눈에 파악하기 어렵다. 이런 경우 3단계 이상의 중첩 대신 `###` 소제목으로 분리하거나, 항목을 별도 섹션으로 독립시키면 문서 가독성이 크게 향상된다.

```text
<!-- 너무 깊은 중첩: 읽기 어려움 -->
- 시스템
  - 운영체제
    - 프로세스
      - 스케줄링
        - 알고리즘

<!-- 개선: 제목으로 분리 -->
## 시스템 구조

### 운영체제와 프로세스

- 프로세스 스케줄링 알고리즘
- ...

탭과 공백 혼용은 렌더러마다 결과가 달라지는 대표적인 함정이다

Markdown 렌더러는 탭 문자를 공백 4칸으로 확장하는 경우가 많지만, 이는 강제 사항이 아니다. GitHub, VS Code 미리보기, pandoc이 각기 다르게 해석할 수 있다. 실무에서는 목록 들여쓰기를 항상 공백으로만 처리하고, .editorconfig나 편집기 설정에서 탭을 공백으로 자동 변환하도록 설정하는 것이 혼란을 방지하는 가장 확실한 방법이다.

실무에서는 "보기에만 맞춘 들여쓰기"가 가장 자주 깨진다. 목록 안 코드 블록, 번호 목록 중첩, 복사된 탭 문자가 한 파일 안에 섞이면 렌더러마다 전혀 다른 구조처럼 보일 수 있다.

선택 기준

주의할 점

1. 설치합니다.
```bash
npm install

이 상태는 코드 블록이 1번 단계에 속하지 않고 목록 밖으로 빠질 가능성이 큽니다. 단계 아래 코드 예시는 fence 자체도 같이 들여써야 합니다.