마크다운 기초

개요

Quarto는 Pandoc을 기반으로 하며, 문서 기본 구문으로 Pandoc 변형 마크다운을 사용합니다. Pandoc 마크다운은 John Gruber의 Markdown 구문을 확장·수정한 버전입니다.

마크다운은 작성하기 쉽고, 무엇보다 읽기 쉬운 단순 텍스트 형식입니다.

마크다운 문서는 태그나 서식 지시가 난무하는 것처럼 보이지 않아야 하며, 평범한 텍스트 그대로 배포할 수 있어야 합니다. – John Gruber

이 문서는 가장 자주 쓰이는 마크다운 구문을 예시로 보여 줍니다. 보다 자세한 내용은 Pandoc 마크다운 전체 문서를 참고하세요.

텍스트 서식

마크다운	출력
`이탤릭, 볼드, *볼드 이탤릭*`	이탤릭, 볼드, *볼드 이탤릭*
`superscript^2^ / subscript~2~`	superscript² / subscript₂
`~~strikethrough~~`	~~취소선~~
`verbatim code`	`verbatim code`

제목

마크다운	출력
`# Heading 1`	Heading 1
`## Heading 2`	Heading 2
`### Heading 3`	Heading 3
`#### Heading 4`	Heading 4
`##### Heading 5`	Heading 5
`###### Heading 6`	Heading 6

링크와 이미지

마크다운	출력
`<https://quarto.org>`	https://quarto.org
`[Quarto](https://quarto.org)`	Quarto
`![Caption](elephant.png)`	Caption
`[![Caption](elephant.png)](https://quarto.org)`
`[![Caption](elephant.png "An elephant")](https://quarto.org)`	\|
`[![](elephant.png){fig-alt="Alt text"}](https://quarto.org)`	\|

마크다운	출력
`* unordered list + sub-item 1 + sub-item 2 - sub-sub-item 1`	unordered list sub-item 1 sub-item 2 sub-sub-item 1
`* item 2 Continued (indent 4 spaces)`	item 2 Continued (indent 4 spaces)
`1. ordered list 2. item 2 i) sub-item 1 A. sub-sub-item 1`	ordered list item 2 sub-item 1 sub-sub-item 1
1. ordered list 2. item 2 ```python print("Hello, World!") ``` A. sub-sub-item 1	ordered list item 2 `print("Hello, World!")` sub-sub-item 1
`- [ ] Task 1 - [x] Task 2`	Task 1 Task 2
`(@) A list whose numbering continues after (@) an interruption`	A list whose numbering continues after an interruption
`::: {} 1. A list ::: ::: {} 1. Followed by another list :::`	A list Followed by another list
`term : definition`	term definition

다른 많은 렌더러(Jupyter, GitHub 등)와 달리, Quarto에서는 목록 위에 빈 줄이 있어야 목록으로 인식됩니다. 빈 줄이 없으면 전체가 일반 텍스트 한 줄로 표시됩니다.

각주

Pandoc은 다음 구문으로 각주 번호와 서식을 지원합니다.

Here is a footnote reference,[^1] and another.[^longnote]

[^1]: 여기에 각주가 있습니다.

[^longnote]: 여러 블록으로 구성된 각주입니다.

    Subsequent paragraphs are indented to show that they
belong to the previous footnote.

        { some.code }

    The whole paragraph can be indented, or just the first
    line.  In this way, multi-paragraph footnotes work like
    multi-paragraph list items.

This paragraph won't be part of the note, because it
isn't indented.

위 구문은 다음과 같이 렌더링됩니다.

Here is a footnote reference,¹ and another.²

This paragraph won’t be part of the note, because it isn’t indented.

한 문단짜리 각주는 다음과 같이 인라인으로 작성할 수도 있습니다.

Here is an inline note.^[Inlines notes are easier to write,
since you don't have to pick an identifier and move down to
type the note.]

이 구문은 다음과 같이 렌더링됩니다.

Here is an inline note.³

각주 ID는 고유해야 합니다

^1 같은 각주 식별자는 문서 안에서 고유해야 합니다. Quarto 책에서 PDF·DOCX·EPUB 같은 형식을 만들면 장을 하나의 문서로 합치므로 각주 식별자는 장 전체에서 고유해야 합니다.

위 예시로 생성된 각주는 페이지 맨 아래 예제 각주 섹션에 포함됩니다. 자세한 내용은 Pandoc Footnotes를 참고하세요.

표

마크다운

| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |

출력

Right	Left	Default	Center
12	12	12	12
123	123	123	123
1	1	1	1

자세한 내용은 표 문서를 참고하세요.

소스 코드

