마크다운

학습 목표

• 마크다운이 무엇이고 어떤 설계 의도로 만들어졌는지 설명할 수 있다.
• 마크다운 문법을 상황에 맞게 활용해 문서를 작성 할 수 있다.

1. 마크다운 문법들

1-1 제목

#을 통해 단계별 제목을 설정 할 수 있다.
단계를 건너뛰지 않고 사용한다.
단순히 글자를 크게 만드는 것이 아닌 뼈대를 만드는 표시이다.
'#' 뒤 공백은 생략 할 수 없다.

1-2 문단 나누기

문단 끝에 공백 2개를 넣는 방법

문단 끝에 \ 를 넣는 방법\

HTML 태그인
쓰는 방법

1-3 강조

기울임, 기울임 = ''기울임'', ''기울임'' (' 는 어떤게 쓰인 것인지 보이기 위해서 쓰임)
굵게, 굵게 = ''굵게'', ''굵게''
굵은 기울임, 굵은 기울임 = ''굵은 기울임'', ''굵은 기울임''

밑줄()은 앞뒤가 글자로 둘러싸인 곳에선 강조로 인식하지 않는다.
별표는 제약이 없다. GameObject / Game__Object_

강조 기호를 문자 그대로 보이게 하려면 앞에 \ 를 넣는다.
별표= 별표
이 방법은 다른 기호 (#, -, [ )등에도 쓸 수 있다.

1-4 목록

목록은 여러 항목을 나열하는 표시이다. 순서가 의미를 갖는지에 따라 두 종류로 나뉜다.

• 순서 없는 목록 : 항목의 순서에 의미가 없다. 준비물, 특징 등을 나열 할 때 사용

줄 앞에 -, +, ''* 중 하나를 놓고 공백을 넣는다. 세 기호 모두 같은 결과를 낸다

• 첫째 항목
• 둘째 항목
• 셋째 항목

기호는 한 문서 안에서 하나로 통일해서 사용. 섞으면 렌더러가 해석 오류 날 수 있음.

• 순서 있는 목록 : 항목의 순서가 의미가 있다. 절차나 단계를 적을 때 사용

줄 앞에 숫자와 마침표를 놓고 공백을 넣는다.

1. 저장소를 내려받습니다.
2. Unity Hub에서 프로젝트를 엽니다.
3. 씬을 열고 재생합니다.

중간에 항목을 끼워 넣어도 번호를 다시 매길 필요가 없다. 다만 원본 텍스트에서 알아보기 어려우므로 수정해줄것.

• 목록 중첩 : 목록 안에 목록을 넣으려면 들여쓰기를 한다.
  • 상위 항목에서 Enter 입력 후 Tab으로
  • 하위 항목이 만들어지면서 자동 들여쓰기가 된다
  • 하위 항목에서 상위 항목으로 다시 만들고 싶을 땐
• Enter를 두 번 누르면 된다.

1. 상위 항목
2. 하위 항목
3. 하위 항목 1. 하하위 항목

1-5 코드

• 문서 안에 코드를 넣을 때는 일반 문장과 구분되게 표시한다. 구분하지 않으면 2가지 문제가 생긴다.

1.  코드 안의 기호가 마크다운 문법으로 해석된다
2.   '*ptr'처럼 별표로 시작하는 코드가 목록 항목으로 인식되거나
3. '[index]' 의 대괄호가 링크로 처리되는 식이다
4. 읽는 사람이 어디까지가 코드인지 알기 어렵다.
5. 코드 표시에는 2가지가 있다. 문장 중간 짧게 넣는 인라인 코드, 여러 줄을 통째로 넣는 코드 블록
6. 인라인 코드
7. 백틱 (`)으로 감싼다. 1. ex) 설정 파일은 'config.json' 이며 'Assets' 폴더 아래에 둡니다.
8. 코드 블록
9. 백틱 3개로 시작하고 3개로 닫는다. 이것을 펜스(fence)라고 부른다.

using UnityEngine;

public class Player : MonoBehaviour
{
    private void Start()
    {
    }
}

1-6 언어 지정

여는 펜스 뒤에 언어 이름을 적으면 그 언어의 문법에 맞게 색이 입혀진다.

using UnityEngine;

public class Player : MonoBehaviour
{
    [SerializeField] private float _moveSpeed = 5f;

    private void Update()
    {
        float horizontal = Input.GetAxis("Horizontal");
        transform.Translate(Vector3.right * horizontal * _moveSpeed * Time.deltaTime);
    }
}

백틱 개수 : 코드 블록 안에 백틱 3개짜리 코드 블록을 넣어야 할 때 fence의 백틱의 수가 안쪽 보다 많게 적어야 한다.
이유는 CommonMark에서 정한 닫는 펜스의 규칙에 있다.

"The closing code fence must be at least as long as the opening fence." (닫는 코드 펜스는 여는 펜스와 같거나 더 길어야 한다.) 출처: CommonMark 명세

여는 fence가 백틱 3개일 때 안쪽 내용에 백틱 3개짜리 줄이 나오면, 그 줄이 닫는 fence 조건을 만족하므로 코드 블록이 끝나버린다.

1-7 인용문과 수평선

인용문

인용문은 다른 곳에서 가져온 문장이나 특별히 구분해 보일 내용을 표시한다.
렌더링하면 왼쪽에 세로선이 붙고 안쪽으로 들여쓰인 형태로 표시된다. (ex) closing fence rule)

줄 앞에 '>'를 놓고 공백을 넣는다.

인용문 입니다.

여러 줄을 인용하려면 각 줄 앞에 '>'를 붙인다.

첫 번째 줄 인용문.

두 번째 줄 인용문.

이곳 Develog에서는 인용문 안에서 자동으로 처리되어 두 번째 줄에 '>'를 따로 입력하지 않아도 괜찮다.

'>'를 여러 개 겹치면 인용 안의 인용이 된다.

바깥 인용문.

안쪽 인용문.

 

인용문 안에는 목록 · 코드 블록 같은 다른 문법을 넣을 수 있다.

수평선

' - ', ' * ', ' _ ' 중 하나를 세 개 이상 이어서 한 줄에 쓴다.

세 기호 모두 같은 결과를 내지만 <'mark'> ' - ' 를 쓸 땐 주의를 해야 한다.
<'/mark'> 바로 위 줄에 글자가 있으면 수평선이 아닌 2단계 제목의 밑줄로 해석된다.

1-8 링크와 이미지

링크는 다른 문서나 웹 주소로 이동하는 표시, 이미지는 그림을 문서 안에 표시하는 것이다.
두 문법은 형태가 거의 같다. 이미지 문법이 링크 문법 앞에 느낌표를 붙인 모양이다.

인라인 링크

대괄호에 표시할 글자를, 소괄호에 주소를 쓴다.

[Unity 공식 문서](https://docs.unity3d.com/)

Unity 공식 문서

주소 뒤에 따옴표로 설명을 붙이면 마우스를 올렸을 때 표시가 된다.

[Unity 공식 문서](https://docs.unity3d.com/ "Unity Documentation")

Unity 공식 문서

참조 링크

같은 주소를 여러 번 쓰거나 주소가 길어 문장 읽기를 방해 할 때 쓰인다.
본문에는 이름만 두고 주소는 문서 아래쪽에 모은다.

자세한 내용은 [공식 문서][docs]를 참고합니다.
설치 방법도 [공식 문서][docs]에 있습니다.

[docs]: https://docs.unity3d.com/

자세한 내용은 공식 문서를 참고합니다.
설치 방법도 공식 문서에 있습니다

주소 정의 줄은 문서 어디에 두어도 되고 렌더링 결과에 나타나지 않는다.

자동 링크

주소를 그대로 쓰면 GitHub는 자동으로 링크로 만든다.
다만 이것은 GFM의 확장 기능이고 표준에는 없다. 표준 방식은 꺾쇠로 감싸는 것이다.

<https://docs.unity3d.com/>

<https://docs.unity3d.com/>

문서 내 이동

같은 문서 안의 제목으로 이동하는 링크를 만들 수 있다.
주소 자리에 '#' 과 제목을 소문자로 바꾸고 공백을 ' - '로 바꾼 값을 쓴다.

[설치 절차로 이동](#설치-절차)

설치 절차로 이동

상대 경로

같은 저장소 안의 다른 파일로 연결 할 때는 전체 주소 대신 상대 경로를 쓴다.

[기여 방법](CONTRIBUTING.md)
[설계 문서](docs/design.md)

기여 방법

설계 문서

<'mark'> 상대 경로를 쓰면 저장소를 내려받은 상태에서도 링크가 동작한다.
<'/mark'> 전체 주소로 적으면 인터넷에 연결되어 있어야만 열린다.

이미지

링크 문법 앞에 느낌표를 붙인다.
대괄호 안에는 이미지가 표시되지 않을 때 대신 보일 설명을 쓴다.

![플레이 화면](images/gameplay.png)

README에서 문서와 이미지를 함께 씁니다.

# Dodge Game

![플레이 화면](docs/images/gameplay.png)

Unity로 만든 회피 게임입니다.
자세한 설계는 [설계 문서](docs/design.md)를 참고합니다.

## 참고 자료

- [Unity 공식 문서](https://docs.unity3d.com/)
- [C# 언어 참조](https://learn.microsoft.com/dotnet/csharp/)

<'mark'> 대체 텍스트를 비워 두지 않는다.
<'/mark'> 이미지 파일이 옮겨지거나 이름이 바뀌면 이 글자만 남으므로, 무엇이 있었는지 알 수 있게 적어둔다.

1-9 표

개념

표는 항목을 행과 열로 정리해 보이는 것이다.
여러 대상을 같은 기준으로 비교할 때 문장보다 읽기 쉽다.

문법 형식

파이프( ' | ' )로 칸을 나눈다.
첫 줄이 열 이름이고, 둘째 줄은 ' - '로 이루어진 구분행이며, 셋째 줄부터 내용이다.

| 컴포넌트 | 역할 |
|---|---|
| Transform | 위치·회전·크기 |
| Rigidbody | 물리 연산 |
| Collider | 충돌 판정 |

<'mark'> 구분행은 생략 할 수 없다.
<'/mark'> 이 줄이 있어야 렌더러가 표로 인식한다.
' - '의 개수는 몇 개든 상관 없으므로 하나씩만 써도 된다.

정렬

구분행에 콜론을 넣어 열의 정렬을 지정한다.

| 왼쪽 | 가운데 | 오른쪽 |
|:---|:---:|---:|
| 1 | 2 | 3 |
| 10 | 20 | 30 |

숫자 열은 오른쪽 정렬로 두면 자릿수가 맞아 비교하기 쉬워진다.

칸 안에 파이프 넣기

파이프는 칸을 나누는 기호이므로 내용으로 쓰려면 백슬래시를 앞에 붙여야한다.

"To include a pipe | as content within your cell, use a \ before the pipe" (파이프 |를 칸의 내용으로 넣으려면 파이프 앞에 \를 쓴다.) 출처: GitHub 공식 문서

| 표기 | 뜻 |
|---|---|
| `a \| b` | a 또는 b |

인라인 코드 안에 있어도 이스케이프가 필요하다.

원본 정렬

원본 텍스트에서 파이프의 위치가 맞지 않아도 결과는 같다.

| 컴포넌트 | 역할 |
|---|---|
| Transform | 위치·회전·크기 |
| Rigidbody | 물리 연산 |

|컴포넌트|역할|
|-|-|
|Transform|위치·회전·크기|
|Rigidbody|물리 연산|

두 입력의 결과는 같다. 다만 원본을 읽거나고칠 일이 있으므로 어느 정도 맞춰 두는 편이 좋다.

사용 예시

설정값이나 조작 방법처럼 항목과 값이 짝을 이루는 내용에 쓴다.

## 조작

| 동작 | 키 |
|---|---|
| 이동 | 방향키 |
| 대시 | Shift |
| 일시정지 | Esc |

## 난이도 설정

| 난이도 | 장애물 수 | 이동 속도 |
|---:|---:|---:|
| 쉬움 | 5 | 3.0 |
| 보통 | 10 | 5.0 |
| 어려움 | 20 | 8.0 |

<'mark'> 표에 긴 문장을 넣지 않는다.
<'/mark'> 칸이 좁아 줄바꿈이 많아지면 표의 장점인 한 눈에 비교하기가 어렵다.
설명이 길어지면 목록이나 문단으로 쓴다.

1-10 확장 문법

개념

표준 마크다운에 없지만 GitHub에서 쓸 수 있는 문법들이 있다.
표도 그 중 하나고, 이 장에서 나머지를 모아 다룬다. 이 문법들은 <'mark'> 어디에서나 동작한다고 가정 할 수 없다.

1. <'/mark'> GitHub에서 잘 보이던 문서를 다른 곳에 옮겼을 때 깨진다면 이 장의 문법을 썼기 때문일 가능성이 높다.
2. GFM에는 공식 명세 문서가 있는데, 그 문서에 실린 확장 목록과 GitHub가 실제로 렌더링하는 문법의 범위가 같지 않다.
3. 명세 문서가 나온 뒤 GitHub가 추가한 기능들은 실제로 동작하지만 그 목록에는 없다.

이 구분은 GFM 공식 명세 문서(2019년판)에 실린 확장 목록과 GitHub가 그 뒤에 자체 공지를 통해 추가한 기능을 나눈 것이다.
(GFM 명세 및 GitHub 공지, 2026년 8월 확인)

문법 형식

작업 목록

목록 항목 앞에 대괄호를 넣어 완료 여부를 표시한다.

- [x] 플레이어 이동 구현
- [x] 장애물 생성
- [ ] 점수 표시
- [ ] 사운드 추가

렌더링하면 각 항목 앞에 체크 상자가 붙고, '[ x ]'로 표시한 항목은 체크된 상태로 나타난다.

대괄호 안에 공백을 빼먹으면 동작하지 않는다.
' -, [ ] ' 는 체크 상자가 되지 않고 대괄호가 그대로 보인다.

취소선

물결표 두 개로 감싼다.

~~취소된 내용~~

취소된 내용

수정 이력을 남길 때나 더 이상 유효하지 않은 항목을 표시 할 때 쓴다.

각주

본문에 표시를 남기고 문서 아래쪽에 내용을 적는다.

Unity는 C#을 사용합니다[^1].
[^1]: 과거에는 UnityScript와 Boo도 지원했으나 현재는 지원하지 않는다.

본문에는 위첨자 번호가 표시되고, 문서 맨 아래에 각주 목록이 생기며 서로 연결된다. 번호 대신 이름을 써도 된다.

Unity는 C#을 사용합니다[^언어].

[^언어]: 과거에는 다른 언어도 지원했었다.

각주는 GFM 명세 문서에는 없고 GitHub가 나중에 추가한 기능이다. (GitHub 각주 지원 공지, 2026년 8월 확인)

알림 상자

인용문 첫 줄에 정해진 표시를 넣으면 색과 아이콘이 붙은 상자로 표시된다.

> [!NOTE]
> 참고할 내용입니다.

> [!WARNING]
> 주의가 필요한 내용입니다.

GitHub가 지원하는 종류는 5가지이다.

GitHub 공식 문서는 <'mark'> 꼭 필요할 때만 쓰고 문서당 한 두개로 제한할 것 <'/mark'>을 권하고 있다.
많이 쓰면 시선을 끄는 효과가 사라지기 때문이다.

다이어그램

코드 블록의 언어 자리에 'mermaid'를 적으면 그 안의 내용이 그림으로 그려진다.
Mermaid는 텍스트로 도표를 기술하는 표기법의 이름이다.

```mermaid
flowchart LR
    A[시작] --> B{조건}
    B -->|참| C[처리]
    B -->|거짓| D[종료]

```mermaid
flowchart LR
    A[시작] --> B{조건}
    B -->|참| C[처리]
    B -->|거짓| D[종료]

그림 파일을 따로 만들지 않아도 되고 텍스트라서 수정이 쉽다는 것이 장점이다.
변경 이력도 줄 단위로 남는다. (GitHub 다이어그램 지원 공지, 2026년 8월 확인)

수식

수학 식을 넣을 수 있다. LaTeX(레이텍, 수식을 글자로 적는 표기법) 문법으로 쓰면 식의 모양으로 그려진다.
문장 안에 넣을 때는 달러 기호로 감싼다.
화면 비율은 $16:9$ 이고 대각선 길이는 $\sqrt{16^2 + 9^2}$ 이다.

화면 비율은 $16:9$ 이고 대각선 길이는 $\sqrt{16^2 + 9^2}$ 입니다.

한 줄을 통째로 쓸 때는 달러 기호 2개로 감싸거나, 코드 블록의 언어 자리에 'math' 를 적는다.

$$v = \sqrt{v_x^2 + v_y^2 + v_z^2}$$

$$v = \sqrt{v_x^2 + v_y^2 + v_z^2}$$

```math
v = \sqrt{v_x^2 + v_y^2 + v_z^2}

자주 쓰는 표기는 다음과 같다.  
쓸 수 있는 표기는 GitHub와 Obsidian이 함께 사용하는  
MathJax(수식 표시 엔진)가 정한 것을 따르므로, 더 필요하면 MathJax 문서에서 찾는다.


| 표기            | 뜻          |
| ------------- | ---------- |
| `x^2`         | 위첨자. x의 제곱 |
| `x_1`         | 아래첨자. x 1  |
| `\sqrt{x}`    | 제곱근        |
| `\frac{a}{b}` | 분수         |


<mark> 첨자에 두 글자 이상이 들어가면 중괄호로 묶는다.</mark>  
`x^10`은 x의 1제곱 뒤에 0이 붙은 것이 되고, `x^{10}`이라야 10제곱이 된다.

**마크다운 문법과 겹치는 문자가 든 식**은 달러 기호 안쪽에 백틱을 덧댄 형태로 쓴다.  
백틱 안은 마크다운이 코드로 보고 건드리지 않으므로 식이 그대로 전달된다.

$`|v| = \sqrt{v_x^2 + v_y^2 + v_z^2}`$

```markdown
$`|v| = \sqrt{v_x^2 + v_y^2 + v_z^2}`$

달러 기호를 글자로 쓸 때는 자리에 따라 방법이 다르다.
한 줄 안에 달러 기호가 두 개 나오면 그 사이가 식으로 해석될 수 있어, 가격을 적을 때 자주 겪는다.

수식은 표준 마크다운이 아니므로 지원하지 않는 환경에서는 달러 기호와 원문이 그대로 보인다.
어디서든 읽혀야 하는 문서라면 식을 글로 풀어 쓰거나 그림으로 넣는 편이 안전하다.
코드 블록에 math를 적는 형태는 지원하지 않는 환경에서도 평범한 코드 블록으로 표시되므로 문서가 덜 흐트러진다.

사용 예시

작업 현황을 공유하는 이슈 본문에 작업 목록을 쓴다.

## 이번 스프린트 작업

- [x] 플레이어 이동 구현
- [x] 장애물 생성 로직
- [ ] 점수 계산
- [ ] 게임 오버 처리

문서에 주의 사항을 넣을 때 알림 상자를 쓴다.

> [!WARNING]
> 이 스크립트는 씬에 하나만 존재해야 합니다.
> 두 개 이상이면 입력이 중복 처리됩니다.

구조나 흐름을 설명할 때 다이어그램을 쓴다.

## 게임 상태 전환

```mermaid
stateDiagram-v2
    [*] --> Title
    Title --> Playing
    Playing --> Paused
    Paused --> Playing
    Playing --> GameOver
    GameOver --> Title

계산식을 설명할 때 수식을 씁니다.

```markdown
## 이동 처리

두 지점 사이를 비율 $t$ 로 나눈 위치를 구한다.

```math
p = a + (b - a)t

$t$ 가 0이면 a, 1이면 b가 된다.

---

### 1-11렌더러에 따른 차이

#### 개념

같은 ' .md ' 파일이라도 ==어떤 프로그램으로 여느냐에 따라 결과가 달라진다.==  
표준에 있는 문법은 어디서나 같게 보이지만, 확장 문법은 그 확장을 지원하는 곳에서만 동작한다.

이 차이는 두 환경을 오가며 문서를 쓸 때 드러난다.  
Obsidian에서 정리한 내용을 GitHub에 올렸더니 일부가 글자 그대로 보이거나,  
반대로 GitHub에서 쓴 문서를 Obsidian에서 열었더니 다르게 보이는 식이다.

#### 문법 형식

##### Obsidian에서만 되는 문법

```markdown
[[다른 노트]]
[[다른 노트|표시할 글자]]
![[이미지.png]]
==하이라이트==

위키링크와 임베드는 Obsidian 전용이다.
Obsidian은 볼트 안의 파일 이름만으로 연결할 수 있어 편리하지만,
그 문서를 GitHub에 올리면 링크가 아니라 대괄호가 붙은 글자로 보인다.

문서 안의 제목으로 이동하는 링크도 표기가 다르다.
8장에서 다룬 [글자](#제목) 형식이 GitHub 방식이고,
Obsidian은 [[#제목]] 형태의 위키링크로도 같은 이동을 처리한다.
두 환경에서 모두 동작해야 한다면 GitHub 방식으로 쓴다.

두 환경 모두에서 동작해야 하는 문서라면 표준 링크 문법을 쓴다.

[다른 문서](other-document.md)
![이미지 설명](images/screenshot.png)

비슷하지만 다른 문법

인용문에 표시를 넣어 상자를 만드는 문법은 양쪽 모두에 있다. 형태도 비슷하다.

> [!NOTE]
> GitHub의 알림 상자입니다.

> [!note]
> Obsidian의 콜아웃입니다.

Obsidian에서는 이 기능을 콜아웃(callout, 인용문을 색과 아이콘이 붙은 상자로 표시하는 기능)이라고 부른다.
형태는 같아 보이지만 서로 다른 기능이다. 지원하는 종류가 다르다.

GitHub에 올릴 문서에 > [!bug]를 쓰면 상자가 되지 않고 그냥 인용문으로 보인다.

환경별 지원 정리

아래 두 화면은 같은 .md 파일을 GitHub과 Obsidian에서 각각 연 것이다.
위 표의 차이가 실제로 어떻게 드러나는지 비교할 수 있다.

사용 예시

두 환경 모두에서 문제없이 보여야 하는 문서는 아래 기준으로 쓴다.

• 링크와 이미지는 표준 문법으로 쓴다. [[ ]]를 쓰지 않는다.
• 강조는 **와 *로 한다. ==를 쓰지 않는다.
• 표·작업 목록·취소선은 써도 된다. 양쪽 모두 지원한다.
• 알림 상자를 쓴다면 GitHub이 지원하는 다섯 종류 안에서 고른다.

Obsidian에서만 볼 문서라면 제약 없이 쓴다. 개인 노트에서는 위키링크가 훨씬 편하다.

## 오늘 배운 것

- [[조건문]]에서 `switch` 사용법 정리
- ==복습 필요== 항목 표시

![[화면_캡처.png]]

GitHub에 올릴 README나 기술 문서라면 표준 문법으로 쓴다.

# Dodge Game

![플레이 화면](docs/images/gameplay.png)

Unity로 만든 회피 게임입니다.

## 진행 상황

- [x] 플레이어 이동
- [ ] 점수 표시

> [!NOTE]
> Unity 6.3 이상에서 동작을 확인했습니다.

자세한 설계는 [설계 문서](docs/design.md)를 참고합니다.