260923 정리 - 마크다운

마크다운

1. 마크다운이란

1-1 마크다운 개념

텍스트에 몇 가지 기호를 섞어 문서의 구조를 표현하는 표기 방식

• 설계 목표: 가능한 한 읽기 쉽게 만드는것
• 태그나 서식 지시자로 표시된것처럼 보이지 않아야함
• 일반 텍스트 그대로 출판 가능해야함
• 코드와 함께 텍스트 파일로 보관할 수 있고, 변경 이력을 줄 단위로 비교할 수 있기 때문

1-2 문법 형식

마크다운 문서는 확장자가 .md인 텍스트 파일입니다 (별도 프로그램 없어도됨)

같은 방식으로 사용

• 숫자키 1번 옆 ~ ` 써져있는 키보드에서 세번 누르고 markdown 입력후 엔터하면 마크다운 창 생성
• 이 파일을 마크다운을 이해하는 프로그램(GitHub, Obsidian 등)에서 열면 기호가 실제 서식으로 바뀌어 보임
• 이 변환 과정을 렌더링(rendering)이라고 하고, 변환하는 프로그램을 렌더러(renderer)라고함

1-3 사용 예

이 파일을 GitHub 저장소의 최상위 폴더에 README.md라는 이름으로 두면, 저장소 첫 화면 아래쪽에 서식이 적용된 상태로 표시됩니다.

# Dodge Game

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

## 실행 방법

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

## 조작

- 이동: 방향키
- 재시작: R

Dodge Game

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

실행 방법

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

조작

• 이동: 방향키
• 재시작: R

2.제목

2.1 개념

제목은 문서를 단계로 나누는 표시
글자를 크게 만드는 기능이 아니라 마크다운 문서의 뼈대를 만드는 표시

2.2 문법 형식

줄 맨 앞에 #을 놓고 공백을 하나 넣은 뒤 제목을 씁니다. #의 개수가 단계를 뜻하며 1개부터 6개까지 쓸 수 있습니다.

# 1단계 제목
## 2단계 제목
### 3단계 제목
#### 4단계 제목
##### 5단계 제목
###### 6단계 제목

1단계 제목

2단계 제목

3단계 제목

4단계 제목

5단계 제목

6단계 제목

• # 뒤의 공백은 생략할 수 없습니다.
  • 공백을 빼먹으면 제목이 되지 않고 환경에 따라 다르지만 #제목 이라는 글자가 그대로 나옵니다.

2.3 사용 예

제목은 단계를 건너뛰지 않고 순서대로 씁니다.

• 왼쪽처럼 쓰면 오른쪽처럼 나옴
• 1단계 제목은 문서 전체의 제목이므로 문서당 하나만 두는 것이 일반적

3. 문단과 줄바꿈

3.1 개념

GitHub 기준으로 줄을 그냥 바꾸면 줄이 바뀌지 않습니다.

• 빈 줄 없이 이어진 줄들은 한 문단의 내용으로 취급하기 때문입니다.
• 줄을 나누는 방법은 두 가지로 구분됩니다.
  • 문단을 나누는 것과
  • 문단 안에서 줄만 바꾸는 것입니다.

3.2 문법 형식

문단 나누기

빈 줄 하나를 넣습니다.

첫 번째 문단입니다.

두 번째 문단입니다.

문단 안에서 줄바꿈

줄 끝에 공백 두 개를 넣습니다.··
이 줄은 위 줄 바로 아래에 붙습니다.

줄 끝에 백슬래시를 넣습니다.\
이 줄도 위 줄 바로 아래에 붙습니다.

HTML 태그를 씁니다.<br>
이 줄도 마찬가지입니다.

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

세 가지 동작 정리

3.3 사용 예

주소나 목록처럼 줄마다 간격 없이 이어져야 하는 내용에 줄바꿈을 씁니다.

연락처는 아래와 같습니다.

담당자: 홍길동\
소속: 개발팀\
내선: 1234

문단이 바뀌는 자리에는 빈 줄을 씁니다.

이 게임은 회피를 중심으로 설계되었습니다. 플레이어는 공격 수단을 갖지 않고
오직 이동으로만 생존합니다.

난이도는 시간이 지날수록 올라갑니다. 장애물의 수와 속도가 함께 증가합니다.

4. 강조

4.1 개념

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

마크다운은 별표(*)나 밑줄(_)로 감싸는 방식을 씁니다.

• 하나로 감싸면 기울임, 두 개로 감싸면 굵게 표시됩니다.

4.2 문법 형식

*기울임* 또는 _기울임_

**굵게** 또는 __굵게__

***굵은 기울임*** 또는 ___굵은 기울임___

• 밑줄은 앞뒤가 글자로 둘러싸인 자리에서는 강조로 인식되지 않습니다. 별표는 그런 제약이 없습니다.
• 이 규칙 때문에 밑줄이 들어간 이름을 쓸 때 의도치 않은 강조가 생기지 않음
  • 따라서 별표를 기본으로 쓰는 것을 권장합니다

기호를 글자 그대로 쓰기

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

• 이 방법은 강조 기호뿐 아니라 #, -, [, ``` 등에도 쓸 수 있습니다.
• 이스케이프(escape)는 기호를 문법이 아니라 글자로 취급하게 만드는 처리를 뜻함

