How to organize markdown for quarto markdown

Quarto

Author

Jeong-Ho SEO

Published

April 6, 2026

Modified

Invalid Date

안녕하세요. 개인 작업을 하다 markdown file을 작성하는 스타일을 정리하고자, 본 페이지 글을 작성하게 되었습니다.
통계학과 컴퓨터공학 등 Data Science 분야에서는 프로그래밍과 함께 여러 문서를 작업하실텐데, 대개 아래와 같은 형식의 문법을 사용하실 것 같습니다.

Domain	Programming_Code	Documents	Both (Dynamic Document)
Stat	Python, R, SPSS, \(\ldots\)	markdown	jupyter notebook, R markdown
CS	Python, C++, \(\ldots\)	markdown	jypyter notebook

Background에 따라 다양한 언어와 tool을 사용하실 것 같아, 대표적인 언어만 기재하였습니다.

1 What is the Quarto markdown ?

제 경우 서울대학교 통계학과에서 개설된 2025s - 통계계산 (lectured by Prof. Jaeyong-Lee) 에서 quarto의 존재를 확인하게 되었습니다.
과제의 답안을 제출하는 과정에서 jupyter notebook, R markdown, quarto markdown 모두 허용하신다는 문구에서 발견하였는데, 그 당시 quarto가 무엇인가에 대하여 서칭을 하게 되었습니다.

결론적으로 말씀드리자면, quarto markdown은 R markdown의 후속작으로, 매우 유용한 tool이라고 생각합니다. quarto markdown을 사용하여 할 수 있는 것들은 Quarto website에서 확인하실 수 있습니다.

저는 주로

quarto markdown document (.qmd)
quarto page rendering (.qmd, github pages)

를 사용하고 있습니다.

quarto markdown (qmd)의 특징으로는

기존의 jupyter notebook (.ipynb), R markdown (.rmd)과 마찬가지로, code cell과 함께 markdown 문법을 사용하여 description 작성이 가능합니다.
기존의 R markdown(.rmd)와 유사하게, YAML header를 사용하여 형식화된 rendering이 가능합니다.
github pages를 사용하여 personal website를 제작할 수 있습니다. (기존 jekyll과 다른 방식)

따라서 장, 단점이 모두 명확합니다.

1.1 Strength

익숙한 markdown 문법으로 다양하게 customizing이 가능합니다.
또한 기존의 jupyter notebook, R markdown과 호환이 가능합니다. convert
더 상세한 YAML header 기능을 사용하여 .html, .pdf 문서를 생성할 수 있스비다.
HTML 문법이 익숙하지 않더라도, pandoc을 사용하여 quarto webpage를 만들 수 있습니다. (github pages)

1.2 Weekness

유일한 Main 단점은 pandoc을 통한 rendering 과정이 필수라는 점입니다. 주요한 issue로는,

markdown과 R markdown모두 미리보기를 통해 수식 등을 작업할 수 있지만, quaro markdown의 경우 불가능합니다. rendering 과정을 거쳐야 하기 때문입니다.
pandoc으로 convert를 사용하여 기존 문서(.ipynb, .rmd)를 .qmd로 변환할 시, code result 출력값은 .qmd문서에 포함되지 않습니다. 따라서 만약 running time이 매우 긴 code cell이 존재한다면, 모두 다시 실행한 후 변환됩니다.
pandoc이 quarto markdown을 parsing하는 방법이 더 까다로워, 종종 제대로 rendering이 되지 않는 issue가 빈번합니다.

하지만 위 단점들은 모두 해결이 가능하기 때문에, 본 문서에서는 어떻게 issue를 해결하는지에 대하여 다룹니다.

1.3 Problem 1. quarto markdown does not support Preview - Use Dynamic Document

형식상으로는 preview 기능을 지원하지만, 실제로는 preview를 할 때마다 새로 rendering을 해야합니다. 이러한 문제는 작업 생산성에 큰 영향을 끼칩니다.

따라서 저는 초기 작업은 quarto markdown으로 작성하지 않고, 다른 문서 (jupyter notebook, R markdown)을 사용하는 것을 강력히 추천드립니다.
제 경우 python이 주력 언어이기 때문에, jupyter markdown을 사용한 방법을 소개드리고자 합니다. (See below)

1.4 Problem 2. `convert` misses the results - Bypass using Dynamic Document

Dynamic documents로서 보통 jupyter notebook과 R markdown이 사용됩니다. 또한 각 문서 보두 여러 programming languages를 동시에 사용할 수 있지만, 보통 하나의 문서에는 하나의 프로그래밍 언어만 사용하시는 경우가 많습니다.

	jupyter notebook	R markdown
Main programming language	python	R

