6  마크다운

AI 시대를 살아가는 우리에게, 만약 딱 하나의 텍스트 언어만 배울 수 있다면 무엇을 선택해야 할까? 답은 단연 마크다운(Markdown)이다. 마크다운은 단순히 문서 작성 도구를 넘어서, AI와 인간이 소통하는 공통 언어가 되었다. ChatGPT, Claude, GitHub Copilot… 모든 AI 도구들이 마크다운을 기본 언어로 채택한 이유가 있다. 바로 인간이 읽기 쉽고, 기계가 처리하기 쉬운 완벽한 중간 지점에 위치하기 때문이다.

프로그래머가 아니어도 마크다운을 배워야 하는 이유는 명확하다. 현대 지식 작업자라면 누구나 문서를 작성하고, 아이디어를 정리하고, 다른 사람과 협업한다. 모든 과정에서 마크다운은 가장 효율적이고 지속가능한 선택이다. 한번 마크다운으로 작성한 문서는 10년 후에도, 20년 후에도 그대로 읽을 수 있다. 워드 문서나 한글 파일이 버전 호환성 문제로 골치를 썩일 때, 마크다운은 여전히 모든 플랫폼에서 완벽하게 작동한다.

더 중요한 것은 마크다운이 사고 과정을 자연스럽게 구조화한다는 점이다. 제목(#), 강조(**), 목록(-), 링크([]()) 같은 간단한 문법은 사람의 논리적 사고를 그대로 반영한다. 복잡한 서식 설정에 시간을 낭비하는 대신, 순수하게 내용과 구조에만 집중할 수 있다. 이것이 바로 WYSIWYM(What You See Is What You Mean) 패러다임의 핵심이다.

마크다운은 마크다운(.md) 확장자를 갖는 파일형식으로, 아래아한글, MS 워드 같은 WYSIWYG(What You See Is What You Get) 편집기와 달리 WYSIWYM(What You See Is What You Mean) 패러다임을 따른다. 즉, 화면에 보이는 것은 글자 그대로 구조화된 텍스트이며, 서식은 렌더링 시점에 적용된다.

그림 6.1: 문서 작성 패러다임 진화

이러한 패러다임의 변화는 단순한 기술적 진보가 아니다. 인간이 생각을 표현하고 지식을 구조화하는 방식 자체 진화를 의미한다. AI 시대에 들어서면서 이제 WYAIWYM(What You Ask AI Is What You Mean)¹의 새로운 패러다임에 진입했다.

노트위지위그 vs 위지윔

위지윅(WYSIWYG: What You See Is What You Get)는 “보는 대로 얻는다”는 의미로, 사용자가 문서를 편집할 때 화면에 보이는 형태가 최종 출력물과 동일하게 나오는 편집 방식이다. 대다수 현대 워드 프로세서에서 위지위그 방식을 사용하고 있다. 사용자에게 직관적이고 쉽게 접근할 수 있는 인터페이스를 제공하기 때문이다.

그러나 위지위그 방식에도 단점은 있다. 마크다운, TeX 같은 텍스트 기반 편집 방식은 문서 호환성과 범용성을 위해 쓰이는 반면, 위지위그 저작방식은 호환성과 범용성을 다소 희생할 수 밖에 없다. 특히 복잡한 문서나 웹 페이지를 작성하는 경우, 코딩방식으로 전환하여 수작업으로 최적화를 시도하더라도 완벽한 해결이 어렵다. 예를 들어, 위지위그 편집기에서 문서를 작성하면 뒷단에 불필요한 코드나 태그가 자동으로 생성되어 문서 최적화를 방해하며, 시간이 지남에 따라 누적되어 호환성과 재현성에 심각한 문제를 야기한다.[^setup_quarto-2]

위지윔(WYSIWYM: What You See Is What You Mean)은 “당신이 보는 것은 당신이 뜻하는 것이다”라는 의미로, 위지위그(WYSIWYG) 방식의 한계를 극복하기 위해 나온 대안 편집 방식이다. 위지윔 방식에서는 사용자가 무엇을 의미하는지를 중점으로 두어, 본래의 코드 구조를 더 명확하게 알 수 있다. 코드 의미를 직접적으로 반영하여, 불필요한 요소 없이 효율적으로 문서를 작성할 수 있는 장점이 있다.

RStudio의 Visual 편집 기능은 위지윔 지향점을 잘 반영하고 있다. 사용자는 복잡한 코드나 태그 없이도 의미 있는 문서 구조를 쉽게 생성하고 관리할 수 있어 문서 최적화와 호환성을 높일 수 있으며, 더욱 높은 문서 저작 생산성을 달성할 수 있다.

오픈 소스 \(\LaTeX\) 편집기인 LyX는 위지윔 방식을 초기부터 채택하여 사용자에게 코드 본래 구조와 의미를 명확하게 파악할 수 있는 인터페이스를 제공했다. 이러한 접근법은 복잡한 수식이나 과학적인 문서를 작성할 때 특히 유용하며, \(\LaTeX\) 복잡성을 낮추면서도 강력한 기능을 최대한 활용할 수 함으로써 위지위그 한계를 극복했다는 평가를 받고 있다.

문서 컴파일	위지위그

6.1 마크다운 방언들

마크다운에는 여러 방언(dialect)이 존재한다. 주요 방언들을 살펴보자:

• CommonMark: 마크다운의 공식 표준 명세. 명확하고 일관된 규칙 제공
• GitHub Flavored Markdown (GFM): GitHub에서 사용하는 마크다운으로, 테이블, 작업 목록, 취소선 등 추가 기능 제공
  
• Quarto Markdown: Pandoc을 기반으로 하여 학술 문서에 특화된 확장 기능 제공 (수식, 인용, 그림 참조 등)

이 장에서는 CommonMark와 GFM에 공통으로 존재하는 핵심 구문을 중심으로 학습한다.

6.2 메타데이터

마크다운 문서에서 ‘저자’, ‘문서제목’ 등은 야믈(YAML) 헤더를 사용하여 메타데이터를 표현할 수 있다. YAML 은 “Yet Another Markup Language”를 축약한 두문어지만 중요하지는 않다. YAML 헤더는 다음과 같다.

---
title: "Quarto를 활용한 재현가능한 연구 보고서"
author: "김연구"
date: "2024년 8월 28일"
format:
  html:
    theme: cosmo
  pdf:
    documentclass: article
---

상기 YAML 헤더에는 문서의 제목, 저자, 작성일자 등의 메타데이터와 함께 출력 형식(format) 설정도 포함된다. Quarto에서는 하나의 문서를 다양한 형식(HTML, PDF, Word 등)으로 동시에 출력할 수 있다.

6.3 기본 구문

마크다운의 진정한 힘은 이러한 기능들이 모두 플레인 텍스트로 표현된다는 점이다. 특별한 소프트웨어나 복잡한 인터페이스 없이도, 텍스트 편집기만으로 구조적이고 의미 있는 문서를 작성할 수 있다. AI 시대에 이러한 특성이 더욱 빛을 발하는 이유는, 인간과 AI 모두가 쉽게 읽고 쓸 수 있는 형태이기 때문이다.

그림 6.2: 마크다운 전체 기능

그림 6.2 는 마크다운의 전체 기능을 한눈에 보여주는 종합 가이드다. 이 다이어그램은 마크다운 기능을 세 개의 주요 범주로 구분한다. 첫째, 모든 플랫폼에서 지원되는 기본 마크다운(파란색), 둘째, Quarto와 Pandoc에 특화된 고급 마크다운(보라색), 셋째, 현재 문서에서 다루지 않았지만 고려해볼만한 추가 요소들(주황색)이다.

기본 마크다운의 핵심은 단순함에 있다. YAML 메타데이터로 문서의 기본 정보를 설정하고, # 기호로 제목의 계층 구조를 표현한다. *와 **를 사용한 텍스트 서식은 직관적이며, 백틱(`)으로 감싼 코드는 즉시 구분된다. 링크는 [텍스트](URL) 형태로 작성하며, 목록은 -나 번호를 사용해 간단히 표현할 수 있다. 인용문(>)과 수평선(---)까지, 이 모든 기능은 텍스트 자체만으로도 충분히 의미를 전달한다.

다이어그램 오른쪽의 출력 예시들은 이러한 마크다운 문법이 실제로 어떻게 렌더링되는지 보여준다. 화살표로 연결된 입력과 출력은 마크다운의 핵심 원리인 WYSIWYM(What You See Is What You Mean)을 시각적으로 구현한다. 구조화된 텍스트가 아름다운 문서로 변환되는 과정이 명확하게 드러난다.

고급 마크다운 기능들은 학술 문서 작성에 필수적이다. 수식 표현, 표 작성, 그림 삽입, 참고문헌 관리 등은 다음 절에서 자세히 다룰 예정이다. 또한 다이어그램의 주황색 영역에 표시된 GitHub Flavored Markdown의 작업 목록, 취소선, 이모지 등의 추가 기능들도 현대적인 문서 작성 환경에서는 점점 중요해지고 있다.

6.3.1 제목

마크다운에서는 # 기호를 사용하여 문서 제목 수준을 결정한다. # 기호를 한 개부터 여섯 개까지 사용하며, # 기호 개수가 많아질수록 제목 수준은 낮아지고, 텍스트 크기도 작아진다. 예를 들어, 어떤 문서가 첫 번째 큰 제목으로 들어가며와 방법론을 갖고 있고, 방법론 아래에는 두 번째 수준 제목인 동적 인구 모형이 있다면, 다음과 같이 작성한다.

# 들어가며
# 방법론
## 동적 인구 모형

6.3.2 텍스트 서식

마크다운으로 쉽게 이탤릭, 굵게, 이탤릭 굵게 글씨체를 지정할 수 있다. (하지만, 모든 마크다운표준이 이러한 서식구문에 동의하지는 않는다). 글꼴에 서식 적용은 * 혹은 _을 사용해서 적용한다. 따라서 다음 명령어는 모두 동등하다.

*이탤릭* 그리고 _이탤릭_
**굵게** 그리고 __굵게__
***이탤릭 굵게.*** 그리고 ___이탤릭 굵게.___

이탤릭 그리고 이탤릭
굵게 그리고 굵게
이탤릭 굵게. 그리고 이탤릭 굵게.

6.3.3 코드

코드는 백틱으로 텍스트를 감싸 인라인(inline) 으로 작성하거나,

프로그램 실행은 `python helloworld.py`으로 프롬프트를 작성한다.

프로그램 실행은 python helloworld.py으로 프롬프트를 작성한다.

혹은 백틱(`) 3개나 틸드(~) 3개를 한줄씩 코드 아래위에 넣어 코드블록을 구분한다.

```
이것이
R, 파이썬
코드블록 입니다.
```

이것이
R, 파이썬
코드블록 입니다.

코드블록 첫번째 행에, 프로그래밍 언어 를 명세하는 것도 가능하다. 프로그래밍 언어를 특정하면 해당 언어 키워드를 강조하는 색상으로 표시되어 가독성이 높아진다.

`python` 으로 언어를 명세한다:

```python
for i in xrange(5):
  print "This is line " + str(i) + " of this useless loop.\n"
```

훌륭해 보입니다!

python 으로 언어를 명세한다:

for i in xrange(5):
  print "This is line " + str(i) + " of this useless loop.\n"

훌륭해 보입니다!

6.3.4 링크

하이퍼링크를 작성하는 방식은 두가지가 있다. 첫번째는 인라인 으로 작성하는 것으로 [텍스트](http://link.tld) 방식을 사용한다. 두번째는 명칭을 지정한 표식을 사용하는 방식이다. 예를 들어,

이것은 [첫번째 링크], 다음은 또다른 [두번째 링크][link2] 혹은 [세번째 링크](http://link.1)

[첫번째 링크]: http://link.1
[link2]: http://link.2

이것은 첫번째 링크, 다음은 또다른 두번째 링크 혹은 세번째 링크

명칭을 지정한 표식을 사용하는 방식에 대한 구문은 [텍스트][표식] 이 먼저 나오고 나서, [표식]: http://link 표식링크가 문서 다음에 뒤따라 나온다. [표식]이 없는 경우 [텍스트]: link 방식으로 동작하게 된다.

6.4 고급 마크다운

학술 논문 작성 시, 단순 텍스트 이상의 다양한 요소들이 포함된다. 특히, 참고문헌, 표, 그림, 수식은 학술 논문에서 매우 중요한 문서구성 요소다. 이러한 요소들을 추가하는 방법을 살펴볼 때, 특히 유의해야 할 점은 팬독을 사용할 때 \LaTeX 명령어가 다른 형식으로 변환되는 과정에서도 그대로 적용된다는 것입니다. 이런 점이 수식 사용을 상당히 단순화시킨다.

6.4.1 수식

수식을 \(\LaTeX\) 구문으로 작성할 수 있다. 예를 들어, 아래 코드 덩어리는 적법한 마크다운 구문이다.

The equation for a polynomial function is $y(x) = ax^2 + bx +c$.

그리고 다음도 마크다운과 \(\LaTeX\) 코드가 섞여 있지만 적법한 구문이다.

The sum of a vector of numbers ($\mathbf{v}$) is noted

\begin{equation}
\sum_{x=1}^n\mathbf{v}_i
\end{equation}

6.4.2 표

마크다운의 한 가지 단점은 표 생성에 대한 지원이 제한적이라는 점이다. 비록 \(\LaTeX\) 구문을 사용하는 것이 가능하지만, 상대적으로 간단히 표를 작성하는 방법은 있다.

|  교과목  |    담당자 |     선수 교과목 |
|:---------|:-----------|------------------:|
| 마크다운 | 홍길동  | 쉘, Git, Makefiles |

상기 구문을 적용하면 다음에 나온 표가 작성된다.

교과목	담당자	선수 교과목
마크다운	홍길동	쉘, Git, Makefiles

표 6.1: 고급 마크다운 표작성 사례

표를 구성하는 요소가 몇개 있다. 첫번째 줄은 헤더 로 표제목, 두번째 줄은 정렬, 그 다음 줄이 표에 기술되는 내용물 이 된다. 칼럼은 파이프(|) 기호로 구분한다. 파이프를 수직방향으로 정렬할 필요는 없다. (하지만, 원문서코드를 읽을 때 가독성을 상당히 높힌다 – 대부분의 편집기에서 이런 기능을 플러그인으로 지원한다)

기본디폴트 설정으로 칼럼은 좌측 정렬 된다. 정렬을 명세하려면, 두번째 행에 다음과 같이 : 세미콜론을 사용해서 지정한다.

|   좌측정렬  |  중앙정렬  |    우측정렬   | 기본 설정 (좌측) |
|:-------------|:--------:|--------------:|:---------------|
| `:---`       |  `:--:`  |        `---:` | `----`         |

상기 구문을 적용하면 다음에 나온 표가 작성된다.

좌측정렬	중앙정렬	우측정렬	기본 설정 (좌측)
:---	:--:	---:	----

6.4.3 그림

그림은 마크다운에서 잘 지원되고 있다. 표기법은 링크에 사용된 표기법을 따르지만, 느낌표(!)를 앞에 위치시킬 필요가 있다. 예를 들어,

![소프트웨어 카펜트리 로고](images/swc-logo-blue.png)

상기 구문을 적용하면 다음과 같이 그림이 삽입된다.

그림 6.3: 소프트웨어 카펜트리 로고

다른 방법으로 다음과 같이 그림 삽입 구문을 작성해도 된다.

![소프트웨어 카펜트리 로고\label{f:swc}][swc]
[swc]: http://swcarpentry.github.io/modern-scientific-authoring/assets/img/swc-logo-blue.svg

\(\LaTeX\) 명령어, \label{f:swc} 라벨을 넣은 것에 주목한다. \autoref{f:swc}를 사용해서 텍스트에 그림을 참조하게 한다. \(\LaTeX\) autoref 팩키지는 놀랍도록 유용한데, 참조하는 객체 유형을 자동 식별해서, 사람이 관여하지 않고도 Fig. 1, Tab. 2, Eqn. 3, 혹은 기타 필요한 것을 자동으로 완성시킨다.

6.4.4 참고문헌

학술논문에서 요구하는 최종 요건은 참고문헌이다. pandoc과 pandoc-citeproc 확장기능을 통해 마크다운은 참고문헌 기능을 매우 우아하게 처리한다. pandoc 서지관리 모듈은 다양한 형식으로부터 인용을 불러올 수 있다. 최초 CSL JSON 와 CSL YAML로 설계되어, BibT_EX과 RIS도 수용한다.

참고문헌을 참조하는 방식은 인용키, @CitationKey를 이용한다. 예를 들어, BibT_EX 라이브러리에 다음 참고문헌이 담겨 있다면:

@ARTICLE{thom99,
    title = {The raw material for coevolution},
    journal = {Oikos},
    author = {Thompson, John N},
    number = {1},
    volume = {84},
    year = {1999},
    pages = {5--16},
}

텍스트에 @thom99 을 넣어 참조한다. 모든 참고문헌 관리 소프트웨어(Zotero, Mendeley, EndNote 등)를 사용해서 BibTeX, CSL JSON 등 Quarto에서 지원하는 형식으로 내보내기 할 수 있다.

참고문헌을 ([@John2012; @Jack2014])와 같이 결합할 수 있고, 인라인 으로 “저자-년도” 스타일을 지정해서 사용하고 있다면 @Doe2013 작성하게 되면 Doe (2013)와 같이 표시되고, 괄호를 사용해서 [@Doe2013]와 같이 사용하면 (Doe, 2013) 산출물을 얻게 된다. 또한, 텍스트를 추가하는 것도 가능하다: [검토를 위해 @Billy2015 참조] 와 같이 작성하면, (검토를 위해 Billy et al., 2015 참조)와 같이 나타난다. 참고문헌은 문서 끝에 자동으로 삽입되며, CSL(Citation Style Language) 파일을 통해 다양한 저널 스타일로 서식을 변경할 수 있다.

6.5 컴파일

지금까지 작성원고는 말그대로 마크다운 자체 파일(확장자가 mkd, .markdown, .pandoc)이다. 마크다운을 뭔가 다른 것으로 변환할 필요가 있다. 대체로 PDF, 혹은 텍스트 프로세서에서 볼 수 있는 문서형식이 된다.

6.5.1 팬독(pandoc) 으로 컴파일

팬독(pandoc) 프로그램이 이런 작업을 수행하는 나름 최적의 도구다.(물론, jekyll 처럼 웹에 특화된 도구도 존재한다.) 대부분의 명령-라인 도구와 마찬가지로, pandoc은 입력값으로 파일과 일부 선택옵션 플래그를 순차적으로 받는다. pandoc을 호출하는 기본방식은 다음과 같다:

pandoc input.ext -o output.ext

그림 6.4: Pandoc 컴파일 및 렌더링 프로세스

그림 6.4 는 Pandoc의 놀라운 변환 능력을 한눈에 보여준다. 하나의 마크다운 파일에서 시작하여 150여 가지가 넘는 다양한 출력 형식으로 변환할 수 있다는 것이 Pandoc의 핵심 가치다. 이 다이어그램에서 볼 수 있듯이, Pandoc 엔진은 4단계 프로세스를 거쳐 작동한다: 파싱(Parsing) → AST 변환 → 템플릿 적용 → 포맷 렌더링.

입력 파일은 .md, .markdown, .pandoc 등의 확장자를 가질 수 있으며, YAML 메타데이터와 사용자 정의 템플릿도 함께 처리된다. 출력 형식은 용도에 따라 다섯 가지 주요 카테고리로 구분된다. 문서 형식에는 PDF, Word, ODT, RTF가 포함되어 일반적인 문서 작성과 공유에 적합하다. 웹 형식은 HTML, EPUB, JSON 등으로 온라인 게시와 전자책 제작을 지원한다. 프레젠테이션 형식으로는 RevealJS, Beamer, PowerPoint가 있어 학회 발표나 강의 자료 제작이 가능하다. 학술 형식인 LaTeX, ConTeXt는 논문 작성에 특화되어 있으며, 기타 형식들은 특수한 목적을 위한 변환을 담당한다.

다이어그램 하단의 명령어 예시들은 실제 사용법을 보여준다. 단순한 pandoc manuscript.md -o manuscript.pdf 명령어로 PDF를 생성할 수 있고, --template, --toc, --bibliography 같은 옵션을 추가하여 더욱 정교한 문서를 만들 수 있다. 이러한 유연성이 바로 Pandoc을 ’문서 변환의 스위스 군용 칼’이라고 부르는 이유다.

6.5.2 템플릿과 고급 활용

Pandoc의 진정한 힘은 템플릿(Template) 시스템에서 발휘된다. 템플릿은 마크다운 내용이 최종 문서에서 어떻게 배치되고 스타일링될지 정의하는 구조적 지침서다. YAML 메타데이터의 변수들이 템플릿의 플레이스홀더와 연결되어 개인화된 문서를 생성한다.

템플릿명	설명	특징
학술 논문
Eisvogel	GitHub에서 많은 별점 받은 LaTeX PDF 템플릿	깔끔한 레이아웃, 코드 하이라이팅 지원
IEEE Template	IEEE 학회 논문 형식	공식 IEEE 스타일, 이공계 표준
Academic	대학 논문 작성에 특화된 템플릿	학위논문, 연구보고서용
비즈니스
Corporate	회사 보고서와 제안서용	기업 브랜딩, 전문적 디자인
Letter	공식 서신 작성용	공문서, 공식 서신 형식
Resume	이력서 작성 전용	개인 브랜딩, 깔끔한 레이아웃

표 6.2: 팬독 인기 템플릿

템플릿 사용 예시

사용자 정의 템플릿을 적용하려면 --template 옵션을 사용한다:

# Eisvogel 템플릿으로 PDF 생성
pandoc paper.md --template=eisvogel.latex -o paper.pdf

# 사용자 정의 HTML 템플릿 적용
pandoc report.md --template=custom.html -o report.html

템플릿 변수는 YAML 헤더에서 설정할 수 있다:

---
title: "연구 보고서"
author: "김연구자"
institute: "한국대학교"
logo: "logo.png"
colorlinks: true
---

6.5.3 핵심 옵션 플래그

마크다운 기본 문법을 익혔다면 이제 Pandoc의 진정한 힘을 경험할 차례다. 단순한 pandoc input.md -o output.pdf 명령어도 훌륭하지만, 옵션 플래그를 활용하면 전혀 다른 차원의 문서를 만들 수 있다.

Pandoc의 옵션 철학은 “작은 조각들의 조합으로 큰 힘을 만든다”는 Unix 철학을 따른다. 150개가 넘는 옵션이 있지만, 각각은 단순하고 명확한 역할을 가지고 있다. 중요한 것은 이들을 어떻게 조합하느냐다. 마치 요리에서 기본 재료들을 조합해 다양한 요리를 만들어내는 것처럼, Pandoc 옵션들도 상황과 목적에 맞게 조합해서 사용한다.

실무에서의 접근 전략은 명확하다. 모든 옵션을 암기하려 하지 말고, 자신의 작업 패턴에 맞는 핵심 옵션들을 먼저 익히는 것이다. 대부분의 사용자는 전체 옵션의 10% 정도만 알아도 90%의 작업을 처리할 수 있다. 나머지는 필요할 때 찾아보면 된다.

Pandoc의 150개가 넘는 옵션 중에서 실무에서 가장 자주 사용하는 핵심 옵션들을 엄선했다. 이 10가지만 제대로 알아도 대부분의 문서 변환 작업을 효과적으로 처리할 수 있다.

우선순위	옵션	기능	활용도
★★★	`-o, --output`	출력 파일명과 형식 지정	모든 변환 작업
★★★	`--standalone`	완전한 독립 문서 생성	HTML, LaTeX 필수
★★★	`--toc`	목차 자동 생성	긴 문서, 보고서
★★☆	`--number-sections`	섹션 자동 번호 매기기	학술논문, 기술문서
★★☆	`--bibliography`	참고문헌 파일 지정	학술 출판
★★☆	`--csl`	인용 스타일 적용	논문 형식 준수
★☆☆	`--template`	사용자 템플릿 적용	조직 표준 양식
★☆☆	`--filter`	Pandoc 필터 확장	고급 변환 기능
★☆☆	`--metadata`	문서 메타데이터 설정	제목, 저자 정보
★☆☆	`--pdf-engine`	PDF 엔진 지정	한글 문서 (XeLaTeX)

표 6.3: 실무 필수 Pandoc 옵션 10선

표 6.3 의 우선순위는 실무 경험을 바탕으로 한 것이다. ★★★는 거의 모든 프로젝트에서 사용하는 필수 옵션, ★★☆는 전문적 문서 작성시 필요한 옵션, ★☆☆는 특정 상황에서 유용한 고급 옵션이다.

옵션 활용 전략

단계적 학습 접근법이 효과적이다. 처음에는 기본 3종 세트(-o, --standalone, --toc)로 시작해서 문서의 복잡도에 따라 점진적으로 옵션을 추가해나가면 된다.

학술 논문을 작성한다면 참고문헌 관련 옵션(--bibliography, --csl)이 필수가 되고, 기업 보고서라면 템플릿 옵션(--template, --metadata)에 집중하게 된다. 블로그나 웹 문서는 CSS와 관련된 옵션들이 중요해진다.

가장 중요한 것은 옵션 간의 시너지를 이해하는 것이다. 예를 들어 --toc와 --number-sections는 함께 사용할 때 진가를 발휘하고, --bibliography와 --csl은 한 쌍으로 움직인다. 이런 조합의 묘미를 알면 Pandoc을 훨씬 효과적으로 활용할 수 있다.

🧩 출력 형식별 필수 옵션 매트릭스

같은 마크다운 파일이라도 출력 형식에 따라 필요한 옵션이 달라진다. PDF는 한글 처리를 위해 XeLaTeX 엔진이 필요하고, HTML은 완전한 웹 페이지를 만들기 위해 --standalone 옵션이 필수다. DOCX는 회사 템플릿을 적용하려면 --reference-doc 옵션을 알아야 한다.

이런 형식별 특성을 이해하면 “왜 안 되지?”라는 의문을 해결할 수 있다. 많은 초보자들이 겪는 문제의 대부분은 출력 형식에 맞지 않는 옵션을 사용하거나, 꼭 필요한 옵션을 빠뜨렸기 때문이다.

형식	필수옵션	권장옵션	주의사항
PDF	--pdf-engine=xelatex	--toc, --number-sections	한글 지원시 XeLaTeX 필수
HTML	--standalone	--toc, --css	완전한 HTML 문서 생성
DOCX	--reference-doc	--toc	스타일 템플릿 준비 권장
RevealJS	-t revealjs --standalone	--variable theme	프레젠테이션 전용 마크다운
EPUB	--epub-cover-image	--toc, --metadata	표지 이미지와 메타데이터 중요

표 6.4: 출력 형식별 필수 옵션 가이드

🍳 실전 활용 레시피

옵션들을 어떻게 조합해야 할지 감이 안 잡힌다면, 이미 검증된 조합들을 참고해보자. 이런 레시피 접근법은 처음에는 따라 하기만 하다가, 익숙해지면 자신만의 변형을 만들어가는 학습 방법이다.

학술 논문용 (PDF)

pandoc manuscript.md --pdf-engine=xelatex --toc --number-sections \
  --bibliography=refs.bib --csl=apa.csl -o paper.pdf

회사 보고서용 (DOCX)

pandoc report.md --reference-doc=template.docx --toc \
  --metadata title="보고서" -o report.docx

웹 문서용 (HTML)

pandoc article.md --standalone --toc --css=style.css \
  --metadata title="제목" -o article.html

프레젠테이션용 (RevealJS)

pandoc slides.md -t revealjs --standalone \
  --variable theme=white -o presentation.html

각 레시피의 핵심은 목적에 맞는 필수 옵션들의 조합이다. 학술논문은 참고문헌과 번호 매기기가, 웹문서는 스타일링이, 프레젠테이션은 테마가 중요하다. 이런 패턴을 이해하면 새로운 상황에서도 적절한 옵션을 선택할 수 있다.

6.5.4 차세대 문서 작성 시스템

그림 6.5: Quarto 개념도

그림 6.5 에서 보듯이 Quarto는 Pandoc을 기반으로 한 오픈소스 과학기술 출판 시스템이다. 복잡한 Pandoc 명령줄 옵션들을 YAML 설정으로 간편하게 관리할 수 있게 해주는 것이 핵심이다.

가장 큰 차이점은 계산 가능한 문서(Computational Document) 작성이다. 일반 마크다운과 달리 .qmd 파일 안에서 R, Python, Julia 코드를 직접 실행하고 그 결과를 문서에 자동으로 포함시킬 수 있다. 데이터 분석 결과가 바뀌면 문서도 자동으로 업데이트되는 진정한 재현가능한 연구(Reproducible Research)가 가능해진다.

# Pandoc 직접 사용 시
pandoc paper.md \
  --toc \
  --number-sections \
  --bibliography=refs.bib \
  --csl=apa.csl \
  -o paper.pdf

# Quarto 사용 시 (YAML 헤더)
---
title: "연구 논문"
format: pdf
toc: true
number-sections: true
bibliography: refs.bib
csl: apa.csl
---

후속 장에서는 이러한 Quarto가 어떻게 마크다운 기반 문서 코드화(Document as Code) 패러다임을 완성하는지 자세히 살펴볼 것이다.

💭 생각해볼 점

마크다운은 ’적을수록 많아진다’는 역설을 보여준다. 최소한의 문법으로 최대한의 표현력을 얻는다. 하나의 # 기호가 제목이 되고, 하나의 *이 강조가 되고, 하나의 []()가 링크가 된다. 이 단순함 속에 숨어있는 철학은 무엇일까?

플레인 텍스트라는 원시적 형태가 오히려 AI 시대에 가장 미래적인 선택이 되는 이유는 무엇일까? 바이너리 포맷에 갇힌 워드 문서는 AI가 읽기 어렵지만, 마크다운은 AI와 인간이 모두 읽고 쓸 수 있는 공통 언어다. ChatGPT에게 “마크다운으로 작성해줘”라고 요청하면 즉시 이해하고 응답한다. 이것이 우연일까?

WYSIWYG(What You See Is What You Get)에서 WYSIWYM(What You See Is What You Mean)으로, 이제는 WYAIWYM(What You Ask AI Is What You Mean)²의 시대로 진화하고 있다. 우리는 더 이상 서식을 직접 조작하지 않는다. AI에게 의미를 전달하면, AI가 적절한 마크다운으로 변환하고, Quarto가 아름다운 문서로 렌더링한다.

문서는 이제 ’대화’가 되고 있다. 인간과 AI가 마크다운이라는 공통 언어로 대화하며 문서를 함께 만들어간다. 버전 관리 시스템은 이 대화의 기록을 남기고, 협업자들은 언제든 이 대화에 참여할 수 있다.

마크다운의 진정한 힘은 단순함이 아니라 연결성에 있다. 텍스트 파일이라는 가장 기본적인 형태로 존재하면서도, 무한한 변화와 확장이 가능하다. Pandoc이라는 강력한 변환 엔진을 통해 하나의 마크다운 파일이 수백 가지 형식으로 변신할 수 있다는 것은 진정 놀라운 일이다.

하지만 Pandoc의 수많은 옵션과 복잡한 명령어를 매번 기억하고 입력하는 것은 현실적으로 어렵다. 여기서 등장하는 것이 바로 Quarto다. 다음 장에서는 Quarto가 어떻게 Pandoc의 강력함을 간편한 인터페이스로 포장하여, 마크다운 기반의 계산 문서(Computational Document)를 만들 수 있게 하는지 살펴볼 것이다. Document as Code의 진정한 구현체를 만나보자.

---

1. WYAIWYM은 WYSIWYG, WYSIWYM의 연장선상에서 AI 시대 문서 작성 패러다임을 설명하기 위해 사용하는 개념적 표현이다. 표준화된 학술 용어는 아니지만, “사용자가 AI에게 전달하는 의도가 곧 원하는 결과가 된다”는 새로운 문서 작성 방식을 나타낸다.

2. 이 용어는 공식적인 학술 표준은 아니지만, AI 도구를 활용한 새로운 문서 작성 패러다임을 설명하는 개념적 표현이다. 예를 들어, “논문의 방법론 섹션을 마크다운으로 작성해줘”라고 ChatGPT에 요청하면, AI가 구조화된 마크다운 텍스트로 변환해준다.