4.3 사용 예

강조는 문서에서 실제로 중요한 곳에만 씁니다.

여러 곳을 강조하면 어느 것도 눈에 띄지 않습니다.

## 주의

빌드 전에 **반드시** `Scenes/Main` 씬이 Build Settings에 등록되어 있는지
확인합니다. 등록되지 않은 씬은 빌드 결과물에 포함되지 않습니다.

5. 목록

5.1 개념

목록은 여러 항목을 나열하는 표시입니다.

순서가 의미를 갖는지에 따라 두 종류로 나뉩니다.

• 순서 없는 목록 - 항목 사이에 순서가 없습니다. 준비물이나 특징을 나열할 때 씁니다.
• 순서 있는 목록 - 항목의 순서가 의미를 갖습니다. 절차나 단계를 적을 때 씁니다.

순서 있는 목록

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

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

• 실제로 반영되는 것은 첫 번째 숫자뿐입니다.
• 나머지는 무시되고 순서대로 다시 매겨집니다.

중첩

목록 안에 목록을 넣으려면 들여쓰기를 합니다.

들여쓰기 칸 수는 정해진 숫자가 아니라 상위 항목의 내용이 시작되는 위치에 맞춥니다.

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

• - 는 기호 하나에 공백 하나이므로 내용이 3번째 칸에서 시작합니다.
• 따라서 하위 항목은 2칸 들여씁니다.

순서 있는 목록은 마커가 더 길어집니다.

1. 은 3글자이므로 하위 항목을 3칸 들여씀

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

목록 안에 다른 내용 넣기

목록 항목 아래에 문단이나 코드 블록을 넣으려면 같은 규칙으로 들여씁니다.

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

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

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

git --version

• 들여쓰기가 부족하면 목록이 그 자리에서 끊기고 이후 항목이 새 목록으로 시작됨

5.3 사용 예

설치 절차처럼 순서가 있는 것과

조작 방법처럼 순서가 없는 것을 구분해 씀

## 실행 방법

1. 저장소를 내려받습니다.
2. Unity Hub에서 Add를 눌러 폴더를 지정합니다.
3. `Scenes/Main` 씬을 엽니다.
4. 재생 버튼을 누릅니다.

## 조작

- 이동: 방향키
- 대시: Shift
- 일시정지: Esc
- 재시작: R

6. 코드

6.1 개념

문서 안에 코드를 넣을 때는 일반 문장과 구분되게 표시합니다.

구분하지 않으면 두 가지 문제가 생깁니다.

• 첫째로 코드 안의 기호가 마크다운 문법으로 해석됩니다.
  *ptr처럼 별표로 시작하는 코드가 목록 항목으로 인식되거나, [index]의 대괄호가 링크로 처리되는 식
• 둘째로 읽는 사람이 어디까지가 코드인지 알기 어려움

코드 표시에는 두 가지가 있습니다.

• 문장 중간에 짧게 넣는 인라인 코드,
• 여러 줄을 통째로 넣는 코드 블록

6.2 문법 형식

인라인 코드

백틱(```)으로 감쌉니다. 백틱은 키보드에서 숫자 1 왼쪽, 물결표(~)와 같은 자리에 있습니다.

코드 블록

백틱 세 개로 시작하고 세 개로 닫습니다. 이 표시를 펜스(fence)라고 부릅니다.

using UnityEngine;

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

언어 지정

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

```csharp
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);
    }
}

