MkDocs

한국어 마크다운 완전 가이드

📝 1. 제목

markdown

# 제목 1 (가장 큼)
## 제목 2
### 제목 3
#### 제목 4
##### 제목 5
###### 제목 6 (가장 작음)

결과:

제목 1 (가장 큼)
제목 2
제목 3

---

🔤 2. 텍스트 포맷

markdown

**굵은 텍스트** (중요함)
*기울인 텍스트* (강조)
***굵고 기울인 텍스트***
~~취소선~~ (지워진 텍스트)
인라인 코드

결과:

• 굵은 텍스트
• 기울인 텍스트
• 굵고 기울인 텍스트
• 취소선
• 인라인 코드

---

📋 3. 순서 있는 리스트

markdown

1. 첫 번째 항목
2. 두 번째 항목
3. 세 번째 항목
   1. 하위 항목 1
   2. 하위 항목 2
4. 네 번째 항목

결과:

1. 첫 번째 항목
2. 두 번째 항목
3. 세 번째 항목

---

🔹 4. 순서 없는 리스트

markdown

- 항목 1
- 항목 2
  - 하위 항목 2-1
  - 하위 항목 2-2
    - 더 깊은 항목
- 항목 3

* 별표로도 가능
* 항목 2

결과:

• 항목 1
• 항목 2
• 항목 3

---

✅ 5. 체크리스트

markdown

- [x] 완료된 작업
- [x] 다른 완료 작업
- [ ] 아직 안 한 작업
- [ ] 해야 할 작업

결과:

• 완료된 작업
• 다른 완료 작업
• 아직 안 한 작업

---

🔗 6. 링크

markdown

