Skip to content

마크다운 #
Find similar titles

소개 #

이 문서는 마크다운(Markdown) 문법 소개의 번역문입니다. WIKI를 작성하시는 데 도움이 되기를 바랍니다. 다만 본문은 이해하기 어렵거나 위키를 작성하는 데 필요하지 않은 부분이 종종 있습니다. 블록 요소부터 읽는다면 원하는 정보를 빨리 찾을 수 있습니다.

편집 문법 아티클은 위키를 작성하는 데 필요한 최소한의 배경지식을 다루고 있으니 비교적 간단한 사항을 참고하실 때 도움이 될 것으로 생각하며 해당 아티클이 포함하지 않는 내용에 대해서 이 문서를 참고하시면 좋겠습니다.

개요(Overview) #

철학 #

마크다운(Markdown) 개발의 의도는 '읽기 쉬운' 그리고 '쓰기 쉬운' 언어를 만드는 데 있다.

그러나 무엇보다 가장 중요한 것은 가독성이며, 마크다운으로 작성된 문서는 그 자체로 보통의 글과 같이 보여아 한다. 그말인즉, 겉보기에 태그나 다른 문법적 지시사항처럼 보이지 않는 것을 목적으로 한다는 것이다. 비록, 마크다운의 구문은 이미 나와있는 텍스트를 HTML으로 변환하는 필터들(Setext, atx, Textile, reStructuredText, Grutatext, and EtText 등)의 영향을 받기는 하였으나, 마크다운의 문법에 가장 큰 영감이 된 것은 보통 문장(plain text)인 이메일의 형식이다.

그리하여 마크다운의 문법요소는 모두 문장 부호로만 이루어지게 되었다. 문장 부호의 선정에 있어 가장 신경썼던 점은, 겉보기에도 그것이 의미하는 바를 알 수 있게 하는 것이었다. 예를 들어 별표(*, asterisk)로 둘러싸인 단어, 즉 *강조*와 같은 경우는 실제로 강조된 것처럼 보인다. 마크다운의 목차 역시 실제로 목차와 같이 보인다. 인용구 역시 이메일을 사용할 때 한번쯤은 봤던 형식이다.

내부 HTML #

마크다운은 웹에서 사용되는 것만을 목적으로 하여 만들어졌다.

마크다운은 HTML을 대체하기 위한 것이 아닐 뿐 아니라 HTML과 비슷하게 만들려고 한 결과물도 아니며, HTML요소의 아주 작은 일부에만 대응하는 초소형 문법이다. 본래의 생각 역시 HTML을 손쉽게 입력하는 문법을 만들겠다는 것도 아니었다. 내가 보기에, 이미 HTML은 아주 입력하기 쉬운 언어이다. 마크다운의 철학이란, '쉽게 읽고 쓰이는' 언어라는 것, 그리고 HTML은 배포를 위한 규격이라는 점에서, 마크다운의 문법이란 평문을 쉽게 웹으로 실어나를 수 있게 하는 데 그 중요성이 있다.

마크다운이 다루지 못한 HTML 태그가 있다면 간단하게 HTML로 적어주면 된다. 문서 중간까지 마크다운을 쓰다가 HTML로 변환한다는 지시를 해 줄 필요가 없다. 바로 태그를 사용하면 끝이다.

HTML요소 사용에 일부 제한이 있는 것도 있다. 예를 들자면 <div>, <table>, <pre>, <p> 등인데, 그것들은 빈 줄을 둘러싸는 콘텐츠로부터 분리되어야 하며, 시작과 끝 태그 앞에는 공백 문자(스페이스, 탭)이 없어야 한다. 마크다운은 꽤나 똑똑해서, HTML요소 주위에 쓸 데 없는 <p> 태그를 붙이지 않는다.

아래는 예시로, 만약 표를 집어넣고 싶다면 아래와 같이 하면 된다.

This is a regular paragraph.

<table>
    <tr>
        <td>Foo</td>
    </tr>
