마크다운 정리

마크다운은 일반 텍스트에 몇 가지 기호를 섞어 구조를 표현하는 표기 방식이다.

제목 표기

• 제목은 줄 맨 앞에 '#'을 놓고 공백을 하나 넣은 뒤 제목을 쓴다. #의 개수가 단계를 뜻하며 6개까지 사용이 가능하다.

# 게임명
## 설치
### 사전 준비
### 설치 절차
## 실행
## 문제 해결

문단과 줄바꿈

• 깃 허브 기준 줄을 그냥 바꾸면 줄이 바뀌지 않는다.

• 줄을 나누는 방법은 두 가지로 구분되며 문단을 나누는 것과 문단 안에서 줄만 바꾸는 것이다.

  방법	표기	특징
  공백 두 개	줄 끝에 공백 2칸	가장 널리 쓰이지만 눈에 보이지 않습니다
  백슬래시	줄 끝에 \	눈에 보여서 실수를 줄일 수 있습니다
  HTML 태그	줄 끝에 <br>	마크다운 문법이 아니므로 HTML 태그를 허용하는 곳에서만 동작합니다

• 공백 두 개 방식은 편집기에서 보이지 않기 때문에 문제가 생깁니다. 다른 사람이 문서를 고치다가 자동 정리 기능으로 줄 끝 공백을 지워 버리면 줄바꿈이 사라지고, 왜 사라졌는지 알아내기 어렵습니다. 백슬래시 방식은 이런 문제가 없습니다.

[ 문단 나누기 ]

첫 번째 문단입니다.

두 번째 문단입니다.

[ 문단 안에서 줄바꿈 ]

줄 끝에 공백 두개를 넣습니다.--
( -- 는 공백을 표현함 )

줄 끝에 백슬래시를 넣습니다.\

HTML 태그를 씁니다.<br>

강조

• 강조는 문장 안의 일부를 굵게 하거나 기울여 표시하는 것이다.

*기울임* or _기울임_
**굵게** or __굵게__
***굵은 기울임*** or ___굵은 기울임___

별표와 밑줄의 차이

• 둘 다 같은 결과를 내지만 단어 중간에서는 동작이 다르다.

• 해당 규칙 때문에 밑줄이 들어간 이름을 쓸 때 의도치 않은 강조가 생기지 않는다.
  'player_max_hp' 같은 변수 이름을 그냥 써도 안전한 것이 이 덕분이다.
  때문에 별표를 기본으로 쓰는 것을 권장한다. (어느 자리에서든 같게 동작하기 때문)

기호를 글자 그대로 쓰기

• 강조 기호를 문자 그대로 보이려면 앞에 백슬래시를 붙인다.

목록

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

순서 없는 목록

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

- 첫째 항목
- 둘째 항목
- 셋째 항목

순서 있는 목록

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

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

• 실제로 반영되는 것은 첫 번째 숫자뿐이며 나머지는 무시되고 순서대로 다시 매겨진다.
• 중간에 항목을 끼워 넣어도 번호를 다시 매길 필요가 없다.
• 시작 번호를 바꾸고 싶다면 첫 항목의 숫자만 변경한다. '5.'로 시작하면 5, 6, 7로 이어진다.

중첩

• 목록 안에 목록을 넣으려면 들여쓰기를 한다.
  들여쓰기 칸수는 정해진 숫자가 아니라 상위 항목의 내용이 시작되는 위치에 맞춘다.
• 순서 없는 목록 - 는 기호 하나에 공백 하나이므로 내용이 3번째 칸에서 시작한다. 따라서 하위 항목은 2칸 들여쓴다.

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

• 순서 있는 목록은 마커가 더 길어집니다. 1. 은 3글자이므로 하위 항목을 3칸 들여씁니다.

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

목록 안에 다른 내용 넣기

• 목록 항목 아래에 문단이나 코드 블록을 넣으려면 같은 규칙으로 들여쓴다.
• 들여쓰기가 부족하면 목록이 그 자리에서 끊기고 이후 항목이 새 목록으로 시작된다.

1. 프로젝트를 내려받습니다.

   내려받은 뒤 압축을 풀어 둡니다.

2. 아래 명령으로 확인합니다.

git --version

코드

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

1. 코드 안의 기호가 마크다운 문법으로 해석된다.

*ptr처럼 별표로 시작하는 코드가 목록 항목으로 인식되거나, [index] 의 대괄호가 링크로 처리되는 식이다. 2. 읽는 사람이 어디까지가 코드인지 알기 어렵다.

• 코드 표시는 두 가지가 있으며 문장 중간에 짧게 넣는 인라인 코드, 여러 줄을통째로 넣는 코드 블록이 있다.

[  인라인 코드 ]
백틱(`` ` ``)으로 감싼다.

설정 파일은 `config.json`이며 `Assets` 폴더 아래에 둡니다.

[ 코드 블록 ]
백틱(```) 세 개로 시작하고 세 개로 단는다. [이 표시를 펜스(fence)라고 부른다.]

언어 지정

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

using System;

Console.Write("구역 순번:");
int num = int.Parse(Console.ReadLine());
Console.Write("좌석 번호:");
int seatNumber = int.Parse(Console.ReadLine());

char seat = (char)('A' + num - 1);

Console.WriteLine($"좌석: {seat}-{seatNumber}");

