마크다운 문법 정리

이 사이트의 글은 모두 마크다운(Markdown) 문법으로 작성되어 렌더링 된 글들이다. 이와 관련하여 마크다운 문법(syntax)을 정리해 본다. 다만 모든 문법을 정리하기엔 내용이 너무 길어질 수 있기에 개인적으로 자주 쓰는 것들 위주로 정리한다.

제목

마크다운에서는 구조적 글을 쓸 때 각 항목의 제목을 달 수 있는 문법으로 여러 방식이 제공된다.

대제목
======

대제목
------

# 대제목
## 중제목
### 소제목
#### 제목 4
##### 제목 5

이 중 #을 이용한 제목 문법은 차례대로 HTML의 h1 태그부터 h5 태그와 매칭된다고 볼 수 있다. 물론 여기서 끝이 아니라 더 깊이도 들어갈 수 있을 것 같다. 다만 개인적으로는 소제목 단위 이후로는 쓸 일이 없었다.

텍스트 스타일

링크

• [Google](https://google.com) = Google📎

이 외에로 파일의 절대 경로나 상대 경로도 사용할 수 있다.

이미지

• ![Alt Text](https://foo.bar/image/path.jpg)

링크 문법과 거의 비슷하지만 제일 앞에 느낌표(!)가 붙으면 이미지 문법이 된다. 'Alt Text'로 표시한 부분은 이미지를 설명하기 위한 문구로 img 태그의 alt 속성의 값으로 들어가며 대체로(?) 화면에 표시되도록 렌더링 되지는 않지만 접근성을 높이기 위해서는 적어주는 편이 좋다.

인용

> 인용된 메시지

이 마크다운 문서는 아래와 같이 렌더링 된다.

인용된 메시지

인용은 별도의 블럭 처럼 사용할 수 있다.

> ## 인용된 메시지
>
> 꺽쇠를 사용하면 인용 기능을 사용할 수 있습니다.
>
>> 인용 안에 인용을 넣을 수도 있습니다.
>
> 문단으로 나눌 수도 있습니다.<br/>
> 줄 나눔은 `br` 태그를 쓰거나 줄바꿈할 라인 끝에 공백 문자를 2개 이상 남기면 됩니다.

위 마크다운 문서는 아래와 같이 렌더링 된다.

인용된 메시지

꺽쇠를 사용하면 인용 기능을 사용할 수 있습니다.

문단으로 나눌 수도 있습니다.
줄바꿈은 br 태그를 쓰거나 줄바꿈할 라인 끝에 공백 문자를 2개 이상 남기면 됩니다.

멀티 라인 코드

일반적인 코드 샘플을 적기 위해서 두 가지 문법이 제공된다. 아래와 같이 하나는 역따옴표 3개(```)로 둘러싸거나 혹은 지렁이 3개(~~~)로 둘러쌀 수 있다.

~~~
multi 
  line 
    code
~~~

```
multi 
  line 
    code
```

위 두 마크다운 문서는 모두 아래와 같이 렌더링 된다.

multi 
  line 
    code

테이블

테이블은 일종의 확장 개념이긴 하지만 그래도 종종 쓰이는 것 같으므로 정리한다. 대충 아래와 같은 형식으로 쓰면 표가 작성된다.

| Head 1 | Head 2 | Head 3 |
|--------|--------|--------|
| Body 1 | Body 2 | Body 3 |
| Body a | Body b | Body c |

위 코드의 경우 아래와 같이 렌더링 된다.

크기나 줄의 갯수 등은 딱히 상관은 없지만 딱 맞춰 써야 보기엔 편하긴 하다. 참고로 Doom Emacs에서 markdown을 사용하도록 하면 탭(Tab) 키 한 방으로 테이블의 크기가 정렬되서 편하다.

좀 더 특수한 속성으로 제목줄과 내용줄 사이의 항목에 콜론(:)을 이용해 정렬(alignment)을 적용할 수도 있다.

| Head 1           | Head 2           |           Head 3 |
|:-----------------|------------------|-----------------:|
| Body 1 Text      | Body 2 Text Long | Body 3 Text Long |
| Body 1 Long Text | Body 2 Text      |      Body 3 Text |

위 문법의 경우 아래와 같이 렌더링 된다.

위 처럼 제목과 본문 표 사이의 구분줄을 표시해 놓은 부분에 콜론(:)이 왼쪽에 있으면 좌측 정렬, 우측에 있으면 우측 정렬이 된다. 기본은 가운데 정렬이다.

다만 정렬 부분은 사용하는 변환기나 패키지에 따라서 다를 수 있다.

HTML 태그

HTML 태그를 넣고 싶다면 고민할 필요 없이 그냥 넣으면 된다. 충돌하는 문법이 있어서 약간의 제약이 있을 수 있지만 대체로 그대로 렌더링 되는 편이다.

<div style="width: 100%; border: 1px solid #777">
HTML 태그는 **쓰는 대로 거의 다 그대로** 출력됩니다.
</div>

위 마크다운 문서는 아래와 같이 렌더링 된다.

보다시피 HTML 태그 블럭 내부의 마크다운 문법은 무시되는 것을 볼 수 있다.

특이사항으로 Python-Markdown의 경우 명확하게 태그가 닫기지 않으면 XML 파싱 관련 오류가 발생하므로 이런 부분은 주의하자.

팁: 역 따옴표를 코드 스타일로 표시하기

여러 방법을 찾아봤지만 개인적으로 사용하는 Python-Markdown 패키지에선 아래 방식만이 제대로 표시되는 것을 확인했다.

`` ` ``
``display ` back tick``

역따옴표 2개를 붙여서 좌우로 둘러싸면 inline code와 동일하게 쓸 수 있지만 여기서 '역따옴표 두개'와 '역따옴표' 사이만 붙여쓰지 않으면 '역따옴표'를 표시할 수 있었다.

다만 역따옴표만 표시할 때는 좌우에 여백(스페이스)이 들어가게 되는 것은 어쩔 수 없는 것 같다.

관련된 글들

• 파이썬으로 마크다운 문서를 HTML로 변환하기
• Python-Markdown의 테이블 렌더링 지원