제대로 쓰는 마크다운 #

이 문서는 마크다운 문법 설명이 아니라,
글을 설계하는 관점에서 마크다운을 어떻게 쓰는지에 대한 기준을 정리한 가이드입니다.

저는 평소에 마크다운을 자주 이용하고 있습니다.
회사에서 하루에 있었던 일들을 정리하거나, 업무 내용이나 회의록을 작성할때도 먼저 마크다운으로 먼저 태블릿에 정리를 해두곤 합니다.
마크다운을 사용하면서 한가지 느낀점은 문법 이외의 글을 작성할 때 사용하는 방법, 기준에 대해서 정해두어야겠다 싶은 생각이 들어 글을 작성하고자 합니다.

---

1️⃣ 헤딩을 나누는 기준 #

헤딩을 나누는 기준은 여러가지 기준이 있겠지만 저는 보통 목차를 생각하며 헤딩을 나눕니다.
질문이 바뀌는 지점이나, 글의 전체적인 성격이 바뀔 때 헤딩을 새로 정의합니다.

특히 H1 헤딩은 글에서 딱 하나만 존재하도록 합니다. (H1에 대한 답을 찾아가는 것이 글의 목표)
아래에 좀 더 자세히 설명을 해보겠습니다.

---

H1 (#) — 이 글이 답하는 단 하나의 질문 #

예시:

mdCopy
# 안드로이드 태블릿으로 Next.js 개발 환경 구축하기

👉 제목만 보고 이 글이 무엇을 해결해 주는지 알 수 있어야 함

---

H2 (##) — 큰 사고 단위 / 큰 단계 #

가장 큰 틀인 H1의 답을 찾기 위해 또 다시 질문을 할 때 H2 헤딩을 사용합니다.
문단을 나누지 않고 줄줄이 설명하게 된다면 독자가 읽고 이해하기 더 어려워지기 때문에 이렇게 H2 헤딩으로 단계를 나눠 답을 찾도록 합니다.

예시:

mdCopy
## 왜 태블릿으로 개발하려 했는가
## 필요한 준비물
## 전체 구조 개요
## 실제 설치 과정

👉 목차에 올라가도 어색하지 않은 단위

---

H3 (###) — 실제 행동 단위 #

H2까지 이론에 대한 설명이였다면, H3부터는 실제로 행동해서 결과를 얻을 수 있는 작업에 대해서 서술합니다.

• 손을 움직이는 단계
• 실행 / 설정 / 클릭 단위

예시:

mdCopy
### Termux 설치
### Node.js 설치
### Next.js 프로젝트 생성

---

H4 (####) — 옵션 / 분기 / 주의사항 #

H4는 선택입니다. 내용을 굳이 안해도 되지만, 따라 했을 경우 부가적인 결과가 따라오는 것에 대한 내용을 적습니다.

• 안 해도 되지만 알면 좋은 내용
• 실수 방지 포인트

예시:

mdCopy
#### 권장 Node 버전
#### 에러가 발생하는 경우

---

2️⃣ 문법을 쓰는 판단 기준 (“어떨 때 쓰느냐”) #

❌ 문법 기능 설명
✅ 이 상황이면 이 문법을 쓴다

헤딩은 목차를 나누는 단위입니다. #이 많아질수록 중요도가 떨어지는 것이 아니라 점점 더 세부적인 내용으로 들어가는 것입니다.
다음은 다른 문법들입니다. 목록이나 코드블럭, 강조, 구분선 등등의 문법들을 사용하는 방법이 아닌 어떤 상황에 쓰는 것인지 알아봅니다.

---

📌 목록 (-, 1.) #

언제 쓰나?

• 나열이 목적일 때

• 문장으로 쓰면 숨 막힐 때

• 순서 중요 ❌ → -

• 순서 중요 ⭕ → 1. 2. 3.

예시:

mdCopy
## 준비물
- 안드로이드 태블릿
- 키보드
- 인터넷 연결

mdCopy
## 설치 순서
1. Termux 설치
2. Node.js 설치
3. Next.js 생성

---

📦 코드 블록 (```) #

언제 쓰나?

• 복사/붙여넣기가 필요한 순간
• 실행을 요구할 때

구조 원칙:

• 설명 → 코드 → 결과

예시:

mdCopy
``` bash
pkg install nodejs
```

👉 설명 중간에 코드를 끼워 넣지 말 것

---

🧠 인용 (>) #

언제 쓰나?

• 독자에게 잠깐 멈추게 할 때
• 주의 / 전제 / 경험 기반 조언

예시:

mdCopy
> 이 단계에서 에러가 나면 대부분 권한 문제입니다.

👉 남발하면 훈계처럼 보임

---

✨ 강조 (**) #

언제 쓰나?

• 스크롤 중에도 눈에 걸려야 하는 핵심 단어

예시:

mdCopy
이 방법의 **가장 큰 장점**은 비용이 들지 않는다는 점입니다.

👉 한 문장에 1개까지만 사용

---

🧱 구분선 (---) #

언제 쓰나?

• 이론 → 실습
• 배경 → 실행
• 큰 맥락 전환 지점

👉 "이제부터 다른 이야기"라는 신호

---

3️⃣ 문단을 나누는 기준 #

원칙 #

• 한 문단 = 한 주장 / 한 설명
• 3줄 이상이면 분리 고려

❌ 나쁜 예:

mdCopy
Next.js는 리액트 기반의 프레임워크이며 서버 사이드 렌더링을 지원하고 정적 사이트 생성도 가능하며 최근에는 App Router가 도입되어 구조가 변경되었다.

✅ 좋은 예:

mdCopy
Next.js는 React 기반의 프레임워크입니다.
서버 사이드 렌더링과 정적 사이트 생성을 지원합니다.

최근에는 App Router가 도입되면서
프로젝트 구조와 사고 방식이 크게 달라졌습니다.

---

5️⃣ 한 문장 요약 #

마크다운 언어는 생각을 정리하기 정말 좋은 도구라고 생각합니다.
저는 학창시절부터 메모하는 것이 서툴렀는데 마크다운 도구를 활용해서 정리하는 방법에 조금씩 익숙해지고 있습니다.

마크다운은 꾸미는 도구가 아니라
생각을 계층화하는 도구다.

• 헤딩 = 생각의 크기
• 문법 = 독자의 행동을 유도하는 신호