```로 코드 블록을 감쌉니다.

```
code
```

언어를 지정해 구문 강조를 적용합니다.

```python
1 + 1
```

Pandoc은 140개 이상의 언어의 구문 강조를 지원합니다. 사용하는 언어가 없다면 default 언어를 사용해 비슷한 스타일을 적용할 수 있습니다.

```default
code
```

위 예시의 축약형과 동일한 긴 형식은 괄호 안에 클래스(예: .python)를 지정하는 방식입니다.

```{.python}
1 + 1
```

긴 형식을 사용하면 Div와 비슷하게 속성을 추가할 수 있습니다. 예를 들어 줄 번호나 코드 파일 이름은 이 구문을 사용합니다.

```{.python filename="run.py"}
code
```

HTML을 생성한다면 코드 블록 출력에 사용할 수 있는 옵션이 매우 다양합니다. 자세한 내용은 HTML 코드 문서를 참고하세요.

원시 콘텐츠

raw attribute를 사용하면 Quarto가 파싱하지 않고 원시 콘텐츠를 직접 포함할 수 있습니다. 원시 블록은 ```{= + 형식 + }로 시작합니다. 예를 들어 원시 HTML 블록은 다음과 같습니다.

```{=html}
<iframe src="https://quarto.org/" width="500" height="400"></iframe>
```

PDF 출력에는 원시 LaTeX 블록을 사용합니다.

```{=latex}
\renewcommand*{\labelitemi}{\textgreater}
```

Typst 형식을 사용하는 경우 다음과 같이 Typst 구문을 포함할 수도 있습니다.

```{=typst} 
#set text(fill: red)
This text is red.
```

원시 콘텐츠는 인라인으로도 포함할 수 있습니다.

 Here's some raw inline HTML: `<a>html</a>`{=html}

수식

인라인 수식은 $, 디스플레이 수식은 $$로 감쌉니다.

마크다운 출력

마크다운	출력
`inline math: $E = mc^{2}$`	inline math: \(E=mc^{2}\)
`display math: $$E = mc^{2}$$`	display math: \[E = mc^{2}\]

inline math: $E = mc^{2}$

inline math: $E=mc^{2}$

display math:

$$E = mc^{2}$$

display math:

\[E = mc^{2}\]

사용자 정의 TeX 매크로가 필요하면 .hidden 블록 안에 $$로 감싼 코드를 넣습니다.

::: {.hidden}
$$
 \def\RR{{\bf R}}
 \def\bold#1{{\bf #1}}
$$
:::

HTML 수식(기본값인 MathJax 사용)에서는 \def, \newcommand, \renewcommand, \newenvironment, \renewenvironment, \let 등 명령으로 원하는 매크로와 환경을 정의할 수 있습니다.

다이어그램

Quarto는 Mermaid, Graphviz 다이어그램을 기본 지원합니다. 이를 통해 순서도, 순차 다이어그램, 상태 다이어그램, 간트 차트 등을 간단한 텍스트 구문으로 작성할 수 있습니다.

다음은 Mermaid로 만든 순서도를 임베드한 예시입니다.

```{mermaid}
flowchart LR
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}
  C --> D[Result one]
  C --> E[Result two]
```

flowchart LR
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}
  C --> D[Result one]
  C --> E[Result two]

자세한 내용은 다이어그램 문서를 참고하세요.

비디오

{{< video >}} 숏코드를 사용해 비디오를 포함할 수 있습니다. 예를 들어 YouTube 비디오는 다음과 같이 임베드합니다.