</table>

This is another regular paragraph.

특수한 문자의 자동 이스케이핑 #


블록 요소 #

문단과 줄바꿈 #

문단은 하나 또는 여러개의 일련된 문장으로, 하나 이상의 빈 줄로 나뉜다. (빈 줄이란 겉보기에 빈 줄처럼 보이는 줄, 즉 탭이나 스페이스 등의 공백문자를 포함해도 상관없다.) 일반 문장은 스페이스나 탭으로 들여쓰기를 하면 안된다.

'하나 이상의 일련된 문장'이라는 것은 줄바꿈(엔터)가 되지 않은 글이라는 말과 같다. 즉, 다른 변환기들처럼 문장의 끝에 <br />태그를 넣을 필요가 없다는 것이다.

만약 <br /> 태그를 넣고 싶을 때에는, 문장의 끝에서 두 번 이상을 띄우고 줄바꿈을 하라.

<br />을 자동 생성하는 것보다 미묘하게 귀찮지만, 마크다운에서 모든 줄바꿈이 <br />을 의미하지 않는다고 생각하면 간단하다. 마크다운이 사용하는 이메일 스타일의 인용구와 여러 문장의 목차 요소는 아주 잘 작동하며, 보기에도 편하다.

머릿말 #

마크다운은 두 가지 스타일의 머릿말, setext와 atx를 지원한다.

setext 스타일의 머릿말은 등호(=)를 밑줄치듯 사용한다. 그보다 하위의 머릿말을 입력하려면 대쉬(dash, –)를 사용하면 된다.

This is an H1
=============

This is an H2
–––––––––––––

등호나 대쉬는 몇개나 입력하든지 상관없다.

