마크다운 출력

개요

Quarto 시각적 편집기는 Pandoc을 사용해 마크다운을 생성합니다. 따라서 일부 경우 마크다운이 표준 Pandoc 관용구에 맞게 재작성됩니다. 예를 들어 Pandoc은 목록 항목 뒤에 3개의 공백을 삽입하고, 마크다운 문법에 사용될 수 있는 문자를 자동으로 이스케이프합니다.

Pandoc이 생성한 마크다운은 사용자 스타일과 다를 수 있으며, 예를 들어 다음과 같은 규칙이 있습니다:

_text_ 대신 *text* 사용
백틱 코드 블록은 ``` {.md} 형태로 작성(```md 대신)
속성이 없는 백틱 코드 블록은 4칸 들여쓰기 코드 블록으로 렌더링
가로 구분선은 문서 전체 너비의 대시로 작성
일반 링크는 https://yihui.org 대신 <https://yihui.org>로 작성
글머리/번호 목록은 항목 내용 앞에 추가 들여쓰기 사용
인용 블록의 각 줄에 인용 문자(>)가 포함됨
표 캡션은 표 위가 아니라 아래에 작성됨
여러 줄 HTML 및 TeX 블록은 명시적인 원시 속성을 사용함(예: ```{=tex})
인라인 각주는 단락 바로 아래의 각주로 대체됨
중첩 div는 속성이 구분되는 한 모든 수준에서 ::: 사용
번호 없는 섹션은 {-} 대신 {.unnumbered}로 지정됨
마크다운 문법에 사용되는 문자(예: *, _, #)는 항상 이스케이프됨

처음에는 이런 동작이 번거롭게 느껴질 수 있지만, 시각적 편집 모드를 워크플로에 유용하게 쓰기로 했다면 Pandoc 방식과 동일하게 마크다운을 작성하는 쪽이 가장 좋습니다. 또한 소스 모드 구성을 통해 어떤 모드에서 편집하더라도 동일한 마크다운이 작성되도록 할 수도 있습니다.

작성자 옵션

마크다운 출력의 일부는 전역, 프로젝트, 파일 수준 옵션으로 사용자 정의할 수 있습니다. 예를 들면 다음과 같습니다:

줄을 어떻게 감쌀지/줄바꿈할지(고정 열, 문장 단위 등).
각주를 어디에 쓸지(현재 단락 또는 섹션 아래, 혹은 문서 끝).
소스 모드에서 저장할 때 시각 모드 마크다운 작성기를 사용할지 여부(두 모드에서 저장한 문서의 일관성 보장).

이 옵션은 R Markdown 전역 옵션 또는 프로젝트 옵션에서 설정할 수 있으며, 아래 설명처럼 YAML로 파일 단위 설정도 가능합니다.

줄 감싸기

기본적으로 시각적 편집기는 줄 감싸기 없이 마크다운을 작성합니다(단락이 모두 한 줄을 차지). 이는 RStudio의 마크다운 소스 편집 모드와 동일한 동작입니다.

하지만 특정 열(예: 72 또는 80)에서 줄바꿈을 삽입하거나 문장마다 줄바꿈을 삽입하고 싶다면 전역 또는 프로젝트 편집기 옵션으로 설정할 수 있습니다.

wrap 옵션을 사용해 문서 단위로 이 동작을 설정할 수도 있습니다. 예를 들어 72자마다 줄을 감싸려면 다음과 같이 설정합니다:

---
editor:
  markdown:
    wrap: 72
---

문장마다 줄바꿈을 삽입하려면 wrap: sentence를 사용하세요. 예:

---
editor:
  markdown:
    wrap: sentence
---

문장 단위 줄바꿈 알고리즘은 영어와 일본어 텍스트를 잘 처리하지만, 다른 언어의 문장 끝을 정확히 감지하지 못할 수 있습니다.

전역 줄 감싸기 옵션을 활성화한 경우 특정 문서에서 줄 감싸기를 끄려면 wrap: none을 사용하세요.

참고문헌

기본적으로 참고문헌은 해당 각주가 등장하는 블록 끝에 작성됩니다. references 옵션으로 이 동작을 변경할 수 있습니다.

예를 들어 블록이 아니라 섹션 끝에 참고문헌을 작성하려면 다음과 같이 설정합니다:

---
title: "My Document"
editor:
  markdown:
    references: 
      location: block
---

references 옵션의 유효한 값은 block, section, document입니다.

참고문헌 작성 동작은 전역 또는 프로젝트 편집기 옵션으로도 제어할 수 있습니다.

여러 마크다운 문서를 더 큰 작업으로 모으는 경우, 모든 문서에서 참고문헌 식별자가 고유하도록 만들고 싶을 수 있습니다(예: [^1]가 여러 번 등장하지 않도록). prefix 옵션으로 고유성을 보장할 수 있습니다. 예:

---
title: "My Document"
editor:
  markdown:
    references: 
      location: block
      prefix: "mydoc"
---

이렇게 하면 이 문서의 각주는 지정한 접두사(예: [^mydoc-1])를 사용해 작성되어 원고 전체에서 전역적으로 고유해집니다.

Quarto 책 프로젝트 안에 있다면 참고문헌 prefix가 자동으로 적용되므로 editor: markdown을 변경할 필요가 없습니다.

정규 모드

시각 모드와 소스 모드를 모두 사용하는 워크플로에서는 어떤 모드에서 편집하더라도 동일한 마크다운이 작성되도록 하고 싶을 수 있습니다. 이때 canonical 옵션을 사용할 수 있습니다. 예:

---
title: "My Document"
editor:
  markdown:
    wrap: 72
    references: 
      location: block
    canonical: true
---

canonical: true를 설정하면 시각 모드와 소스 모드의 편집 결과가 동일한 마크다운 출력으로 저장됩니다. 이는 버전 관리를 사용하면서 여러 작성자가 소스/시각 모드를 혼용하는 경우 특히 유용합니다.

알려진 제한 사항

시각적 편집에서 현재 지원되지 않는 Pandoc 마크다운 확장이 일부 있습니다. 자주 쓰이지 않는 확장이라 대부분의 문서에는 영향이 없겠지만, 참고할 만합니다.

Extension(s)	Example	Behavior
Inline footnotes	^[inline]	숫자 각주로 변환됨.
Footnote identifiers	[^longnote]	숫자 각주로 변환됨.
Example lists	(@) First example	일반 번호 목록으로 읽고/작성됨.
Auto-list numbers	#. First item	일반 번호 목록으로 읽고/작성됨.
Reference links	This is a [link]	일반 링크로 변환됨.
MultiMarkdown attributes	# Heading [id]	Pandoc 속성으로 변환됨.

시각적 편집기는 YAML이 아닌 제목 블록(예: 기존 스타일의 % 제목 또는 MultiMarkdown 제목)과 최상위가 아닌 YAML 메타데이터 블록을 파싱할 수 없습니다. 이러한 메타데이터 형식을 만나면 시각 모드는 경고와 함께 로드에 실패합니다.