{{< video https://www.youtube.com/embed/wo9vZccmqwc >}}

비디오는 MPEG 같은 파일을 참조할 수도 있고, YouTube·Vimeo·Brightcove에 배포된 영상 링크를 사용할 수도 있습니다. 자세한 내용은 비디오 문서를 참고하세요.

페이지 분할

pagebreak 숏코드를 사용하면 문서에 네이티브 페이지 분할을 삽입할 수 있습니다(LaTeX의 \newpage, Word의 페이지 분할, HTML의 page-break-after: always CSS 등).

page 1

{{< pagebreak >}}

page 2

네이티브 페이지 분할은 HTML, LaTeX, ConTeXt, MS Word, Open Document, ePub에서 지원됩니다(그 외 포맷에는 폼 피드 문자 \f가 삽입됨).

Div와 Span

Div와 Span을 사용하면 콘텐츠 영역에 클래스, 속성, 식별자를 지정할 수 있습니다. “Div”, “Span”이라는 용어는 HTML에서 시작됐지만, 해당 구문은 Quarto 전반에 걸쳐 사용됩니다. 예를 들어 콜아웃 블록은 div 구문으로 지정하고, 소문자(capitalization) 변형은 span 구문으로 지정하며, HTML 외의 여러 형식에서도 작동합니다. CSS나 필터를 Div와 Span과 함께 사용해 Quarto에서 제공하는 기능 외의 스타일·동작을 추가할 수도 있습니다.

Div

다음과 같이 div(:::)로 콘텐츠 영역에 border 클래스를 추가할 수 있습니다.

::: {.border}
This content can be styled with a border
:::

HTML로 렌더링되면 다음과 같이 변환됩니다.

<div class="border">
  <p>This content can be styled with a border</p>
</div>

Div는 최소 3개의 연속된 콜론과 속성으로 시작합니다. 속성 뒤에 추가 콜론을 붙일 수도 있습니다. Div는 다시 3개 이상 콜론으로 된 닫기 줄로 끝납니다. Div 앞뒤에는 빈 줄이 있어야 하며, 중첩할 수도 있습니다. 예시는 다음과 같습니다.

::::: {#special .sidebar}

::: {.warning}
Here is a warning.
:::

More content.
:::::

HTML 출력은 다음과 같습니다.

<div id="special" class="sidebar">
  <div class="warning">
    <p>Here is a warning.</p>
  </div>
  <p>More content.</p>
</div>

속성이 없는 펜스는 항상 닫기 펜스로 처리됩니다. 코드 블록과 달리 닫기 펜스의 콜론 개수는 열기 펜스와 일치할 필요가 없지만, 가독성을 위해 중첩 Div의 길이를 다르게 두면 좋습니다.

Span

링크를 시작할 때처럼 대괄호로 감싼 인라인 구문 뒤에 속성을 붙이면 Span으로 처리됩니다.

[This is *some text*]{.class key="val"}

HTML 출력은 다음과 같습니다.

<span class="class" data-key="val">
  This is <em>some text</em>
</span>

속성 순서

Pandoc의 div와 span에는 ID, 클래스, 다수의 key-value 속성을 조합해 지정할 수 있습니다. 인식되려면 ID → 클래스 → key-value 순서를 지켜야 합니다. 생략은 가능하지만 순서는 유지해야 합니다. 예를 들면 다음은 유효합니다.

[This is good]{#id .class key1="val1" key2="val2"}

반면 다음은 Pandoc이 인식하지 못합니다.

[This does *not* work!]{.class key="val" #id}

이 순서 제한은 div와 span 모두에 적용됩니다. 자세한 내용은 Pandoc Div와 Span 문서를 참고하세요.

콜아웃 블록

마크다운

:::{.callout-note}
Note that there are five types of callouts, including: 
`note`, `tip`, `warning`, `caution`, and `important`.
:::

출력

Note

Note that there are five types of callouts, including note, tip, warning, caution, and important.

자세한 내용은 콜아웃 블록 문서를 참고하세요.

기타 블록

마크다운	출력
`> Blockquote`	Blockquote
`::: {.classname} Div :::`	Div
`\| Line Block \| Spaces and newlines \| are preserved`	Line Block Spaces and newlines are preserved

기타 Span

텍스트를 스몰캡으로 만들거나, 밑줄·형광펜 효과를 추가하려면 span에 .smallcaps, .underline, .mark 클래스를 각각 사용합니다.

마크다운	출력
`[This text is smallcaps]{.smallcaps}`	This text is smallcaps
`[This text is underlined]{.underline}`	This text is underlined
`[This text is highlighted]{.mark}`	This text is highlighted

지원 형식에서만 작동

이 클래스는 Pandoc에서 직접 지원합니다. 모든 출력 형식이 모든 클래스를 지원하지는 않습니다. 특히 .mark는 현재 format: pptx에서 지원되지 않습니다.

특수 문자

마크다운	출력
`endash: --`	endash: –
`emdash: ---`	emdash: —

키보드 단축키

kbd 숏코드는 문서에서 키보드 단축키를 표현할 때 사용합니다.

모든 운영체제에 동일한 단축키를 표시하려면 위치 인자를 사용합니다: {{< kbd Ctrl-C >}}
운영체제별로 다른 단축키가 있다면 키워드 인자 win, mac, linux를 사용합니다: {{< kbd mac=Shift-Command-O win=Shift-Control-O linux=Shift-Ctrl-L >}}

JavaScript 기반 포맷에서는 Quarto가 운영체제를 감지해 해당 단축키만 보여 줍니다. 인쇄/정적 포맷에서는 모든 운영체제의 단축키 정보를 함께 출력합니다.

예를 들어 아래 마크다운을 작성하면:

To print, press {{< kbd Shift-Ctrl-P >}}. To open an existing new project, press {{< kbd mac=Shift-Command-O win=Shift-Control-O linux=Shift-Ctrl-L >}}.

다음처럼 렌더링됩니다:

To print, press Shift-Ctrl-P. To open an existing new project, press .

예제 각주

여기에 각주가 있습니다.↩︎
여러 블록으로 구성된 각주입니다.

이어지는 문단은 들여쓰기를 적용해 이전 각주에 속함을 표시합니다.
```
{ some.code }
```
문단 전체를 들여쓸 수도 있고 첫 줄만 들여쓸 수도 있습니다. 이렇게 하면 여러 문단으로 된 각주가 여러 문단 목록 항목처럼 동작합니다.↩︎
인라인 각주는 식별자를 고르거나 아래로 내려가 각주를 입력할 필요가 없어 작성이 더 쉽습니다.↩︎

개요

텍스트 서식

제목

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

Heading 6

링크와 이미지

목록

각주

표

마크다운

출력

소스 코드

원시 콘텐츠

수식

다이어그램

비디오

페이지 분할

Div와 Span

Div

Span

속성 순서

콜아웃 블록

마크다운

출력

기타 블록

기타 Span

특수 문자

키보드 단축키

예제 각주