[링크 텍스트](https://example.com)

[새 탭에서 열기](https://example.com){target="_blank"}

[같은 사이트 링크](../guide/start.md)

[앵커 링크](#42-순서-없는-리스트)

<https://example.com>

---

🖼️ 7. 이미지

markdown

![이미지 설명](../images/logo.png)

![크기 조절](../images/screenshot.png){width="500"}

[![클릭하면 링크](../images/thumbnail.png)](https://example.com)

---

📊 8. 표 (테이블)

markdown

| 항목 | 설명 | 가격 |
|------|------|------|
| 상품 1 | 설명입니다 | 10,000원 |
| 상품 2 | 다른 설명 | 20,000원 |
| 상품 3 | 또 다른 설명 | 30,000원 |

| 왼쪽 정렬 | 중앙 정렬 | 오른쪽 정렬 |
|:------|:------:|------:|
| 왼쪽 | 중앙 | 오른쪽 |
| 텍스트 | 정렬됨 | 됨 |

결과:

항목	설명	가격
상품 1	설명입니다	10,000원
상품 2	다른 설명	20,000원

---

💬 9. 인용구 (Blockquote)

markdown

> 이것은 인용구입니다.
> 여러 줄도 가능합니다.

> **중요한 인용구**
> 굵은 텍스트도 가능합니다.

> 첫 번째 인용
> > 중첩된 인용
> > > 더 깊은 중첩

결과:

이것은 인용구입니다.
여러 줄도 가능합니다.

---

💻 10. 코드 블록

markdown

python
def hello():
    print("안녕하세요!")
    return True


bash
#!/bin/bash
echo "쉘 스크립트"
mkdocs serve


json
{
  "이름": "프로젝트",
  "버전": "1.0.0"
}

---

📌 11. 수평선

markdown

---

또는

***

또는

___

결과: 가로줄이 그어짐

---

📌 12. 탈출 문자

markdown

\*별표를 표시하려면\*
\[대괄호\]
\# 해시태그

---

🎯 완전한 한국어 예시 문서

docs/guide/complete-example.md:

markdown

# 완전한 마크다운 예시

## 1. 소개

이것은 **완전한 마크다운** 예시 문서입니다.
*모든 기능*을 포함하고 있습니다.

![기술 문서 로고](../images/logo.png){width="300"}

---

## 2. 설치 가이드

### 요구사항

- Python 3.8 이상
- pip (파이썬 패키지 관리자)
- Windows, macOS, 또는 Linux

### 설치 단계

1. **Python 다운로드**
   - [Python 공식 웹사이트](https://python.org) 방문
   - 최신 버전 다운로드

2. **설치 실행**
   - 다운로드한 설치 파일 실행
   - "Add Python to PATH" 체크 (중요!)

3. **설치 확인**

bash
python --version
pip --version


4. **프로젝트 생성**

cmd
mkdocs new my-project
cd my-project


---

## 3. 기능 비교표

| 기능 | MkDocs | Sphinx | Docusaurus |
|------|:------:|:------:|:----------:|
| 학습 난이도 | 쉬움 | 어려움 | 중간 |
| 마크다운 지원 | ✅ 완벽 | ⚠️ 제한 | ✅ 완벽 |
| 테마 풍부 | ✅ 많음 | ✅ 많음 | ⚠️ 적음 |
| 커뮤니티 | ✅ 큼 | ✅ 큼 | ⚠️ 작음 |

---

## 4. 주요 특징

> **핵심 기능**
> 
> MkDocs는 다음과 같은 특징을 가지고 있습니다:

- 마크다운 기반 문서화
- 자동 네비게이션 생성
- 라이브 서버 미리보기
- 정적 사이트 생성
- 무료 호스팅 가능

---

## 5. 자주 묻는 질문 (FAQ)

### Q1. MkDocs는 무료인가요?

**답:** 네, 완전히 무료이며 오픈소스입니다.

### Q2. 다국어를 지원하나요?

**답:** Material for MkDocs는 다국어를 지원합니다.
지원하는 언어:
- 한국어 (ko)
- 영어 (en)
- 일본어 (ja)
- 중국어 (zh)
- 등등

### Q3. 배포는 어렵나요?

**답:** 매우 간단합니다!

bash
# GitHub Pages에 배포
mkdocs gh-deploy

# Netlify에 배포 (site/ 폴더 업로드)
mkdocs build


---

## 6. 코드 예제

### Python 예제

python
# MkDocs는 마크다운으로 작성합니다
import mkdocs

def create_docs():
    """
    문서를 생성합니다
    """
    print("문서 생성 중...")
    return True

result = create_docs()


### Bash 예제

bash
#!/bin/bash
# MkDocs 배포 스크립트

echo "=== MkDocs 빌드 ==="
mkdocs build

echo "=== 배포 완료 ==="
echo "site/ 폴더가 준비되었습니다"


### 설정 예제

yaml
# mkdocs.yml
site_name: 기술 문서
site_description: 완전한 기술 가이드

theme:
  name: material
  language: ko

nav:
  - 홈: index.md
  - 설치: install.md
  - 가이드: guide.md


---

## 7. 체크리스트

- [x] 마크다운 학습
- [x] MkDocs 설치
- [x] 프로젝트 생성
- [x] 문서 작성 시작
- [ ] 웹에 배포
- [ ] 팀과 공유

---

## 8. 다음 단계

1. **문서 작성** - 프로젝트에 맞게 마크다운 파일 작성
2. **테마 커스터마이징** - Material for MkDocs 테마 설정
3. **배포** - GitHub Pages 또는 Netlify에 배포
4. **유지보수** - 문서 정기적으로 업데이트

---

## 9. 유용한 링크

- [MkDocs 공식 문서](https://www.mkdocs.org/)
- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
- [마크다운 가이드](https://www.markdownguide.org/)

---

> **팁**
> 
> Material for MkDocs를 사용하면 전문적인 문서를 쉽게 만들 수 있습니다!

마지막으로 **Happy Documenting! 🎉**

---

🎨 추가 한국어 예시들

기술 문서 예시

markdown

# API 문서

## 엔드포인트

### POST /api/users

사용자를 생성합니다.

**요청:**

json
{
  "이름": "김철수",
  "이메일": "kim@example.com",
  "나이": 30
}


**응답:**

json
{
  "성공": true,
  "사용자ID": 12345,
  "메시지": "사용자가 생성되었습니다"
}


**오류:**

| 코드 | 설명 |
|------|------|
| 400 | 잘못된 요청 |
| 401 | 인증 실패 |
| 500 | 서버 오류 |

튜토리얼 예시

markdown

# Python 시작하기

## 1단계: 환경 설정

먼저 Python을 설치해야 합니다.

bash
python --version


## 2단계: 첫 프로그램

python
# hello.py
print("안녕하세요!")


실행하려면:

bash
python hello.py


## 3단계: 함수 만들기

python
def 인사(이름):
    return f"안녕하세요, {이름}님!"

결과 = 인사("철수")
print(결과)

---

✅ 체크리스트: 마크다운 모든 기능

• 제목 (H1 ~ H6)
• 텍스트 포맷 (굵기, 기울임)
• 리스트 (순서 있음/없음)
• 링크
• 이미지
• 코드 블록
• 표
• 인용구
• 수평선
• 체크리스트