```csharp

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);
    }
}

• C#을 입력하니 그 문법에 맞게 변화하는 모습

• C# 코드에는 csharp을 씁니다. 언어를 지정하지 않으면 색 없이 고정폭 글꼴로만 표시됩니다.

  언어	지정자
  C#	csharp
  JSON	json
  마크다운	markdown
  명령어	bash

백틱 개수

코드 블록 안에 백틱 세 개짜리 코드 블록을 넣어야 할 때가 있습니다.

이때는 바깥 펜스의 백틱을 안쪽보다 많게 합니다

• 여는 펜스가 백틱 3개일 때 안쪽 내용에 백틱 3개짜리 줄이 나오면,
  그 줄이 닫는 펜스 조건을 만족하므로 거기서 코드 블록이 끝나 버립니다.
• 바깥을 4개로 하면 안쪽의 3개는 닫는 조건을 만족하지 않아 내용으로 남습니다.

6.3 사용 예

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

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

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

## 이동 처리

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

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

7. 인용문과 수평선

7.1 개념

인용문은 다른 곳에서 가져온 문장이나 특별히 구분해 보일 내용을 표시

렌더링하면 왼쪽에 세로선이 붙고 안쪽으로 들여쓰인 형태로 표시됩니다.

• 수평선은 문서에 가로선을 그어 내용을 크게 나눕니다.

7.2 문법 형식

인용문

줄 앞에 >를 놓고 공백을 넣습니다.

인용문입니다.

첫 번째 줄입니다.

두 번째 줄입니다.

• 여러 줄을 인용하려면 각 줄 앞에 >를 붙입니다

바깥 인용입니다.

안쪽 인용입니다.

• >를 여러 개 겹치면 인용 안의 인용이 됨

준비물은 다음과 같습니다.

• Unity Hub
• Git

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

수평선

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

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

• 수평선을 쓸 때는 위에 빈 줄을 넣습니다.

• 주의할 점
• 파일 맨 첫 줄부터 ---로 시작해 다시 ---로 닫는 구간은 여러 도구에서 문서의 속성을 적는 영역으로 해석
• 이 영역을 프런트매터(front matter)라고 부름
• 본문이 아니라 문서 정보로 취급됨

7.3 사용 예

출처가 있는 문장을 옮길 때 인용문을 쓰고 아래에 출처를 답니다.

닫는 코드 펜스는 여는 펜스와 같거나 더 길어야 한다. 출처: CommonMark 명세

• 문서의 큰 단락이 바뀌는 자리에 수평선을 넣습니다.

설치

설치 절차를 설명합니다.

설치

설치 절차를 설명합니다.

실행

실행 방법을 설명합니다.

• 제목만으로 구분이 충분하면 수평선을 넣지 않습니다.

8. 링크와 이미지

8.1 개념

링크는 다른 문서나 웹 주소로 이동하는 표시이고

이미지는 그림을 문서 안에 표시하는 것입니다

이미지 문법이 링크 문법 앞에 느낌표를 붙인 모양

8.2 문법 형식

인라인 링크

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

Unity 공식 문서

Unity 공식 문서

참조 링크

같은 주소를 여러 번 쓰거나 주소가 길어 문장 읽기를 방해할 때 씁니다.

본문에는 이름만 두고 주소는 문서 아래쪽에 모읍니다.

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

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

자동 링크

주소를 그대로 쓰면 GitHub은 자동으로 링크로 만듭니다.

다만 이것은 GFM의 확장 기능이고

표준 방식은 꺾쇠로 감싸는 것입니다.

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

문서 내 이동

같은 문서 안의 제목으로 이동하는 링크를 만들 수 있습니다.

주소 자리에 #과 제목을 소문자로 바꾸고 공백을 -로 바꾼 값을 씁니다.

설치 절차로 이동

같은 저장소 안의 다른 파일로 연결할 때는

전체 주소 대신 상대 경로를 씀

기여 방법

설계 문서

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

이미지

링크 문법 앞에 느낌표를 붙입니다.

대괄호 안에는 이미지가 표시되지 않을 때 대신 보일 설명을 씁니다.

8.3 사용 예

README에서 문서와 이미지를 함께 씀

Dodge Game

Unity로 만든 회피 게임입니다. 자세한 설계는 설계 문서를 참고합니다.

참고 자료

• Unity 공식 문서
• C# 언어 참조

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

9.표

9.1 개념

표는 항목을 행과 열로 정리해 보이는 것

여러 대상을 같은 기준으로 비교할 때 문장보다 읽기 쉬움

9.2 문법 형식

파이프(|)로 칸을 나눔

첫 줄이 열 이름이고

둘째 줄은 -로 이뤄진 구분행이며

셋째 줄부터 내용

• | <- 파이프 이건 역슬래쉬 키에 있는 작대기

• 구분행은 생략할 수 없음
• 이 줄이 있어야 렌더러가 표로 인식
• -의 개수는 몇 개든 상관없으므로 하나씩만 써도 됨
• 주의!! 표 작성할때 Shit + Enter해야 표가 유지됨!!!

정렬

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

왼쪽 - 왼쪽

가운데 - 양쪽에

오른쪽 - 오른쪽

칸 안에 파이프 넣기

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

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

라고 쓰면

이렇게 됨

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

원본 정렬

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

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

조작

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

난이도 설정

• 표에 긴 문장을 넣지 않음
• 칸이 좁아 줄바꿈이 많아지면 표의 장점인 한눈에 비교하기가 사라짐
• 설명이 길어지면 목록이나 문단으로 씀

10. 확장 문법

10.1 개념

표준 마크다운에 없지만

GitHub에서 쓸 수 있는 문법들

10.2 문법 형식

작업 목록

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

렌더링하면 각 항목 앞에 체크 상자가 붙고

[x]로 표시한 항목은 체크된 상태로 나타남

• 플레이어 이동 구현

• 장애물 생성

• 점수 표시

• 사운드 추가

• 플레이어 이동 구현

• 장애물 생성

• 점수 표시

• 사운드 추가

• 대괄호 안의 공백을 빼먹으면 동작하지 않음
  • []`는 체크 상자가 되지 않고 대괄호가 그대로 보임