백틱 개수

• 코드 블록 안에 백틱 세 개짜리 코드 블록을 넣어야 할 때가 있다.
  이때 바깥 펜스의 백틱을 안쪽보다 많게 적어야한다.

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

[ 사용 예시 ]
문장 안에서 파일명·메서드명·설정값을 언급할 때 인라인 코드를 씁니다.

```markdown
`Assets/Scripts` 폴더에 `PlayerController.cs`파일을 만들고, `MonoBehaviour`를 상속받는 클래스를 선업합니다.

여러 줄짜리 코드는 블록으로 넣고 언어를 지정합니다.

 이동 처리

```markdown
 이동 처리

플레이어 이동은 아래와 같이 구현되어 있습니다.

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

명령어를 안내할 때도 코드 블록을 쓴다.

인용문

• 인용문은 다른 곳에서 가져온 문장이나 특별히 구분해 보일 내용을 표시한다.
  렌더링하면 왼쪽에 새로선이 붙고 안쪽으로 들여쓰인 형태로 표시된다.
• 줄 앞에 >를 놓고 공백을 넣습니다.

인용문입니다.

수평선

• -, *, _ 중 하나를 세 개 이상 이어서 한 줄에 씁니다.

• 세 기호 모두 같은 결과를 내지만 - 를 쓸 때는 주의가 필요합니다.
  바로 위 줄에 글자가 있으면 수평선이 아니라 2단계 제목의 밑줄로 해석됩니다.

  입력	결과
  빈 줄 다음에 ---	수평선
  글자 있는 줄 바로 다음에 ---	위 줄이 2단계 제목이 됩니다

• 수평선을 쓸 때는 위에 빈 줄을 넣습니다. 또 하나 주의할 점이 있습니다.
  파일 맨 첫 줄부터 ---로 시작해 다시 ---로 닫는 구간은 여러 도구에서 문서의 속성을 적는 영역으로 해석됩니다.
  이 영역을 프런트매터(front matter)라고 부르며, 본문이 아니라 문서 정보로 취급됩니다.
  표시 방식은 도구마다 다르므로 실제로 어떻게 보이는지는 사용하는 환경에서 확인합니다.

• 문서의 큰 단락이 바뀌는 자리에 수평선을 넣는다.
  단 제목만으로 구분이 충분하다면 수평선을 넣지 않는다.
  구분선이 많으면 오히려 문서가 잘게 끊어져 읽기 어려워진다.

링크와 이미지

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

[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/>

문서 내 이동

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

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

상대 경로

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

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

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

이미지

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

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

링크와 이미지 총 정리

게임 이름

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

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

참고 자료

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

표

• 표는 항목을 행과 열로 정리해 보이는 것이다.
  여러 대상을 같은 기준으로 비교할 때 문장보다 읽기 쉽다.
• 표는 표준 마크다운에 없고 Github가 확장으로 추가한 문법이며, 오늘날 대부분의 렌더러가 이 방식을 그대로 지원한다.

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

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

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

정렬

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

| 왼쪽 | 가운데 | 오른쪽 |
|:---|:---:|---:|
| 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|물리 연산|

• 두 입력의 결과는 같다. 다만 원본을 읽거나 고칠 일이 있으므로 어느 정도 맞춰 두는 편이 낫다.
• 표에 긴 문장을 넣지는 않는다. 칸이 좁아 줄 바꿈이 많아지면 표의 장점인 한눈에 비교하기가 사라진다.
  설명이 길어지면 목록이나 문단으로 쓰는 것이 좋다.

확장 문법

• 표준 마크다운에 없지만 Github에서 쓸 수 있는 문법들이 있다.

이 문법들은 어디에서나 동작한다고 가정할 수 없습니다. GitHub에서 잘 보이던 문서를 다른 곳에 옮겼을 때 깨진다면 이 장의 문법을 썼기 때문일 가능성이 높습니다.

한 가지 더 구분할 것이 있습니다. GFM에는 공식 명세 문서가 있는데, 그 문서에 실린 확장 목록과 GitHub이 실제로 렌더링하는 문법의 범위가 같지 않습니다. 명세 문서가 나온 뒤 GitHub이 추가한 기능들은 실제로 동작하지만 그 목록에는 없습니다.

구분	해당 문법
GFM 명세에 있는 확장	표, 작업 목록, 취소선, 맨 주소 자동 링크
명세 이후 GitHub이 추가	각주, 다이어그램, 알림 상자, 수식

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

문법 형식

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

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

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

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

GitHub의 이슈나 풀 리퀘스트(pull request, 변경 사항을 반영해 달라고 요청하는 기능) 본문에서는 화면에서 직접 눌러 체크할 수 있는 상자로 표시됩니다. (GitHub 공식 문서, 2026년 8월 확인)

취소선

• 물결표 두 개로 감싼다.

~~취소된 내용~~

• 예시 > 취소된 내용
  수정 이력을 남길 때가 더 이상 유효하지 않은 항목을 표시할 때 사용한다.

각주

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

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

[^1]: 과거에는 UnityScript와 Boo도 지원했으나 현재는 지원하지 않습니다.

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

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

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

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

알림 상자

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

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

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

• Github가 지원하는 알림 상자의 종류는 다섯 가지이다.

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

다이어그램

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

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

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