atx 스타일의 머릿말은 머릿말의 위계에 따라 한 개 이상 여섯 개 이하의 샵(#)기호를 사용한다.

# This is an H1

## This is an H2

###### This is an H6

원한다면 atx 스타일의 머릿말은 끝을 '닫을' 수도 있다. 이건 순전히 문서를 예뻐 보이게 하는 용도인데, 마음에 드는 쪽을 선택하면 된다. 닫을 때 들어가는 샵 기호는, 머릿말을 열기 위해 맨 앞에 썼던 샵 기호의 수와 맞출 필요가 없다. (머릿말의 위계는 앞쪽의 샵 기호의 수가 정한다.)

# This is an H1 #

## This is an H2 ##

### This is an H3 #######

인용구 #

마크다운의 인용구는 이메일 스타일의 > 기호를 사용한다. 이메일을 보낼 때 상대방의 메시지를 인용하는 데 익숙하다면 마크다운의 인용구를 이미 아는 것이나 마찬가지다. 줄 끝에 엔터를 넣으면서 모든 줄 처음에 > 기호를 넣는 것이 가장 보기 좋다.

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
> 
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
> id sem consectetuer libero luctus adipiscing.

줄을 바꾸는 것이나 모든 줄의 처음에 > 기호를 넣는 것이 귀찮은 사람은 이렇게 입력하면 된다.

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

인용구는 중첩될 수도 있다(인용구 안에 인용구가 들어가는 식으로). 인용구 안에 추가적으로 > 기호를 넣으면 된다.

> This is the first level of quoting.
>
> > This is nested blockquote.
>
> Back to the first level.

인용구 안에는 마크다운의 다른 요소들이 들어갈 수도 있다. 예를 들면 머릿말이나, 목록, 또는 코드 블록 정도이다.

> ## This is a header.
> 
> 1.   This is the first list item.
> 2.   This is the second list item.
> 
> Here's some example code:
> 
>     return shell_exec("echo $input | $markdown_script");

괜찮은 편집기를 사용한다면 이메일 스타일의 인용구를 만들기란 쉬운 일이다. 예를 들면 BBEdit은 지정된 선택 범위의 인용구 위계를 Text 메뉴에서 지정할 수 있다.

목록 #

마크다운은 순서 있는 목록(ordered lists, numbered lists)과 순서 없는 목록(unordered lists, bulleted lists)을 지원한다.

순서 없는 목록은 별표, 덧셈기호, 그리고 하이픈을 기호로 사용한다. 기호는 모두 구분 없이 사용 가능하다.

*   Red
*   Green
*   Blue

아래는 위의 예제와 상동하다.

+   Red
+   Green
+   Blue

이것도 마찬가지.

-   Red
-   Green
-   Blue

한편으로, 순서 있는 목록은 숫자에 점을 찍어 표현한다.

1.  Bird
2.  McHale
3.  Parish

중요한 건 어떤 순서를 적든지간에 결과물인 HTML에는 아무 영향이 없다는 것이다. 위의 마크다운이 의미하는 HTML 코드는 아래와 같다.

<ol>
<li>Bird</li>
<li>McHale</li>
<li>Parish</li>
</ol>

마크다운에서 숫자를 아래와 같이 넣었을 경우에도,

1.  Bird
1.  McHale
1.  Parish

또는 이렇게 넣는다고 해도,

3. Bird
1. McHale
8. Parish

완전히 똑같은 HTML 결과물이 나오게 된다. 그러니 문서를 편집하는 단계에서 목록에 정확한 숫자를 넣고 싶다면 입력한 후 나오는 목록 번호까지 고려하여 입력해야 한다. 귀찮다면 그렇게 하지 않아도 아무 상관 없다.

그러나, 숫자를 매기는게 귀찮더라도 목록을 시작하는 숫자는 1로 하기를 바란다. 앞으로 마크다운은 임의의 숫자에 대해 순서 있는 목록(ordered lists)를 지원할지도 모른다.

목록을 나타내는 기호는 통상 왼쪽 끝에서 시작하지만, 세 개의 스페이스까지 들여쓰기가 가능하다. 목록 기호 뒤에는 하나 이상의 스페이스나 탭을 넣어야 한다.

문서가 예쁘게 보이기 위해서는, 이렇게 들여쓰기하면 될 것이다.

*   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
    Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
    viverra nec, fringilla in, laoreet vitae, risus.
*   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
    Suspendisse id sem consectetuer libero luctus adipiscing.

위와 같이 하기가 귀찮다면:

*   Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
*   Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

만약, 목록의 항목들이 빈 줄로 나뉘어 있다면 마크다운은 그 항목들을 HTML의 <p> 태그로 감싸게 된다. 예를 들면 아래의 예제는,

*   Bird
*   Magic

아래와 같이 바뀐다.

<ul>
<li>Bird</li>
<li>Magic</li>
</ul>

하지만 이것은,

*   Bird

*   Magic

이렇게 바뀌게 된다.

<ul>
<li><p>Bird</p></li>
<li><p>Magic</p></li>
</ul>

한편, 목록의 항목은 여러 문단을 포함할 수도 있다. 뒤따르는 문장은 스페이스 네 번이나 탭 한번으로 들여쓰기가 되어야 한다.

1.  This is a list item with two paragraphs. Lorem ipsum dolor
    sit amet, consectetuer adipiscing elit. Aliquam hendrerit
    mi posuere lectus.

    Vestibulum enim wisi, viverra nec, fringilla in, laoreet
    vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
    sit amet velit.

2.  Suspendisse id sem consectetuer libero luctus adipiscing.

모든 줄을 들여쓰기하는 위의 예제가 보기엔 좋지만, 이런 경우 역시 귀찮을 경우 아래와 같이 할 수 있다.

*   This is a list item with two paragraphs.

    This is the second paragraph in the list item. You're
only required to indent the first line. Lorem ipsum dolor
sit amet, consectetuer adipiscing elit.

*   Another item in the same list.

목록의 항목 안에 인용구를 넣고 싶으면 인용구의 > 기호를 들여쓰기하라.

*   A list item with a blockquote:

    > This is a blockquote
    > inside a list item.

목록의 항목 안에 코드를 넣고 싶다면 코드 블록은 두 번 들여쓰기가 되어야 한다. 즉 스페이스를 여덟 번 치거나 탭을 두 번 입력하면 된다.

*   A list item with a code block:

        <code goes here>

의도치 않게 목록으로 처리되는 문장을 입력하는 경우도 있을 것이다.

1986. What a great season.

즉 한 줄의 시작을 연도로 하게 되는 경우인데, 이를 피하기 위해서는 연도 뒤에 백슬래시()를 입력하여 이스케이핑한다.

1986\. What a great season.

코드 블록 #

(주 : 생략)

수평선 #

수평선을 입력하기 위해서는, 해당 위치에 세개 이상의 하이픈, 별표 또는 밑줄을 입력하면 된다. 별표와 하이픈의 경우에 각각의 문자 사이에 공백을 넣는 것도 가능하다. 아래의 예제들은 모두, 같은 수평선을 입력하기 위한 것이다.

* * *

***

*****

- - -

---------------------------------------

스팬 요소 #

링크 #

마크다운은 inline과 reference, 두 가지 스타일의 링크를 지원한다. (주; inline은 링크가 나올 때마다 그때그때 향할 주소를 넣는 것이고, reference는 링크를 따로 정의한 후 그 링크의 이름을 본문에서 참조하는 방식이다.)

두 스타일은 모두 링크 텍스트를 [대괄호]로 둘러싸는 식이다.

inline 링크를 만들기 위해서는 대괄호 다음에 바로 괄호를 입력한다. 괄호 안에는 링크가 향하는 URL를 넣으면 된다. 원한다면 URL 뒤에 해당 웹페이지의 제목을 큰따옴표로 감싸 넣을 수 있다.

This is [an example](http://example.com/ "Title") inline link.

[This link](http://example.net/) has no title attribute.

위의 결과는 아래와 같다.

<p>This is <a href="http://example.com/" title="Title">
an example</a> inline link.</p>

<p><a href="http://example.net/">This link</a> has no
title attribute.</p>

만약 같은 서버상의 목적지를 항하게 하려면 관계 주소(relative paths)를 사용할 수 있다.

See my [About](/about/) page for details.

reference 스타일의 링크는 처음의 대괄호 다음에 다른 대괄호가 오는 식이다. 두 번째 대괄호 안에는 해당 링크를 구분할 수 있는 이름(id)을 넣는다.

This is [an example][id] reference-style link.

괄호 사이를 띄우는 것도 허용된다.

This is [an example] [id] reference-style link.

그리하여, 문서의 어디에서나 링크의 이름(id)은 이와 같이 정의한다.

[id]: http://example.com/  "Optional Title Here"

그말인즉,

  • 대괄호 안에는 링크의 이름이 들어간다.
  • 그 뒤로 콜론(:)을 넣는다.
  • 그 뒤로 하나 이상의 스페이스(또는 탭)을 넣는다.
  • 그 뒤로 해당 링크의 URL을 넣는다.
  • 필요하다면, 그 뒤에 링크에 제목을 달아놓을 수 있다. 제목은 큰따옴표나 작은따옴표, 또는 괄호 안에 집어넣으면 된다.

따라서 아래의 링크는 모두 동일한 것이다.

[foo]: http://example.com/  "Optional Title Here"

[foo]: http://example.com/  'Optional Title Here'

[foo]: http://example.com/  (Optional Title Here)

링크 URL은 > 괄호로 둘러쌀 수 있다.

[id]: <http://example.com/>  "Optional Title Here"

링크의 제목을 다음 줄에 넣을 수도 있다. URL이 길어 제목을 넣을 공간이 부족할 때 유용하며, 들여쓰기를 사용할 수 있다.

[id]: http://example.com/longish/path/to/resource/here
    "Optional Title Here"

링크에 대한 위와 같은 정의들은 마크다운 문서에서만 존재하며 HTML로 변환될 때 사라진다.

정의된 링크의 이름은 문자, 숫자, 스페이스, 문장 부호를 포함할 수 있다. 또한, 대소문자의 구분이 없다. 그 예로, 아래의 경우는

[link text][a]
[link text][A]

상동한 것이다.

정의된 링크를 참조하는 바로가기에서, 링크가 걸릴 텍스트와 정의된 링크의 이름(id)이 같다면 이름을 생략하는 것이 가능하다. 대괄호를 그냥 빈 상태로 내버려두면 된다. 예를 들어 "Google"이라는 단어를 google.com에 링크하고 싶다면,

[Google][]

그리고 링크 정의는 아래와 같이 하면 된다.

[Google]: http://google.com/

링크 이름이 스페이스를 포함하는 것이 가능하므로, 링크 바로가기는 두 개 이상의 단어로 구성될 수 있다.

Visit [Daring Fireball][] for more information.

그리고 위에 대한 링크 정의는,

[Daring Fireball]: http://daringfireball.net/

링크 정의는 마크다운 문서의 어느곳이나 들어갈 수 있다. 나는 보통 링크가 쓰인 문단의 바로 아래에 넣는 것을 좋아하지만, 미주처럼 문서의 맨 마지막에 모아 놓는 것도 괜찮을 것이다.

아래는 reference 링크가 실제로 어떻게 쓰일 수 있는지 보여준다.

I get 10 times more traffic from [Google] [1] than from
[Yahoo] [2] or [MSN] [3].

  [1]: http://google.com/        "Google"
  [2]: http://search.yahoo.com/  "Yahoo Search"
  [3]: http://search.msn.com/    "MSN Search"

그리고 아래는 링크 바로가기와 링크의 이름을 같게 한 경우이다.

I get 10 times more traffic from [Google][] than from
[Yahoo][] or [MSN][].

  [google]: http://google.com/        "Google"
  [yahoo]:  http://search.yahoo.com/  "Yahoo Search"
  [msn]:    http://search.msn.com/    "MSN Search"

위의 두 예제는 아래와 같은 HTML로 변환된다.

<p>I get 10 times more traffic from <a href="http://google.com/"
title="Google">Google</a> than from
<a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>

아래의 inline 스타일의 링크와 비교해 보자. 아래의 문장은 위의 예시들과 같은 결과로 변환된다.

I get 10 times more traffic from [Google](http://google.com/ "Google")
than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
[MSN](http://search.msn.com/ "MSN Search").

reference 스타일 링크의 포인트는 그것이 쓰기에 쉽다는 것이 아니다. reference 링크를 사용한다면 문서가 훨씬 읽기 쉬워진다는 것이 중요하다. 위의 예제들을 비교해 보자. reference 스타일의 링크를 사용한 문장은 81 글자밖에 되지 않는다. 반면 inline 스타일의 경우 176자, HTML 문서의 경우 234자이다.

마크다운의 reference 스타일의 링크를 사용한다면, 작성된 문서와 출력 결과로 브라우저 상에 그려지는 문서는 서로 아주 비슷해질 것이다. 문장 안에서 링크 정의를 위한 메타데이터를 빼냄으로써, 문장의 흐름을 방해하지 않고 링크를 넣는 것이 가능해졌다.

강조 #

마크다운에서, 별표(%#42;)와 및줄(_)로 감싼 부분은 강조처리된다. * 기호 하나 또는 _ 기호 하나로 감싸진 부분은 HTML상에서 <em> 태그가 붙고, 두개로 감싸진 경우에는 <strong>이 된다. 예를 들면 아래와 같다.

*single asterisks*

_single underscores_

**double asterisks**

__double underscores__

위의 예는 아래와 같이 된다.

<em>single asterisks</em>

<em>single underscores</em>

<strong>double asterisks</strong>

<strong>double underscores</strong>

어떤 스타일이든 원하는 대로 고르자. 다만 여는 문자와 닫는 문자가 같아야 한다는 규칙은 지켜야 한다.

강조는 단어의 중간에 들어가도 된다.

un*frigging*believable

만약, * 기호나 _ 기호를 스페이스로 둘러싸게 된다면 실제 별표와 및줄 기호가 나타난다.

이미지 #

인정하건데, 이미지를 '자연스러운' 문법으로 보통 문장 속에 집어넣기란 꽤나 어려운 일이다.

마크다운은 두 가지 스타일, 즉 inline과 reference 스타일을 사용하여 이미지 구문을 링크와 비슷하게 보이도록 했다.

inline 이미지 구문은 아래와 같다.

![Alt text](/path/to/img.jpg)

![Alt text](/path/to/img.jpg "Optional title")

즉,

  • 느낌표: !;
  • 그 뒤에 alt 속성에 들어갈 텍스트를 대괄호로 감싸 넣는다. (주; alt 속성이란 이미지를 대체할 때 보이는 텍스트, HTML에서 사용됨)
  • 그 뒤에 해당 이미지의 URL을 포함하는 괄호가 따른다. 괄호 안에는 작은따옴표나 큰따옴표로 감싸진 제목이 들어가는 것이 가능하다.

reference 스타일의 이미지 구문은 아래와 같다.

![Alt text][id]

"id"부분은 참조하는 이미지의 이름이다. 이미지 참조를 정의하는 것은 링크를 정의하는 것과 동일하다.

[id]: url/to/image  "Optional title attribute"

위와 같이, 마크다운에는 이미지의 크기를 정하는 문법이 없다. 만약 이미지의 크기를 꼭 정해야 하겠다면 보통 HTML의 <img>태그를 사용하자.

기타 사항 #

자동 링크 #

마크다운은 URL이나 이메일 주소에 대한 바로가기 링크를 지원한다. URL이나 이메일 주소를 꺾쇠 괄호(<, >)로 감싸면 된다. 링크가 향하는 주소와 링크가 걸리는 텍스트를 같게 하고 싶을 때 이런 식으로 사용할 수 있다.

<http://example.com/>

위의 예제는 아래와 같은 HTML을 만들어낸다.

<a href="http://example.com/">http://example.com/</a>

이메일에 대한 자동 링크도 비슷하다. 단지, 마크다운은 이메일 주소를 무작위로 암호화하는데 그것은 이메일을 수집하는 스팸봇이 해당 링크가 이메일 주소인지를 인식하지 못하도록 하기 위함이다.

<address@example.com>

위의 문장은 아래와 같이 변한다.

<a href="&#x6D;&#x61;i&#x6C;&#x74;&#x6F;:&#x61;&#x64;&#x64;&#x72;&#x65;
&#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;
&#109;">&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61;
&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a>

브라우저 상에서는 "에 대한 링크가 된다.

(이러한 entity-encoding 수법에 사실상 많은 이메일 수집기가 속아넘어간다고 해도 역시 전부를 피할 수는 없다. 없는 것보다는 나을 뿐. 이러한 방법으로 공개된 주소 역시 결국에는 스팸 메일을 받게 될 것이다.)

백슬래시 이스케이프 #

마크다운은 마크다운의 문법에서 쓰이는 기호들을 실제로 문서에 입력하기 위해 백슬래시 이스케이프를 지원한다. 예를 들면 강조하기 위한 것이 아니라 진짜 단어를 별표로 둘러싸고 싶은 거라면 별표 앞에 백슬래시를 넣으면 된다.

\*literal asterisks\*

아래의 문자들은 백슬래시 이스케이프가 가능한 것들이다.

\   backslash
`   backtick
*   asterisk
_   underscore
{}  curly braces
[]  square brackets
()  parentheses
#   hash mark
+   plus sign
-   minus sign (hyphen)
.   dot
!   exclamation mark

Incoming Links #

Related Articles #

Suggested Pages #

0.0.1_20140628_0