취소선

물결표 두 개로 감싸기

취소된 내용

취소된 내용

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

각주

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

Unity는 C#을 사용합니다¹.

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

알림 상자

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

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

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

• GitHub이 지원하는 종류는 다섯 가지입니다.

• 많이쓰면 시선끄는 효과가 사라져 한두개로 제한할것을 권함

다이어그램

코드 블록의 언어 자리에 mermaid를 적으면 그 안의 내용이 그림으로 그려짐

Mermaid는 텍스트로 도표를 기술하는 표기법의 이름

• 그림 파일을 따로 만들지 않아도 되고 텍스트라서 수정이 쉽다는 것이 장점
• 변경 이력도 줄 단위로 남음

수식

수학 식을 넣을 수 있음

• LaTeX(레이텍, 수식을 글자로 적는 표기법) 문법으로 쓰면 식의 모양으로 그려짐
• 문장 안에 넣을 때는 달러 기호로 감쌈

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

• 자주 쓰는 표기는 다음과 같습니다.

• 첨자에 두 글자 이상이 들어가면 중괄호로 묶음
  • x^10은 x의 1제곱 뒤에 0이 붙은 것이 되고
  • x^{10}이라야 10제곱이 됨
• 마크다운 문법과 겹치는 문자가 든 식은
  달러 기호 안쪽에 백틱을 덧댄 형태로 씁니다.
  • 백틱 안은 마크다운이 코드로 보고 건드리지 않으므로 식이 그대로 전달됨

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

• 달러 기호를 글자로 쓸 때는 자리에 따라 방법이 다름

• 수식은 표준 마크다운이 아니므로 지원하지 않는 환경에서는 달러 기호와 원문이 그대로 보임

10.3 사용 예

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

이번 스프린트 작업

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

이번 스프린트 작업

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

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

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

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

게임 상태 전환

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

  이동 처리

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

  mathCopy

  p = a + (b - a)t
  
  

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

11. 렌더러에 따른 차이

11.1 개념

같은 .md 파일이라도 어떤 프로그램으로 여느냐에 따라 결과가 달라집니다

표준에 있는 문법은 어디서나 같게 보이지만 -> 확장문법은 지원하는데에서만 쓰임

11.2 문법 형식

Obsidian에서만 되는 문법

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

비슷하지만 다른 문법

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

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

• 인용문에 표시를 넣어 상자를 만드는 문법은 양쪽 모두에 있으며 형태도 비슷함
• Obsidian에서는 이 기능을 콜아웃이라 부름

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

환경별 지원 정리

11.3 사용 예

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

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