Positron에서 시각적 편집

개요

Quarto VS Code 확장에는 표, 인용, 상호 참조, 각주, div/span, 정의 목록, 속성, 원시 HTML/TeX 등을 포함해 Quarto의 모든 마크다운 문법을 지원하는 시각적 마크다운 편집기가 포함되어 있습니다:

Positron에서 `libraries.qmd` 문서를 시각적 편집 모드로 열어 둔 모습. 부제와 항목 목록이 서식 적용되어 있고, 문서 상단에 시각적 편집 도구 모음이 보입니다.

시각 모드와 소스 모드 사이를 언제든 전환할 수 있으며 두 모드에서 동시에 문서를 편집할 수도 있습니다. 시각 모드와 소스 모드를 전환하려면 다음을 사용하세요:

⇧⌘ F4 단축키 사용.
문서 어디서든 컨텍스트 메뉴 사용:
Edit in Visual Mode와 Edit in Source Mode 명령 사용:
편집기 메뉴 사용:

도구 모음의 Source/Visual 버튼 사용:

파일 탐색기에서 .qmd 문서를 마우스 오른쪽 버튼으로 클릭하고 Open With… 명령을 선택하면, 파일을 열 편집기를 선택할 수 있습니다:

이 메뉴에는 .qmd 파일의 기본 편집기를 설정하는 옵션도 있습니다. 시각 모드로 주로 편집하고 가끔 소스 모드로 전환하고 싶다면 이 옵션을 사용하세요.

키보드 단축키

시각 모드는 전통적인 키보드 단축키(예: 굵게에 ⌘ B)와 마크다운 단축키(마크다운 문법 직접 입력)를 모두 지원합니다. 예를 들어 **bold** 텍스트를 별표로 감싸거나 ##을 입력한 뒤 스페이스를 눌러 2단계 제목을 만들 수 있습니다.

사용 가능한 키보드 및 마크다운 단축키는 다음과 같습니다:

명령	키보드 단축키	마크다운 단축키
굵게	`⌘ B`	`bold`
기울임	`⌘ I`	`italic`
코드	`⌘ D`	`code`
취소선		`~~strike~~`
아래 첨자		`~sub~`
위 첨자		`^super^`
제목 1	`⌥⌘ 1`	`#`
제목 2	`⌥⌘ 2`	`##`
제목 3	`⌥⌘ 3`	`###`
제목 속성		`{#id .class}`
링크	`⌘ K`	`<href>`
인용 블록		`>`
코드 블록	`⇧⌘ \`	```
코드 셀	`⌥⌘ I`	```{python}
원시 블록		```{=html}
Div		`:::`
글머리 목록		`-`
번호 목록		`1.`
촘촘한 목록	`⌥⌘ 9`
체크 목록		`[x]`
이모지		`:smile:`
정의		`:`
줄바꿈 없는 공백	`⌃ Space`
강제 줄바꿈	`⇧ Enter`
단락	`⌥⌘ 0`
이미지	`⇧⌘ I`
각주	`⇧⌘ F7`
인용	`⇧⌘ F8`	`[@`
표	`⌥⌘ T`
편집 주석	`⇧⌘ C`
모두 선택	`⌘ A`
서식 지우기	`⌘ \`
속성 편집	`F4`

마크다운 단축키를 의도한 것이 아니라면 백스페이스 키를 눌러 효과를 되돌릴 수 있습니다.

무엇이든 삽입

⌘ / 단축키를 사용하면 거의 모든 항목을 삽입할 수 있습니다. 단축키를 실행한 다음 삽입하려는 내용을 입력하세요. 예:

커서가 있는 텍스트 줄에서 '/lis'가 입력되어 있고, 아래에 'Bullet List', 'Numbered List', 'Definition List' 옵션이 세로로 나열된 드롭다운 메뉴가 있습니다. 각 항목 제목은 굵게 표시되며 왼쪽에 작은 아이콘, 아래에 연한 회색 설명이 있습니다.

$커서가 있는 텍스트 줄에서 '/ma'가 입력되어 있고, 아래에 'Inline Math', 'Display Math', 'Image...' 옵션이 세로로 나열된 드롭다운 메뉴가 있습니다. 각 항목 제목은 굵게 표시되며 왼쪽에 작은 아이콘, 아래에 연한 회색 설명이 있습니다.$

(위처럼) 줄의 시작 부분에 있다면 /만 입력해도 단축키를 호출할 수 있습니다.

편집기 도구 모음

편집기 도구 모음에는 가장 자주 사용하는 서식 명령 버튼이 포함되어 있습니다:

Format, Insert, Table 메뉴에는 추가 명령이 있습니다:

Format	Insert	Table

편집기 옵션

시각적 편집기의 동작을 구성할 수 있는 다양한 Positron 옵션이 있습니다. 설정 패널에서 quarto.visualEditor로 필터링하면 해당 옵션을 찾을 수 있습니다:

옵션을 통해 모양(글꼴 크기, 콘텐츠 폭 등), 마크다운 출력(예: 열 줄바꿈), 맞춤법 검사, 목록의 기본 간격 등을 구성할 수 있습니다.

Zotero 인용

Zotero는 인기 있는 무료 오픈 소스 참고문헌 관리자입니다. Quarto 시각적 편집기는 Zotero와 직접 통합되어 Insert Citation 명령으로 Zotero 라이브러리의 참고문헌을 사용할 수 있습니다:

'Insert Citation' 대화상자. 'My Library' 옵션이 선택되어 있습니다. 오른쪽 섹션 상단의 검색 바는 비어 있지만, 검색 결과 영역에는 Zotero 참고문헌 관리자 라이브러리의 항목이 채워져 있습니다. 각 검색 결과 아이콘에는 해당 항목이 Zotero 라이브러리에서 왔음을 나타내는 작은 'Z'가 오른쪽 아래에 표시됩니다.

Zotero 참고문헌은 시각적 편집기 자동 완성에도 자동으로 표시됩니다:

Zotero 항목은 참고문헌 목록의 항목과 함께 작은 “Z” 로고가 겹쳐 표시됩니다. Zotero에서 인용을 삽입했는데 참고문헌에 없는 항목이면 자동으로 참고문헌에 추가됩니다.

데스크톱에서 Positron와 Zotero를 함께 실행 중이라면 Zotero 라이브러리 연결에 추가 설정이 필요하지 않습니다. 하지만 웹을 통해 Zotero 라이브러리에 접근하려면 몇 가지 추가 단계가 필요합니다(자세한 내용은 Zotero Web API 섹션 참고).

그룹 라이브러리

Zotero Groups는 클래스에서 컬렉션을 공유하거나 동료와 프로젝트를 밀접하게 협업할 수 있는 강력한 방법입니다. 기본적으로 Zotero Group Libraries는 Insert Citation 대화상자나 인용 자동 완성에 포함되지 않습니다. 하지만 Quarto > Zotero: Group Libraries 옵션으로 그룹 라이브러리를 하나 이상 활성화할 수 있습니다(전역 또는 워크스페이스별):

그룹 라이브러리를 목록에 추가하면 동기화가 수행되고, Insert Citation 대화상자에 해당 라이브러리가 표시됩니다. 표시되지 않으면 설정하려는 그룹 라이브러리 이름의 철자가 정확한지 다시 확인하세요(Zotero에서 복사해 붙여넣으면 확실합니다).

Zotero Web API

Zotero가 로컬에 설치되어 있지 않더라도 Zotero Web API를 통해 라이브러리에 접근할 수 있습니다(웹 Zotero 계정이 있고 라이브러리가 계정과 동기화되어 있어야 합니다).

데스크톱에서 Positron를 사용하는 경우 일반적으로 Zotero도 데스크톱에서 실행해 로컬 라이브러리에 접근하는 것이 더 쉽습니다. 다만 원한다면 데스크톱에서 Positron를 사용하면서 Zotero 웹 라이브러리에 접근하는 구성도 가능합니다.

API 접근 키

Zotero 통합은 Zotero Web API를 사용하므로, 먼저 Zotero 계정을 만든 다음 Zotero가 데이터를 계정에 동기화하도록 설정해야 합니다. Zotero 환경설정의 Sync 탭에서 설정할 수 있습니다:

Zotero 환경설정의 Sync 탭.

라이브러리 동기화를 설정한 뒤에는 Zotero API Key를 만들어야 합니다:

Zotero의 'New Private Key' 섹션. 'Allow library access' 옵션이 선택되어 있습니다.

안내에 따라 새 접근 키를 만드세요. Group Libraries를 사용하려면 기본값을 변경해 그룹에 대한 읽기 전용 접근을 제공해야 합니다(위 그림 참고).

키를 생성한 뒤에는 반드시 키를 기록해 두세요(예: 클립보드에 복사하거나 영구적으로 저장). 다른 페이지로 이동하면 다시 볼 수 없습니다.

라이브러리 구성

마지막으로 Zotero 설정에서 로컬 라이브러리 대신 web Zotero 라이브러리를 사용하도록 지정하세요:

이후 Zotero Web API Key를 입력하라는 안내가 표시됩니다:

API 키를 입력하고 검증되면 Zotero 라이브러리의 초기 동기화가 수행됩니다. 이후 Zotero에서 인용을 삽입할 수 있습니다.

Note

Zotero API 키를 변경해야 한다면 Quarto: Zotero - Connect Web Library 명령을 실행하면 됩니다. 웹 라이브러리를 강제로 동기화하려면 Quarto: Zotero - Sync Web Library 명령을 실행하세요(웹 라이브러리는 자동으로 동기화되므로 일반적으로 이 명령을 직접 사용할 일은 많지 않습니다).

마크다운 출력

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

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

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

처음에는 이런 동작이 번거롭게 느껴질 수 있지만, 시각적 편집 모드를 워크플로에 유용하게 쓰기로 했다면 Pandoc 방식과 동일하게 마크다운을 작성하는 쪽이 가장 좋습니다.

작성자 옵션

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

줄을 어떻게 감쌀지/줄바꿈할지(고정 열, 문장 단위 등).
각주를 어디에 쓸지(현재 단락 또는 섹션 아래, 혹은 문서 끝).
인라인 링크 또는 참조 링크 중 무엇으로 쓸지.

이 옵션은 다음 두 가지 방법 중 하나로 지정할 수 있습니다:

전역 또는 워크스페이스별 Positron 옵션으로 지정(마크다운 출력에 영향을 주는 옵션은 quarto.visualEditor.markdown으로 필터링해 찾을 수 있습니다).
문서 또는 프로젝트 수준 YAML에서 지정(아래 설명).

줄 감싸기

기본적으로 시각적 편집기는 줄 감싸기 없이 마크다운을 작성합니다(단락이 모두 한 줄을 차지). 그러나 특정 열(예: 72 또는 80)에서 줄바꿈을 삽입하거나 문장마다 줄바꿈을 삽입하고 싶다면, Positron 설정 편집기에서 quarto.visualEditor.markdownWrap 및 quarto.visualEditor.markdownWrapColumn 옵션을 사용할 수 있습니다.

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

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

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

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

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

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

참고문헌

기본적으로 참고문헌(각주 및 참조 링크)은 해당 각주가 등장하는 블록의 끝에 작성됩니다. 이 동작은 Positron 설정인 quarto.visualEditor.markdownReferences를 사용하거나, 문서/프로젝트 YAML의 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 옵션을 변경할 필요가 없습니다.

링크

기본적으로 링크는 인라인으로 작성되지만, 문서/프로젝트 YAML의 references 섹션에 links: true 옵션을 추가하면 각주처럼 내용 아래에 참조 링크로 작성할 수 있습니다. 예:

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

또는 Positron의 quarto.visualEditor.markdownReferenceLinks 옵션으로 참조 링크를 활성화할 수 있습니다.

알려진 제한 사항

시각적 편집에서 현재 지원되지 않는 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 메타데이터 블록을 파싱할 수 없습니다. 이러한 메타데이터 형식을 만나면 시각 모드는 경고와 함께 로드에 실패합니다.

참조 링크 지원은 문서/프로젝트 YAML의 editor: markdown: references: links 옵션이나 Positron의 quarto.visualEditor.markdownReferenceLinks 옵션으로 활성화할 수 있습니다. 참조 링크는 참조 위치 옵션(block, section, 또는 document)에 따라 작성됩니다.