빠른 비교
npm run build
npm run test```bash
npm run build
npm run test
```코드 블록 경계
네 칸 들여쓰기는 코드 블록이 된다
CommonMark에서 문단 바깥의 네 칸 들여쓰기는 indented code block으로 해석됩니다. 이 방식은 오래된 Markdown 문서에서 자주 보이지만, 언어 이름을 붙이거나 fence 안에 Markdown을 명확히 닫는 데는 불리합니다.
const name = "refdock";
console.log(name);렌더링 결과는 코드 블록이지만 js, bash 같은 info string이 없으므로 syntax highlighting을 기대하기 어렵습니다.
fenced code block이 문서화에는 더 명확하다
실무 문서에서는 삼중 backtick이나 tilde를 쓰는 fenced code block이 더 읽기 쉽습니다. 코드 시작과 끝이 눈에 보이고, 언어 이름을 붙일 수 있으며, 목록이나 blockquote 안에서도 의도가 더 분명합니다.
```js
const name = "refdock";
console.log(name);
```짧은 명령어 문서, README, 튜토리얼에서는 fenced code block을 기본값으로 두는 편이 좋습니다.
목록 안에서는 들여쓰기 기준이 달라진다
목록 안에 indented code block을 넣으려면 list item의 내용 영역 안에서 다시 네 칸 수준의 들여쓰기가 필요합니다. 즉 화면상 네 칸처럼 보이지 않아도, list marker 폭과 공백을 고려한 상대 들여쓰기로 판단됩니다.
1. 설치합니다.
npm install
npm run build이 규칙은 source를 읽는 사람에게도 헷갈리기 쉽습니다. 목록 안 코드 예시는 fenced code block으로 쓰면 실수를 줄일 수 있습니다.
선택 기준
| 상황 | 권장 방식 |
|---|---|
| 새 문서의 코드 예시 | fenced code block |
| 언어별 highlighting 필요 | fenced code block + info string |
| 오래된 Markdown 호환 | indented code block 가능 |
| 목록 안 코드 예시 | fenced code block 권장 |
| 코드 앞뒤 문단이 많음 | fence로 경계 명시 |
| 들여쓰기 자체가 중요한 예시 | fence 안에서 보존 |
주의할 점
indented code block은 의도하지 않은 공백 때문에 생기기 쉽습니다. 특히 목록, blockquote, 복사한 터미널 출력이 섞인 문서에서는 renderer가 문단을 코드 블록으로 바꿔 버릴 수 있습니다.
코드 블록이 갑자기 깨지면 backtick 개수보다 먼저 들여쓰기를 확인해야 합니다. 탭은 block 구조를 판단할 때 네 칸 기준으로 동작할 수 있으므로, 팀 문서에서는 tab 대신 space 사용을 고정하는 편이 안전합니다.
참고 링크
2 sources