통계학과 인공지능 분야에서 가장 많이 사용되는 언어가 python이기 때문에, jupyter notebook을 기준으로 우회하는 방법을 소개드리겠습니다.

(코드 및 디버깅, description) filename.ipynb 작성
filename.ipynb \(\rightarrow\) filename.md
```
python -m jupyter nbconvert --to markdown filename.ipynb
```
터미널에서 위 코드를 입력하면, 동일한 directory에서 두 가지 파일이 생성됩니다.
- filename_files: code results 중 image가 있다면, 해당 images를 자동으로 저장합니다.
- filename.md: filename.ipynb의 markdown cell, code cell and code result가 모두 포함된 markdown file입니다.
- filename_files에 저장된 images의 경우 ![png](images_directory)로 편리하게 자동 변환됩니다.
filename.md \(\rightarrow\) filename.qmd
```
ren filename.md filename.qmd
```
다른 이름으로 바꾸고 싶으신 경우에는, ren filename.md new_filename.qmd로 입력하시면 됩니다. 혹은, 파일 탐색기에서 이름바꾸기를 통해 간편하게 .qmd로 변환이 가능합니다.
filename.qmd setting
- filename.qmd: YAML header 추가
- filename.qmd: code cell에서 {} 추가.: python 에서 {python} 으로 변환이 필요합니다.

Render to .html or .pdf

quarto render filename.qmd --to html    # qmd to html
quarto render filename.qmd --to pdf     # qmd to pdf

를 통하여 간편하게 rendering 할 수 있습니다.

참고로 terminal에서 작업할 때, filename에 space가 들어간다면, ” “로 감싸주어야 합니다.

추가적으로 pandoc를 사용하여 다른 문서도 rendering할 수 있습니다.

quarto render "filename.qmd" --to pdf
quarto render "filename.md" --to pdf
quarto render "filename.ipynb" --to pdf

위와 같이 .qmd, .md, .ipynb 등 모두 .pdf 및 .html로 render이 가능합니다. 다만 pandoc이 친절하지 않은 편이라, md와 .ipynb의 경우에는 기존의 다른 rendering 방식을 추천드립니다.

1.5 Problem 3. pandoc is not kind - Recommended markdown writing style for pandoc

마지막으로, Dynamic Document에서 추천드리는 markdown 문법 작성 스타일을 소개드리고자 합니다.
quarto markdown과 markdown은 상당수 같은 문법을 사용하지만, quarto file을 rendering하는 pandoc의 parsing 규칙과 YAML header의 차이에서 일부 다른점이 발생합니다.

1.5.1 Inline Elements - Maintain your style

Bold, italic, link 와 같은 요소들은 그대로 사용하셔도 무방합니다. 아래에서 소개드릴 Block Elements를 제외한 상당수가, 기존 markdown 문법과 동일하게 작동합니다.

1.5.2 Block Elements Rule - Surround with blank lines

pandoc은 Block Elements의 경우 앞, 뒤로 empty line을 요구합니다. 또한 YAML header가

---
Header
---

와 같이 ---를 사용하여 이루어지기 때문에, 구분선으로 ---을 사용하시면 에러가 발생합니다.

따라서 주의해야할 예제들을 아래에서 보여드리겠습니다.

1.5.3 Wrong examples

Bullet list (글머리 기호)
```
#, ##, ###
-
-
```
Blockquote (인용문)
```
abcd,...
> quote
efgh,...
```
Thematic Break (구분선)
```
ABCD,...
---
EFGH,...
```

1.5.4 Right examples

Bullet list (글머리 기호)
```
#, ##, ###

-
-
```
Blockquote (인용문)
```
abcd,...

> quote

efgh,...
```
Thematic Break (구분선)
```
ABCD,...
***
EFGH,...
```

최종적으로, 아래와 같은 markdown 작성 방식을 추천드립니다.

Bullet list (글머리 기호)
- 1., -, * 모두 앞, 뒤로 blank lines 추가.
- 특히 #, ##, ### 쓰는 경우 유의.
Blockquote (인용문)
- > 표현 사용 시 앞, 뒤로 blank lines 추가.
Thematic Break (구분선)
- --- 대신 *** 사용.
- 필수는 아니지만, 마찬가지로 앞, 뒤로 blank lines 권장.

이렇게 하여 선호하는 quarto markdown 문서 작성 방법에 대하여 다루었습니다.
작성 스타일에 관련된 문서이므로, 참고하셔서 생산성 증대에 기여가 되었다면 감사드립니다.

본 글은 markdown으로 작성하여 quarto markdown으로 변환하였습니다. 이후 간단히 #, ##, ### 정도만 조정하였습니다. markdown으로 작성한 글은 markdown_written 에서 보실 수 있습니다.